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

Previous Next

To reply to this bug, email your comments to 52985 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

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.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 52985 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#52985: describe-package should show README instead of
 "Commentary" section
Date: Fri, 14 Jan 2022 09:42:39 +0100

Stefan Kangas <stefan <at> 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

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 52985 <at> debbugs.gnu.org, Stefan Kangas <stefan <at> marxist.se>
Subject: Re: bug#52985: describe-package should show README instead of
 "Commentary" section
Date: Fri, 14 Jan 2022 11:21:59 -0500

Lars Ingebrigtsen [2022-01-14 09:42:39] wrote:
> Stefan Kangas <stefan <at> 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

Previous Next

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