Re: Ideas to improve the output of C-h m?

[Stefan Monnier]

> I have pasted at the botom of this email the output of the current C-h
> m and the output of the code I wrote a while ago.  Here's how it looks
> for a single entry, to see the difference (note that unlike C-h m, it
> currently groups keybindings that map to the same command):

I think grouping is a good idea, tho the current "columnar" output has
its advantages as well.

>     ‘C-c @’ (outline-mark-subtree)
>       Mark the current subtree in an outlined document.
>     ‘C-c C-n’ (outline-next-visible-heading)
>       Move to the next visible heading line.

More importantly, while I like the idea of showing the first line of the
docstring, I find the above much harder to read.  It makes the common
`C-c` and `outline-` prefixes much less obvious so you can't so easily
focus on the other parts to find what you're looking for.

IOW it's a definite improvement when you're looking for something akin
to a "quick overview" or "very short manual" that you will read from
top-to-bottom.  But if you're instead interested in looking up a table,
I think it's rather worse.

Not sure how/if we can reconcile those two kinds of uses.
Of course, we could simply do:

>     ‘C-c @’    (outline-mark-subtree)          Mark the current subtree in an 
> outlined document.
>     ‘C-c C-n’  (outline-next-visible-heading)  Move to the next visible 
> heading line.

and then play with the line-truncation keep it on a single line to get
the same benefit as the current text (but at the cost of pushing the
docstring to the right were it will only be visible in a very wide
window or after the user explicitly scrolls or changes the line-truncation).

> (in a real Emacs window, the function names and the keybindings are 
> highlighted, and on graphical terminals there's a thin line between each 
> entry).

Don't know about you, bu I'm looking at it in a real (and graphical)
Emacs window and I can't see any of those finer details ;-)


        Stefan