Andreas Röhler<address@hidden> 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
org-texi.patch