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

[Boruch Baum]

On 2020-10-18 09:11, Stefan Monnier wrote:
> > 1) I share the sentiment about consolidating the help/describe commands,
> >    and have no objection to the feature being accessed via a link in
> >    describe-package (ie. no direct dedicated keybinding).
>
> IIUC your pack-doc provides a superset of what `C-h P` provides.

No, the only intersection is the 'commentary' text taken from the elisp
file. describe-package presents a unique heading summary; for example:

  #+BEGIN_QUOTE
  yasnippet is a dependency package.

       Status: Installed in ‘yasnippet-20200524.2215/’ (unsigned).
      Version: 20200524.2215
       Commit: d3d6d70b1cd4818d271752468e0fdb0788db750d
      Summary: Yet another snippet extension for Emacs
     Requires: cl-lib-0.5
     Homepage: http://github.com/joaotavora/yasnippet
     Keywords: [convenience] [emulation]
  Other versions: 20200604.246 (melpa), 0.14.0 (gnu), 0.6.1 (marmalade).
  #+END_QUOTE

> So what would be the downside(s) of replacing `C-h P` with your packdoc?

I have no objection, but I do like the heading summary that
describe-package presents, and think it would be a shame to lose it.

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

Playing devil's advocate: I'm not any kind of UX psychologist, but if
there is someone like that on the list, they could speak to the notion
of it maybe being a situation of presenting 'too much information' for a
user expecting the prior behavior or for a user just wanting the most
basic package description or for a user unfamiliar with org-mode.

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