From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#52985: describe-package should show README instead of "Commentary" section Date: Mon, 3 Jan 2022 14:13:56 -0500 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27583"; mail-complaints-to="usenet@ciao.gmane.io" To: 52985@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Jan 03 20:15:35 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1n4Snv-0006wB-0H for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 03 Jan 2022 20:15:35 +0100 Original-Received: from localhost ([::1]:33736 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n4Snt-0000ea-8F for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 03 Jan 2022 14:15:33 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:44730) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n4SnO-0000e5-La for bug-gnu-emacs@gnu.org; Mon, 03 Jan 2022 14:15:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52919) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1n4SnO-00005o-4m for bug-gnu-emacs@gnu.org; Mon, 03 Jan 2022 14:15:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1n4SnO-00053y-1W for bug-gnu-emacs@gnu.org; Mon, 03 Jan 2022 14:15:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 03 Jan 2022 19:15:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 52985 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.164123724319366 (code B ref -1); Mon, 03 Jan 2022 19:15:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 3 Jan 2022 19:14:03 +0000 Original-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 Original-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 Original-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 Original-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 Original-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) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Mon, 3 Jan 2022 14:13:56 -0500 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:223599 Archived-At: 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.