[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
https://protesilaos.com
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), (continued)
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), Ihor Radchenko, 2022/06/10
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), Akib Azmain Turja, 2022/06/10
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), Ihor Radchenko, 2022/06/08
- Re: Org mode and Emacs (was: Convert README.org to plain text README while installing package), Stefan Kangas, 2022/06/08
- Re: Org mode and Emacs, Stefan Monnier, 2022/06/08
- Re: Org mode and Emacs, Ihor Radchenko, 2022/06/08
- Re: Org mode and Emacs, Richard Stallman, 2022/06/12
- Re: Convert README.org to plain text README while installing package, Tim Cross, 2022/06/07
- Re: Convert README.org to plain text README while installing package, chad, 2022/06/08
- Re: Convert README.org to plain text README while installing package, Alan Mackenzie, 2022/06/06
- Re: Convert README.org to plain text README while installing package,
Protesilaos Stavrou <=
- Re: Convert README.org to plain text README while installing package, Philip Kaludercic, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Protesilaos Stavrou, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Stefan Monnier, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Po Lu, 2022/06/06
- Re: Convert README.org to plain text README while installing package, Kévin Le Gouguec, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Po Lu, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Kévin Le Gouguec, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Po Lu, 2022/06/07
- Re: Convert README.org to plain text README while installing package, Kévin Le Gouguec, 2022/06/08
- Re: Convert README.org to plain text README while installing package, Michael Albinus, 2022/06/06