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

[Tassilo Horn]

Drew Adams <drew.adams@oracle.com> writes:

>> why can't you understand that someone thinks
>> it's a good idea if the package description
>> is displayed as the author intended?
>
> I'd say as the _user_ intends, not the author.

You and me are both users and it seems we have different
intentions/preferences.

> Displaying a package description is for the
> benefit of the user, not the author.  It's
> about what's most useful for users.

Why do you think that a free software package author doesn't write his
documentation for this very purpose?  Exactly for this reason she has
structured the README in sections, **emphasized the important parts**,
included usage/config examples as highlighted

#+BEGIN_SRC emacs-lisp
  (code snippets)
#+END_SRC

and added clickable links to [[helpful resources][https://...]].  Why is
it "most useful" for users to strip away parts of that?

> Best is this, I think:
>
> 1. Require a plain-text README, as a minimum.
> 2. Allow other formats, with appropriate file
>    extensions (e.g. .md, .org).
>
> I see no reason for any limit on the kinds of
> format, for #2.
>
> There should be, and likely are, simple ways
> to generate a plain-text README from this or
> that more structured format.  Condition #1
> shouldn't be an obstacle to anyone, I'd think.

If there is some automatic conversion like for org, the obstacle is just
that I as a package author would need to commit a generated file with
the danger that contributors send patches against the generated document
instead of the source.  Not a big deal but also not great.

>> I've just tried org-exporting the vertico README.org to a plain-text
>> UTF-8 version and have to confess, the result is really, really
>> intriguing.  So, yes, such a conversion is at least much better as the
>> status quo where the org syntax is displayed literally without
>> highlighting.  (I almost don't perceive the org/markdown syntax when
>> there's syntax highlighting but if there isn't, it looks annoying.)
>
> For Org, at least, that seems to confirm my
> guess that such conversion's already available.

Yes, indeed.  I haven't seen anything like that for markdown (which is
probably even more popular for READMEs than org), though.

Bye,
Tassilo