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

[Yuri Khan]

On Mon, 27 Jun 2022 at 17:05, Philip Kaludercic <philipk@posteo.net> wrote:

> > 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.

Badges do not have to be ugly in markdown source. Or, at least, they
can be much less ugly.

Let’s dissect [Eglot’s README.md][1] just as an example (only because
it has badges; otherwise, I think Eglot’s README.md is as non-ugly as
possible):

[1]: https://raw.githubusercontent.com/joaotavora/eglot/master/README.md

    [![Build 
status](https://github.com/joaotavora/eglot/actions/workflows/test.yml/badge.svg)](https://github.com/joaotavora/eglot/actions/workflows/test.yml)
    [![GNU 
ELPA](https://elpa.gnu.org/packages/eglot.svg)](https://elpa.gnu.org/packages/eglot.html)
    
[![MELPA](https://melpa.org/packages/eglot-badge.svg)](https://melpa.org/#/eglot)

Here we have three source lines, each longer than 80 characters. They
are not separated with blank lines, so they comprise a single
paragraph; the badges are rendered in a single line.

Each badge is a hyperlink [](); brackets contain the link text and
parentheses specify the link target URL. There is alternative syntax
where you put a short reference identifier at the place of use, and
define that reference on a separate line.

    [![Build 
status](https://github.com/joaotavora/eglot/actions/workflows/test.yml/badge.svg)][build]
    [![GNU ELPA](https://elpa.gnu.org/packages/eglot.svg)][elpa]
    [![MELPA](https://melpa.org/packages/eglot-badge.svg)][melpa]

    [build]: https://github.com/joaotavora/eglot/actions/workflows/test.yml
    [elpa]: https://elpa.gnu.org/packages/eglot.html
    [melpa]: https://melpa.org/#/eglot

Next, each badge’s text is actually an image ![](). Brackets contain
the alt text fallback for user agents that do not display images; and
parens specify the image URL. The same external reference syntax
works:

    [![Build status][build-badge]][build]
    [![GNU ELPA][elpa-badge]][elpa]
    [![MELPA][melpa-badge]][melpa]

    [build]: https://github.com/joaotavora/eglot/actions/workflows/test.yml
    [elpa]: https://elpa.gnu.org/packages/eglot.html
    [melpa]: https://melpa.org/#/eglot

    [build-badge]:
https://github.com/joaotavora/eglot/actions/workflows/test.yml/badge.svg
    [elpa-badge]: https://elpa.gnu.org/packages/eglot.svg
    [melpa-badge]: https://melpa.org/packages/eglot-badge.svg

Now, only one line is longer than 80 characters.

URLs specified this way can appear anywhere in the markdown source.
Eglot’s README actually uses this syntax for all other (non-badge)
hyperlinks and puts URLs at the bottom.