Re: ~Make emacs friendlier: package documentation [POC CODE INCLUDED]

[Boruch Baum <boruch_baum@gmx.com>]

On 2020-10-18 08:50, Stefan Kangas wrote:
> Boruch Baum <boruch_baum@gmx.com> writes:
>
> >> IOW what would be the advantage of adding a link in `C-h P` to your
> >> system, instead of just replacing `C-h P` with your system?
> >
> > IMO: Just losing the heading summary, but that code can be integrated so
> > that nothing would be lost.
>
> Having tested your code,

Thanks. For what packages? It's important to know in order to understand
the content of your feedback.

> I agree that we should keep `C-h P' as-is, but extend it with
> everything from the "** Code:" header and down in your code.

That would lose a lot of information. There could be many
sections/headings above 'code', and it turns out to seem that even the
'commentary' section that describe-package presents isn't directly from
the 'commentary' section in the elisp file (see, for example, yasnippet).

> (I guess that part could be collapsed by default in order to not
> overwhelm a user with details?)

Yes. Good idea.

> It would be great if one could also collapse the "Commentary" section.

Do-able.

> I would also give it a headline "Description:" using the same font as
> "Status:".

Don't know if that's possible for org-mode headings...

> We would also need to check that this works also for packages that are
> not installed (they don't need to show the full documentation, I don't
> think, but they should at least not be broken ;-).

My code submission should work as-is on any elisp file that conforms to
the emacs coding standard format. I've tested it for my other recent
code submission - key-assist.el

OTOH, the converse is not true. describe-package doesn't expose itself
to any elisp file, only recognized packages. Even some features that we
all think of as packages aren't exposed (eg. dired).

> Bonus points if we can also add a link to the relevant Info manual,
> where there is one.

That a good idea, but it's independent of whatever ends up happening
with my code submission, so it should be an independent bug report or
feature request against package 'describe-package'.

> BTW, does this all really need to be based on Org-mode?

Technically: of course not.

Practically: the entire point of the code submission is exploit the
             great features of org-mode, and the pre-existing format
             conventions of the emacs coding standard.

> Perhaps one could make it look more polished by rolling a custom
> solution here,

Ugh. Re-invent yet another wheel?

> and I'm not exactly sure what using Org-mode buys us in this case.

For starters: Navigation, expansion and collapse of sections.

> Three more nits:

For me to make sense of most of what you write below, I need to know at
the very least on what elisp file you encountered the problem, and
helpfully a pointer of where to find it.

> - I wouldn't show obsolete aliases.

???

> - The autoload cookies should probably get a better representation than
>   just being copied in.

???

> - The doc strings should be passed to `substitute-command-keys' before
>   display.

This one I understand, and is an excellent idea.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0