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

[Stefan Kangas <stefankangas@gmail.com>]

Boruch Baum <boruch_baum@gmx.com> writes:

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

I tested it on lisp/time.el.

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

OK, fair enough, so please modify the above to say "everything after the
'Commentary' section".

You could just move the sections around.  For example, the license could
be moved to the end (if it is even necessary in the GPL case).

> 'commentary' section that describe-package presents isn't directly from
> the 'commentary' section in the elisp file (see, for example, yasnippet).

That's because it comes from the package README file instead.

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

Yes, so that's the part that would need looking into.

>> Perhaps one could make it look more polished by rolling a custom
>> solution here,
>
> Ugh. Re-invent yet another wheel?

Not if we can avoid it, but Org-mode is also not a hammer looking for a
nail.

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

Run your code on time.el and see that obsolete aliases are there.

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

Run your code on time.el and see that the autoload cookies are copied
verbatim above the headings.  I think they should better be marked in a
different way.