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

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: wishlist; Reported by: Stefan Kangas <stefan@HIDDEN>; dated Mon, 3 Jan 2022 19:15:01 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 52985 <at> debbugs.gnu.org:


Received: (at 52985) by debbugs.gnu.org; 14 Jan 2022 08:42:52 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Jan 14 03:42:52 2022
Received: from localhost ([127.0.0.1]:35521 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1n8IAe-0001Dt-3F
	for submit <at> debbugs.gnu.org; Fri, 14 Jan 2022 03:42:52 -0500
Received: from quimby.gnus.org ([95.216.78.240]:35024)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <larsi@HIDDEN>) id 1n8IAb-0001Dc-Td
 for 52985 <at> debbugs.gnu.org; Fri, 14 Jan 2022 03:42:50 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org;
 s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date:
 References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding:
 Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender:
 Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:
 List-Subscribe:List-Post:List-Owner:List-Archive;
 bh=742PZZ3AKWL7TdnC6tOuAAfP1KOqxwHakd2VOKZlQrM=; b=u27s36PxXEHO36BCyg4LMKU20i
 vNjMIaIxHfXohHRnflnDVQO46Lu0oLeNnGjqgYT54FNarQFDTgzmHdLIizTql8Q0Ey7/XEuK+ugke
 JL+GQ7Ih8EMpaSVFk7fDzRjUN/iue8/dx7CcYKoqeeb4tq9HnWZ1n1H60nDWzrvSGwDY=;
Received: from [84.212.220.105] (helo=xo)
 by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.92) (envelope-from <larsi@HIDDEN>)
 id 1n8IAS-0001pJ-HY; Fri, 14 Jan 2022 09:42:43 +0100
From: Lars Ingebrigtsen <larsi@HIDDEN>
To: Stefan Kangas <stefan@HIDDEN>
Subject: Re: bug#52985: describe-package should show README instead of
 "Commentary" section
References: <CADwFkmncFSDCkXBeqF4FEsWZYigC4+9TrYScb4VVXx7cHoWnBw@HIDDEN>
X-Now-Playing: Noveller's _Arrow_: "Rune"
Date: Fri, 14 Jan 2022 09:42:39 +0100
In-Reply-To: <CADwFkmncFSDCkXBeqF4FEsWZYigC4+9TrYScb4VVXx7cHoWnBw@HIDDEN>
 (Stefan Kangas's message of "Mon, 3 Jan 2022 14:13:56 -0500")
Message-ID: <874k66r9mo.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org",
 has NOT identified this incoming email as spam.  The original
 message has been attached to this so you can view it or label
 similar future email.  If you have any questions, see
 @@CONTACT_ADDRESS@@ for details.
 Content preview: Stefan Kangas <stefan@HIDDEN> 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. 
 Content analysis details:   (-2.9 points, 5.0 required)
 pts rule name              description
 ---- ---------------------- --------------------------------------------------
 -1.0 ALL_TRUSTED            Passed through trusted hosts only via SMTP
 -1.9 BAYES_00               BODY: Bayes spam probability is 0 to 1%
 [score: 0.0000]
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 52985
Cc: 52985 <at> debbugs.gnu.org, Stefan Monnier <monnier@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

Stefan Kangas <stefan@HIDDEN> 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




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#52985; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 3 Jan 2022 19:14:03 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jan 03 14:14:03 2022
Received: from localhost ([127.0.0.1]:36232 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1n4SmR-00052H-93
	for submit <at> debbugs.gnu.org; Mon, 03 Jan 2022 14:14:03 -0500
Received: from lists.gnu.org ([209.51.188.17]:35140)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <stefankangas@HIDDEN>) id 1n4SmO-00051e-69
 for submit <at> debbugs.gnu.org; Mon, 03 Jan 2022 14:14:02 -0500
Received: from eggs.gnu.org ([209.51.188.92]:44510)
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
 id 1n4SmO-0000Qx-2S
 for bug-gnu-emacs@HIDDEN; Mon, 03 Jan 2022 14:14:00 -0500
Received: from mail-pg1-f171.google.com ([209.85.215.171]:37698)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
 id 1n4SmM-0008R0-Fm
 for bug-gnu-emacs@HIDDEN; Mon, 03 Jan 2022 14:13:59 -0500
Received: by mail-pg1-f171.google.com with SMTP id x194so7571456pgx.4
 for <bug-gnu-emacs@HIDDEN>; Mon, 03 Jan 2022 11:13:58 -0800 (PST)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20210112;
 h=x-gm-message-state:from:mime-version:date:message-id:subject:to;
 bh=CdNMZh45nHt4082Po1FWuKehUVdt2DFZo8arzwqJc10=;
 b=kqp3bKwGp1JBx7XEXA0OZ4frr5ESd7RLjsFilNoEWUoQBbYbVkHROCyTpMCp5+Vste
 Zt0AhB7Op7eXwpjTt2eOCBrBma0ayQ6eF+eTgYNDmJKF5wmNxrTt1fd1XgpzWlSv5TuX
 oqFR83+HaK00VaTtawuD72z0auBXbr0at/CZlgSXQ7V8I3jKSO7AFUFaUjEPhBvEnqPK
 XbX8wGxnrV/b8+B5YpzvCpkbX5qzrsvxifCvxPRXqekpaGZb68rA11qUJ8T5vD86M5z0
 oJ6+55qxUmDI7wfG+PwGAvxlp79KabCP7Qz4IUS+dM8BzHaD2YzW/ToQgpFL3fBBET9+
 srIg==
X-Gm-Message-State: AOAM532Wfn8PWQvmQ1Wp3Ua5HaNLBiqgWd7oqdnhnr4ifvY+eVNmfidS
 FBNtRuNZxO3wjVrcL1oV6yEZGh1KEWT6SmPlCpC/78gP
X-Google-Smtp-Source: ABdhPJzJJIBoEbULQO+C+HvwbQqHOkJydfcULdFZCkcxZP5OBUwd0UNiQagq61CFcoxLl4Q3PeQIyRTmtuug0GYpcAk=
X-Received: by 2002:a63:2c11:: with SMTP id s17mr41149151pgs.435.1641237237178; 
 Mon, 03 Jan 2022 11:13:57 -0800 (PST)
Received: from 753933720722 named unknown by gmailapi.google.com with
 HTTPREST; Mon, 3 Jan 2022 14:13:56 -0500
From: Stefan Kangas <stefan@HIDDEN>
MIME-Version: 1.0
Date: Mon, 3 Jan 2022 14:13:56 -0500
Message-ID: <CADwFkmncFSDCkXBeqF4FEsWZYigC4+9TrYScb4VVXx7cHoWnBw@HIDDEN>
Subject: describe-package should show README instead of "Commentary" section
To: bug-gnu-emacs@HIDDEN
Content-Type: text/plain; charset="UTF-8"
Received-SPF: pass client-ip=209.85.215.171;
 envelope-from=stefankangas@HIDDEN; helo=mail-pg1-f171.google.com
X-Spam_score_int: 5
X-Spam_score: 0.5
X-Spam_bar: /
X-Spam_report: (0.5 / 5.0 requ) FREEMAIL_FORGED_FROMDOMAIN=0.249,
 FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.25,
 RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001,
 SPF_PASS=-0.001 autolearn=no autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -0.8 (/)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.8 (-)

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.




Acknowledgement sent to Stefan Kangas <stefan@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#52985; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Fri, 14 Jan 2022 08:45:01 UTC

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