GNU bug report logs - #52985
describe-package should show README instead of "Commentary" section

Previous Next

Full log

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: describe-package should show README instead of "Commentary" section
Date: Mon, 3 Jan 2022 14:13:56 -0500

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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.