[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: installed packages long description.

From: Stephen Leake
Subject: Re: installed packages long description.
Date: Mon, 10 Dec 2018 11:27:58 -0800
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.90 (windows-nt)

Stefan Monnier <address@hidden> 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 <pkg>-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':


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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]