[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: |
Tue, 11 Dec 2018 17:46:59 -0800 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.0.90 (windows-nt) |
Stefan Monnier <address@hidden> 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
- installed packages long description., Stephen Leake, 2018/12/04
- Re: installed packages long description., Stefan Monnier, 2018/12/09
- Re: installed packages long description., Stephen Leake, 2018/12/09
- Re: installed packages long description., Stefan Monnier, 2018/12/09
- Re: installed packages long description., Stephen Leake, 2018/12/10
- Re: installed packages long description., Stefan Monnier, 2018/12/11
- Re: installed packages long description.,
Stephen Leake <=
- Re: installed packages long description., Stefan Monnier, 2018/12/11
- Re: installed packages long description., Stephen Leake, 2018/12/13
- Re: installed packages long description., Stefan Monnier, 2018/12/13
- Re: installed packages long description., Stephen Leake, 2018/12/13