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

* bug#52985: describe-package should show README instead of "Commentary" section
  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
  0 siblings, 1 reply; 3+ messages in thread
From: Lars Ingebrigtsen @ 2022-01-14  8:42 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 52985, Stefan Monnier

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





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

* bug#52985: describe-package should show README instead of "Commentary" section
  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
  0 siblings, 0 replies; 3+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-01-14 16:21 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 52985, Stefan Kangas

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






^ 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 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).