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: Mon, 10 Dec 2018 11:27:58 -0800 Message-ID: <86efapi3lt.fsf@stephe-leake.org> References: <868t14kazo.fsf@stephe-leake.org> <86k1kiilm0.fsf@stephe-leake.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1544470006 28504 195.159.176.226 (10 Dec 2018 19:26:46 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 10 Dec 2018 19:26:46 +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 Mon Dec 10 20:26:42 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 1gWRCR-0007Ha-FK for ged-emacs-devel@m.gmane.org; Mon, 10 Dec 2018 20:26:39 +0100 Original-Received: from localhost ([::1]:34473 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gWREY-0006fl-Bi for ged-emacs-devel@m.gmane.org; Mon, 10 Dec 2018 14:28:50 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47793) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gWRDs-0006e9-MW for emacs-devel@gnu.org; Mon, 10 Dec 2018 14:28:09 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gWRDo-0004XZ-Je for emacs-devel@gnu.org; Mon, 10 Dec 2018 14:28:08 -0500 Original-Received: from smtp97.ord1d.emailsrvr.com ([184.106.54.97]:40886) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1gWRDo-0004Tv-DH for emacs-devel@gnu.org; Mon, 10 Dec 2018 14:28:04 -0500 Original-Received: from smtp21.relay.ord1d.emailsrvr.com (localhost [127.0.0.1]) by smtp21.relay.ord1d.emailsrvr.com (SMTP Server) with ESMTP id CDE73606E5 for ; Mon, 10 Dec 2018 14:27:59 -0500 (EST) X-Auth-ID: board-president@tomahawk-creek-hoa.com Original-Received: by smtp21.relay.ord1d.emailsrvr.com (Authenticated sender: board-president-AT-tomahawk-creek-hoa.com) with ESMTPSA id 8690A606C0 for ; Mon, 10 Dec 2018 14:27:59 -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); Mon, 10 Dec 2018 14:27:59 -0500 In-Reply-To: (Stefan Monnier's message of "Sun, 09 Dec 2018 21:40:01 -0500") X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 184.106.54.97 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:231745 Archived-At: Stefan Monnier writes: >>> The ELPA standard >> >> Where is this published/documented? > > I think it's in "Preparing Lisp code for distribution" in the > Elisp manual. Hmm. "Creating and Maintaining Package Archives" says: If you want the archive to be reachable via HTTP, this directory must be accessible to a web server. How to accomplish this is beyond the scope of this manual. 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. > And apparently it does document that it should be either in the > Commentary or in the README. Right. We need to add the other allowed file names to that. > >> 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. > >> Just document the code above. Markup could be handled by specifying >> "markdown", and looking for README.md. Or allow any markup for which >> there is an Emacs mode. > > IIRC README.md doesn't work so well, because many package use it as > a kind of "homepage" on github, so its content doesn't work very well > in the context of package.el. We could add README_elpa.* to handle that problem. > 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*.* . > Also, there's the old discussion of which markup to use (mostly Org or > markdown). Easiest to allow any that Emacs can display. The downside to that is if others try to maintain the file, they may have to learn a new markup; that's not a big deal for a README. -- -- Stephe