bug#52985: describe-package should show README instead of "Commentary" section

bug#52985: describe-package should show README instead of "Commentary" section

[Stefan Kangas]

Severity: wishlist

It would be more useful if `M-x describe-package' would show the README
file than the "Commentary" section, for packages where such a file
exists.

For the overwhelming majority of third-party packages, the README file,
when it exists, is much better maintained than the "Commentary" section.
Very few people bother keeping the two in sync, so usually what happens
is that the file commentary is pretty useless, and you need to go to the
Homepage/URL to even know how to use the package.

Too often this means you need to visit GitHub in your web browser.  One
could perhaps argue that this is a bug in those packages, but there are
literally thousands of them, and AFAICT little interest in doing things
differently among package authors and users.  Reading on GitHub is fine,
so why bother?

This state of affairs seems suboptimal.  However, I think the above
change could make reading documentation in Emacs more pleasant and
better than reading it externally.

Showing the raw source is unlikely to be very pleasant, so this might
need us to render not just org files in an attractive way, but also
markdown files.  Maybe we could start with showing the raw README files,
then add org-mode (README.org) and markdown (README.md) support, etc.,
later.

Perhaps we could even show the included images, somehow.

bug#52985: describe-package should show README instead of "Commentary" section

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> It would be more useful if `M-x describe-package' would show the README
> file than the "Commentary" section, for packages where such a file
> exists.

Makes sense to me.

> Perhaps we could even show the included images, somehow.

Yes, that would be nice.

I've added Stefan M to the CCs; perhaps he has some comments here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#52985: describe-package should show README instead of "Commentary" section

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Lars Ingebrigtsen [2022-01-14 09:42:39] wrote:
> Stefan Kangas <stefan@marxist.se> writes:
>> It would be more useful if `M-x describe-package' would show the README
>> file than the "Commentary" section, for packages where such a file
>> exists.
> Makes sense to me.
>> Perhaps we could even show the included images, somehow.
> Yes, that would be nice.
> I've added Stefan M to the CCs; perhaps he has some comments here.

When preparing the tarball, the (Non)GNU ELPA scripts can be told
whether to use the Commentary or a README file, and AFAIK that's the
info that is then shown by `describe-package`.  Currently the ELPA
protocol only offers a plain text version for that info.  We should
probably improve this part of the protocol.


        Stefan