More useful mode help?

More useful mode help?

[ndame]

[-- Attachment #1: Type: text/plain, Size: 2650 bytes --]

I wanted to kill a process from emacs, so I started
list-processes. Never having used it before I pressed k on a process
to kill it. Nothing. So I pressed ? to find out what key kills a
process.

The first thing in the mode help:

  Enabled minor modes: Abbrev Auto-Composition Auto-Compression
  Auto-Encryption Auto-Insert Blink-Cursor Column-Number
  Delete-Selection Diff-Auto-Refine Electric-Indent Electric-Pair
  File-Name-Shadow Font-Lock Global-Aggressive-Indent Global-Eldoc
  Global-Font-Lock Iswitchb Line-Number Minibuffer-Depth-Indicate
  Mouse-Wheel Recentf Save-Place Savehist Shell-Dirtrack Tooltip
  Transient-Mark Winner


Is there a reason why this comes first? Doesn't seem too relevant if
the user simply wants to find out about how to use the current mode.

Then comes the process description mentioning which hook run. Still
not very useful if one wants to simply use the mode.

Then come the keys:

  key             binding
  ---             -------

  TAB             forward-button
  ESC             Prefix Command
  SPC             scroll-up-command
  -               negative-argument
  0 .. 9          digit-argument
  <               beginning-of-buffer
  >               end-of-buffer
  ?               describe-mode
  S               tabulated-list-sort
  d               process-menu-delete-process
  g               revert-buffer
  h               describe-mode
  n               next-line
  p               previous-line
  q               quit-window
  DEL             scroll-down-command
  S-SPC           scroll-down-command
  <backtab>       backward-button
  <follow-link>   mouse-face
  <mouse-2>       mouse-select-window
  <remap>         Prefix Command

  C-M-i           backward-button



As you can see the single process binding is in the middle and it's d.

Shouldn't this info come first in the help? The actual keys bound by
the major mode. So in my case the beggining of the Help could have
been:

  Mode keys:

  d process-menu-delete-process


All the other info about hooks and minor modes and next-line,
etc. keys could come later.

Maybe the tabulated-list-sort key and the revert-buffer key could also
be listed along with d at the beginning, but I understand it may not
be trivial to determine automatically which other minor mode keys are
relevant.

But the major mode keys are surely relevant for usage, so they could
come first in Help.

 

[-- Attachment #2: Type: text/html, Size: 3769 bytes --]

Re: More useful mode help?

[Eli Zaretskii]

> From: ndame <emacsuser@freemail.hu>
> Date: Fri, 20 Sep 2019 10:57:49 +0200 (CEST)
> 
> The first thing in the mode help:
> 
>   Enabled minor modes: Abbrev Auto-Composition Auto-Compression
>   Auto-Encryption Auto-Insert Blink-Cursor Column-Number
>   Delete-Selection Diff-Auto-Refine Electric-Indent Electric-Pair
>   File-Name-Shadow Font-Lock Global-Aggressive-Indent Global-Eldoc
>   Global-Font-Lock Iswitchb Line-Number Minibuffer-Depth-Indicate
>   Mouse-Wheel Recentf Save-Place Savehist Shell-Dirtrack Tooltip
>   Transient-Mark Winner
> 
> Is there a reason why this comes first?

So that users could know, without reading all of the process-menu-mode
description, that the other minor modes are described below, and could
also jump there if that is what they want.

> Doesn't seem too relevant if
> the user simply wants to find out about how to use the current mode.

Yours is just one of the possible use cases we want to support; there
are others, where the exact opposite is true.

The beginning of the process-menu-mode's key bindings is actually
visible in the buffer that pops up, so I don't see a problem with the
preamble, it doesn't cause the text you wanted to see to become
obscured.

> Then comes the process description mentioning which hook run. Still
> not very useful if one wants to simply use the mode.

Again, that's just one of the use cases.  Mode hooks is something
people want to know about frequently, because that lets them customize
the mode.

> As you can see the single process binding is in the middle and it's d.

I hope you now understand why we arranged the information as we did.