Re: usability problem of emacs describe-mode

[Tassilo Horn <tassilo@member.fsf.org>]

Xah Lee <xahlee@gmail.com> writes:

> emacs's describe-mode (Ctrl+h m) is really unusable.

[...]

> Why the fuck do i care to be splashed with these info?

Having all minor mode descriptions on one page does make sense, because
then you can use isearch.  Imagine you write "xy SPC" and suddenly it
expanded to "foobar".  `C-h m C-s expand' will point you to the
culprit's description (abbrev-mode).

> Suggestion:
>
> • describe-mode should just show the inline doc for the major mode.

I'd object with the reason above.

> • Add a link to the bottom to go to the full doc of the mode, if it
> exists. (the link may be to info doc, or to a url online of the mode's
> doc website)

Yep, an info link would be nice.  One could enforce that each command's
description contains a link to the relevant info pages, but that would
create a thight coupling between the code and the docs which requires
additional maintenance.

> • get rid of convention of using ^L for page break marker.

I don't have a opinion on that, but ^L doesn't occur in normal text, so
it makes parsing the *Help* buffer a bit easier.

> In addition, many of the convention adds up the pain in reading the
> doc. e.g. C t, C-u C-u, RET, <mouse-2>, etc. The C something really
> should be Ctrl+c, RET should be Return or Enter, <mouse-2> should be
> Right Button, etc.

I don't think that `Ctrl+c Alt+m' is more readable than `C-c M-m'.  And
<mouse-2> may be the right mouse button on your system, but on mine it's
<mouse-3>.  And with some gaming mouse it may be <mouse-17>.

Bye,
Tassilo