Andreas Röhler <andreas.roeh...@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
_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode
