From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Stephen Leake Newsgroups: gmane.emacs.devel Subject: Re: installed packages long description. Date: Tue, 11 Dec 2018 17:46:59 -0800 Message-ID: <86r2enecto.fsf@stephe-leake.org> References: <868t14kazo.fsf@stephe-leake.org> <86k1kiilm0.fsf@stephe-leake.org> <86efapi3lt.fsf@stephe-leake.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1544579143 16538 195.159.176.226 (12 Dec 2018 01:45:43 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 12 Dec 2018 01:45:43 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.90 (windows-nt) To: emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Dec 12 02:45:39 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gWtal-0004Cm-EM for ged-emacs-devel@m.gmane.org; Wed, 12 Dec 2018 02:45:39 +0100 Original-Received: from localhost ([::1]:42254 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gWtcs-0005cJ-4L for ged-emacs-devel@m.gmane.org; Tue, 11 Dec 2018 20:47:50 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52943) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gWtcA-0005c1-GU for emacs-devel@gnu.org; Tue, 11 Dec 2018 20:47:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gWtc7-0002qp-9p for emacs-devel@gnu.org; Tue, 11 Dec 2018 20:47:06 -0500 Original-Received: from smtp113.iad3b.emailsrvr.com ([146.20.161.113]:58978) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1gWtc7-0002qX-5L for emacs-devel@gnu.org; Tue, 11 Dec 2018 20:47:03 -0500 Original-Received: from smtp15.relay.iad3b.emailsrvr.com (localhost [127.0.0.1]) by smtp15.relay.iad3b.emailsrvr.com (SMTP Server) with ESMTP id D96FEC0B47 for ; Tue, 11 Dec 2018 20:47:01 -0500 (EST) X-Auth-ID: board-president@tomahawk-creek-hoa.com Original-Received: by smtp15.relay.iad3b.emailsrvr.com (Authenticated sender: board-president-AT-tomahawk-creek-hoa.com) with ESMTPSA id 828FDC0AF1 for ; Tue, 11 Dec 2018 20:47:01 -0500 (EST) X-Sender-Id: board-president@tomahawk-creek-hoa.com Original-Received: from Takver4 ([UNAVAILABLE]. [76.77.182.20]) (using TLSv1.2 with cipher AES256-GCM-SHA384) by 0.0.0.0:25 (trex/5.7.12); Tue, 11 Dec 2018 20:47:01 -0500 In-Reply-To: (Stefan Monnier's message of "Tue, 11 Dec 2018 15:01:04 -0500") X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 146.20.161.113 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:231770 Archived-At: Stefan Monnier writes: >> And it does not describe "the -readme.txt served via HTTP" >> >> So we need to add that at least. We could also document the other uses >> of 'package--with-response-buffer': >> >> package--check-signature >> package--download-one-archive >> package-install-from-archive >> >> Then package.el can reference the elisp manual. > > Sounds good. Can you take care of it? Yes. >>>> from elpa/admin/archive-contents.el, that appears to be: >>>> >>>> (archive--get-section >>>> "Commentary" >>>> '("README" "README.rst" "README.org") >>>> srcdir mainsrcfile) >>>> >>>> That code could be moved to package.el >>> >>> Sounds good. > > Can you take care of this as well? Yes. I won't change the elpa code. I'll submit a patch for review before committing anything. >>> As for saying the README and/or Commentary: from now on is assumed to >>> use Markdown, that will result in ugly text with current/previous >>> packages which are not written under this assumption. >> Right, I would say no markup in Commentary: or README, and rely on the >> file extension for a README*.* . > > We could support a new section name ("Description:" or > "Commentary.org:" or ...) for the "Commentary: with markup". > > This said, there's also the possibility to just use Commentary: along > with a heuristic which would give "mostly correct" results on > existing Commentaries. > > Bonus points if we can change elisp-mode's font-lock so the markup is > correctly prettified. I'll leave this for later. Simple package authors can switch to a multi-file package with a README.* file if they want markup. >>> Also, there's the old discussion of which markup to use (mostly Org or >>> markdown). >> Easiest to allow any that Emacs can display. > > I think currently Org is the only markup format that vanilla Emacs can > render (tho arguably Texinfo is there as well, via makeinfo.el). > > Allowing more formats requires more code to handle the various formats, > so I think we'd be better off only supporting one format. We have markdown-mode in ELPA, which does a reasonable job. There's also markdown-preview-eww - I didn't try it. That's what I meant by "any that Emacs can display"; if there is a mode (built-in or in ELPA) for the format, that does a reasonable job of display, then the package author can decide to use that format. Hmm. It also has to work well on the ELPA web page; that's a complication. We might have to use multi-major-mode in the display buffer, for the headers provided by 'describe-package'. If the mode is in ELPA and not installed, there needs to be some header text saying "please install foo-mode to display this better". Or something. That would be a reason to use only modes bundled with the standard distribution. Or the author could provide a plain text README as a fall-back. I suspect most markdown formatters have an option to output plain text, so that could be automated. I don't see an "rst-mode", but I guess that format is meant to be readable as plain text. This is less important than getting the correct long description for installed packages. -- -- Stephe