Re: installed packages long description.

[Stephen Leake <stephen_leake@stephe-leake.org>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

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

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