Re: installed packages long description.

[Stefan Monnier]

> 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.

Sounds good.  Can you take care of it?

>>> 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?

>> 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.

>> 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.


        Stefan