Re: installed packages long description.

[Stephen Leake]

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':

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