From unknown Wed Jun 18 23:13:09 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#52985 <52985@debbugs.gnu.org> To: bug#52985 <52985@debbugs.gnu.org> Subject: Status: describe-package should show README instead of "Commentary" section Reply-To: bug#52985 <52985@debbugs.gnu.org> Date: Thu, 19 Jun 2025 06:13:09 +0000 retitle 52985 describe-package should show README instead of "Commentary" s= ection reassign 52985 emacs submitter 52985 Stefan Kangas severity 52985 wishlist thanks From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 03 14:14:03 2022 Received: (at submit) by debbugs.gnu.org; 3 Jan 2022 19:14:03 +0000 Received: from localhost ([127.0.0.1]:36232 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n4SmR-00052H-93 for submit@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 ) id 1n4SmO-00051e-69 for submit@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 ) id 1n4SmO-0000Qx-2S for bug-gnu-emacs@gnu.org; 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 ) id 1n4SmM-0008R0-Fm for bug-gnu-emacs@gnu.org; Mon, 03 Jan 2022 14:13:59 -0500 Received: by mail-pg1-f171.google.com with SMTP id x194so7571456pgx.4 for ; 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 MIME-Version: 1.0 Date: Mon, 3 Jan 2022 14:13:56 -0500 Message-ID: Subject: describe-package should show README instead of "Commentary" section To: bug-gnu-emacs@gnu.org Content-Type: text/plain; charset="UTF-8" Received-SPF: pass client-ip=209.85.215.171; envelope-from=stefankangas@gmail.com; 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@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Jan 14 03:42:52 2022 Received: (at 52985) by debbugs.gnu.org; 14 Jan 2022 08:42:52 +0000 Received: from localhost ([127.0.0.1]:35521 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n8IAe-0001Dt-3F for submit@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 ) id 1n8IAb-0001Dc-Td for 52985@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 ) id 1n8IAS-0001pJ-HY; Fri, 14 Jan 2022 09:42:43 +0100 From: Lars Ingebrigtsen To: Stefan Kangas Subject: Re: bug#52985: describe-package should show README instead of "Commentary" section References: X-Now-Playing: Noveller's _Arrow_: "Rune" Date: Fri, 14 Jan 2022 09:42:39 +0100 In-Reply-To: (Stefan Kangas's message of "Mon, 3 Jan 2022 14:13:56 -0500") Message-ID: <874k66r9mo.fsf@gnus.org> 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 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@debbugs.gnu.org, Stefan Monnier X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Stefan Kangas 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 From debbugs-submit-bounces@debbugs.gnu.org Fri Jan 14 11:22:10 2022 Received: (at 52985) by debbugs.gnu.org; 14 Jan 2022 16:22:10 +0000 Received: from localhost ([127.0.0.1]:37932 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n8PL7-0005Zo-SU for submit@debbugs.gnu.org; Fri, 14 Jan 2022 11:22:10 -0500 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:32603) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n8PL6-0005Za-4z for 52985@debbugs.gnu.org; Fri, 14 Jan 2022 11:22:08 -0500 Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 27DE24423EC; Fri, 14 Jan 2022 11:22:02 -0500 (EST) Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id CD5854423E9; Fri, 14 Jan 2022 11:22:00 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1642177320; bh=HzySafnAUDfNwtOpmc+sg1Atmb+dSothZFfE4edO5DU=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=azxbP0pzmeDmGdInqNj0JzebMErfpii+YJrDF4lKhFcaCQ9DuTrC1wwbiqpaCcfvI vL0txUeVm9Jz67TF84pjnP0F9MZ/G/3OIXr2BbxKMUosdiUVBCK51YUmd7bDALJtwH 6xOty59VYZq3D3MO8QAzofWmwkMyZVteOzDnOmHHYz+ps7UiOQ7tR0q4o8Z8rGNkBk t7YekdxA73l6hYIKMPcUBtJb4KRd5CvEct/oraImuWujecJZX3jWy/rPHoHQggBkem NCFv8Rc/OP+BxGBV8qelKzzBL5N2rJjrwwdMjfdBtUDQUSVMQCznJPdwXCJrlvRp0c PWLGcHFszwJ2w== Received: from pastel (unknown [216.154.30.173]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 9F87C120480; Fri, 14 Jan 2022 11:22:00 -0500 (EST) From: Stefan Monnier To: Lars Ingebrigtsen Subject: Re: bug#52985: describe-package should show README instead of "Commentary" section Message-ID: References: <874k66r9mo.fsf@gnus.org> Date: Fri, 14 Jan 2022 11:21:59 -0500 In-Reply-To: <874k66r9mo.fsf@gnus.org> (Lars Ingebrigtsen's message of "Fri, 14 Jan 2022 09:42:39 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL 0.553 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain X-SPAM-LEVEL: X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 52985 Cc: 52985@debbugs.gnu.org, Stefan Kangas X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Lars Ingebrigtsen [2022-01-14 09:42:39] wrote: > Stefan Kangas 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