[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Convert README.org to plain text README while installing package

From: Protesilaos Stavrou
Subject: Re: Convert README.org to plain text README while installing package
Date: Tue, 07 Jun 2022 13:50:31 +0300
User-agent: Notmuch/0.36 (https://notmuchmail.org) Emacs/29.0.50 (x86_64-pc-linux-gnu)

Hello Alan, Tim, everyone,

> From: Alan Mackenzie <acm@muc.de>
> Date: Mon, 06 Jun 2022 19:19:41 +0000
>> > "It" could best be avoided by having plain text README files.
> I think we should strongly encourage package writers to include plain
> text READMEs in their packages.

As the author of several packages on GNU ELPA which use a README.org:

1. I agree with Alan's main point: we do not need Org in Help buffers.
   Neither directly nor indirectly (if we are having that discussion).

2. I write all my documentation using the .org format because it can be
   exported to HTML and Info, among others.

3. Org is efficient for large files as it can, for example, create
   persistent links/references between headings.  Those are preserved in
   .info and .html exports.  Org also has nice features, such as the
   ability to declare a buffer-local macro which expands into, say,
   "version1.2.3" or "exported on DATE" where DATE is dynamic.  There
   are some cases where such functionality is helpful.

Concerning point 2, the GNU ELPA machinery converts the Org source into
an Info file.  (Those who install the package can access it with C-h i.)
While I handle the export process into HTML.

This arrangement provides two viable options for users who (i) want to
read the documentation yet (ii) do not wish to load org.el and its
accoutrements.  A third option, in the form of a plain README, is a
useful addition, provided it is done automatically by GNU ELPA.

As far as I am concerned, the README.org is a fully fledged resource,
not a generic, "here are the absolute basics" kind of file (not that
there is anything wrong with those).  As such, writing a separate
README, instead of exporting README.org into plain text, would add to
the maintenance burden---I would rather avoid that.

All the best,
Protesilaos (or simply "Prot")

Protesilaos Stavrou

reply via email to

[Prev in Thread] Current Thread [Next in Thread]