From mboxrd@z Thu Jan 1 00:00:00 1970 From: Tassilo Horn Subject: Re: keys and command name info Date: Thu, 29 Jul 2010 08:45:19 +0200 Message-ID: <87zkxa7pmo.fsf@member.fsf.org> References: <4C5086C1.9060000@easy-emacs.de> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from [140.186.70.92] (port=54589 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OeMs8-0003T0-8e for emacs-orgmode@gnu.org; Thu, 29 Jul 2010 02:45:41 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OeMs6-0002SK-P9 for emacs-orgmode@gnu.org; Thu, 29 Jul 2010 02:45:40 -0400 Received: from lo.gmane.org ([80.91.229.12]:38177) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OeMs6-0002S0-CN for emacs-orgmode@gnu.org; Thu, 29 Jul 2010 02:45:38 -0400 Received: from list by lo.gmane.org with local (Exim 4.69) (envelope-from ) id 1OeMrw-0001sR-Jd for emacs-orgmode@gnu.org; Thu, 29 Jul 2010 08:45:28 +0200 Received: from tsdh.uni-koblenz.de ([141.26.67.142]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 29 Jul 2010 08:45:28 +0200 Received: from tassilo by tsdh.uni-koblenz.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 29 Jul 2010 08:45:28 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Andreas Röhler 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