Re: keys and command name info

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

Andreas Röhler <andreas.roehler@easy-emacs.de> writes:

Hi Andreas,

> what about delivering mnemonic command names alongside with its keys
> in org-info?

That would be good practice, and I think it's more or less standard for
emacs packages.  For example, that is from Gnus:

,----[ (info "(gnus)Summary Post Commands") ]
| `S p'
| `a'
|      Prepare for posting an article (`gnus-summary-post-news').  By
|      default, post to the current group.  If given a prefix, disable
|      that.  If the prefix is 1, prompt for another group instead.
| 
| `S f'
| `f'
|      Post a followup to the current article (`gnus-summary-followup').
`----

> 8.1. Agenda files
>
> [ ... ]
> `C-c ['
>      Add current file to the list of agenda files.  The file is added to
>      the front of the list.  If it was already in the list, it is moved
>      to the front.  With prefix arg, file is added/moved to the end.
>
> might be provided as
>
> 8.1. Agenda files
>
> [ ... ]
> `C-c [', org-agenda-file-to-front
>      Add current file to the list of agenda files.  The file is added to
>      the front of the list.  If it was already in the list, it is moved
>      to the front.  With prefix arg, file is added/moved to the end.

I'd write it in parens with the usual function markup at the end of the
first sentence, just like it's done in Gnus.  The 2 Gnus entries above
have this definition:

--8<---------------cut here---------------start------------->8---
@table @kbd
@item S p
@itemx a
@kindex a (Summary)
@kindex S p (Summary)
@findex gnus-summary-post-news
@c @icon{gnus-summary-post-news}
Prepare for posting an article (@code{gnus-summary-post-news}).  By
default, post to the current group.  If given a prefix, disable that.
If the prefix is 1, prompt for another group instead.

@item S f
@itemx f
@kindex f (Summary)
@kindex S f (Summary)
@findex gnus-summary-followup
@c @icon{gnus-summary-followup}
Post a followup to the current article (@code{gnus-summary-followup}).
--8<---------------cut here---------------end--------------->8---

So basically, you only have to add the command name with @code{} at the
appropriate place and add an index item to the function index with
@findex{}.

> IMHO it's useful for emacs-beginners, but for hackers too, as
> remembering function names may precede remembering keys - which are to
> change individually anyway.

Exactly, and using `C-h f' you can easily switch to *Help* to lookup the
exact docstring and signature.  And from *Help*, the function definition
is only one click away.

> Should you be interested, I'll consider to take action with
> texi-files.

I'd welcome such an enhancement to the docs, and I'm pretty sure nobody
will object. :-)

Bye,
Tassilo