[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: Philip Kaludercic
Subject: Re: Convert README.org to plain text README while installing package
Date: Mon, 27 Jun 2022 16:44:48 +0000

Yuri Khan <yuri.v.khan@gmail.com> writes:

> 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):


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

I get the impression that this trades horizontally wasted space for
vertically wasted space (setting aside that by reordering the URLs they
don't have to appear in the middle of the document).  The issue here is
that in the plain-text buffer that C-h P provides, the badges are simply
always redundant, so either they should somehow be handled by the *Help*
buffer, removed from the buffer or (as I argue) we should not display
the README that is usually targeted at a different audience, and instead
recommend to write clean, brief, informative commentary sections in the
main files.

reply via email to

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