unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#52985: describe-package should show README instead of "Commentary" section
@ 2022-01-03 19:13 Stefan Kangas
  2022-01-14  8:42 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 3+ messages in thread
From: Stefan Kangas @ 2022-01-03 19:13 UTC (permalink / raw)
  To: 52985

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.





^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2022-01-14 16:21 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-01-03 19:13 bug#52985: describe-package should show README instead of "Commentary" section Stefan Kangas
2022-01-14  8:42 ` Lars Ingebrigtsen
2022-01-14 16:21   ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).