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

[Philip Kaludercic <philipk@posteo.net>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> FWIW I find this particular conversion made things overall worse :-(
>> Hmm, what in particular?
>
> I didn't like the two spaces after the "bullets" and more importantly
> the information about what is a title was completely lost.
>
>> As I said it doesn't have to be this specific formatting.
>
> Sure, I just mentioned it because I found it rather odd to return
> a worse result than the identity function.

My example was a pretty clean markdown file, which is usually readable
enough in its own right, so most post-processing doesn't help.  But I
agree, it isn't as easy as just using pandoc's "plain" output.

>> It could also just be cleaned up markdown, moving links below
>> paragraphs, wrapping lines and stuff like that.
>
> Then again, this can (should?) be applied to the source directly.

As in sending upstream patches?  From my experience a lot of maintainers
(regrettably) prefer something that renders well on sites like GitHub or
GitLab than that is readable as plain text.

Or do you mean writing custom code to process markdown files?

> Don't get me wrong: I'm definitely not opposed to rendering Markdown to
> plain text.  I've seen a fair bit of "GFM" files that are not great to
> read as plain text, so there is clearly room for improvement.
> Maybe throwing out the badges would be a good first step ;-)

Then again, this ties into the README files that look better when
rendered on GitHub/Lab, and where it is worth considering if *not*
using them would be of more use.  If this is about providing a good
overview when using C-h P, using a good commentary section (that does
not include comments on how to install the package, contribution
guidelines, screenshots, etc.) might be better to begin with.

This is also related to the point I had raised earlier in the thread
that when a package generates a manual from a Org README, using the same
file as a README file results in too much (redundant) information.

>         Stefan