Re: installed packages long description.

[Stephen Leake]

Stefan Monnier <address@hidden> writes:

>> I see two solutions; describe-package can also look for README or the
>> Commentary comment header, or package-install can always populate
>> ~/.emacs.d/elpa/<pkg>-readme.txt
>
> Another is to look for a corresponding package in the archives and
> download its readme file.

One problem with this is different versions might be in different
archives, and the package description does not include which archive the
installed package is from.

Perhaps that could be added; it would require a
meta-info file, either in ~/.emacs.d/elpa/<pkg>/, or in ~/.emacs.d/elpa/

Another problem is the installed package could be older than the
current version in the archive; apparently there is no way to retrieve
the readme for an old version.

There's also no way to check that an existing <pkg>-readme.txt
corresponds to the installed package version.

> The ELPA standard

Where is this published/documented? I don't see a reference on
https://elpa.gnu.org/, and a web search for "ELPA standard" returned no
useful hits.

And where are changes to it discussed?

> doesn't say how/where to find the description within the package: the
> <pkg>-readme.txt served via HTTP is the only documented/official way
> to get the description (the README file and the Commentary sections
> are just what existing archives tend to use in their own
> package-building scripts).
>
> While we can come up with a short-term solution,

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

That would also handle old versions nicely.

> I think in the long run we should try and improve the ELPA standard in
> this respect, e.g. by specifying where the description can be found
> within the package (and also by specifying some kind of markup for
> this description rather than being limited to plain text).

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.

--
-- Stephe