From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andreas Burtzlaff Subject: Re: keys and command name info Date: Mon, 09 Aug 2010 11:37:28 +0200 Message-ID: <87fwyom8iv.fsf@gmx.net> References: <4C5086C1.9060000@easy-emacs.de> <20100808222636.GF20223@shi.workgroup> <770A61DC-4063-4A72-95F2-21F4E7DE6E77@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from [140.186.70.92] (port=56661 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OiOn2-00067q-6U for emacs-orgmode@gnu.org; Mon, 09 Aug 2010 05:37:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OiOn0-0002G4-R3 for emacs-orgmode@gnu.org; Mon, 09 Aug 2010 05:37:04 -0400 Received: from mailout-de.gmx.net ([213.165.64.23]:54785 helo=mail.gmx.net) by eggs.gnu.org with smtp (Exim 4.69) (envelope-from ) id 1OiOn0-0002Fk-FR for emacs-orgmode@gnu.org; Mon, 09 Aug 2010 05:37:02 -0400 In-Reply-To: <770A61DC-4063-4A72-95F2-21F4E7DE6E77@gmail.com> (Carsten Dominik's message of "Mon, 9 Aug 2010 08:43:21 +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: Carsten Dominik Cc: emacs-orgmode Carsten Dominik writes: > On Aug 9, 2010, at 12:26 AM, Gregor Zattler wrote: > >> Hi Carsten, org-mode developers, >> * Carsten Dominik [02. Aug. 2010]: >>> I am not sure I would like such a change because I think it >>> makes the manual harder and less fluid to read and considerably >>> longer. >> >> It makes the manual longer as in bytes/bandwidth but not as in >> lines which IMHO corresponds with the amount of time one needs to >> read the manual. >> >> If it's consistent within the manual it's IMHO not confusing or >> harder to read because it's easy to skip. >> >> To me actually this hints look like headings. They would support >> me in skimming a section of commands in order to find the right >> one. Those paragraphs with key sequences at the beginning are >> hard to skim because all the info which stands out is not >> relevant if one searches for a specific action. >> >> Seeing how the command is named in the context of usage >> information might help lisp novices in getting an idea why some >> solutions work the way they do. > > Hi Gregor, thanks for chiming in and summarizing your arguments. > And that you say it makes it easier to find the right command > may be a good argument to insert the command names. > > Some of the original arguments, that these names would stick > more easily and that it would make it easy for a hacker to > find the command name for rebinding, these do not fly, I think. > I don't think anyone calls Org commands with M-x, and if a > hacker needs to find a command name, `C-h b' and in particular > `C-h k' are the perfect ways to get to the names. > > I have put a version of the manual as modified by Andreas here: > > http://orgmode.org/org-manual-with-command-names.pdf > > Not all the command names are in there, but quite a few are. > I'd like to hear from more people > > - if they would like to have the names there (i.e. if it would > help them finding a command) > - if the position (first thing in the command description) > is right, or if it would be better to have it > - last thing in the description > - or after the first sentence, this is how the GNUS manual > does it. Having the function names in the manual at all makes it look a bit overloaded and might lose us a couple of newbies, I think. Personally, I would not have use for it. If the names are included in the manual I strongly object to them being at the beginning of the first sentence. The fixed starting column of the sentences becomes variable and that makes it hard to skim through for those who don't want to read the function names. What about having them in the same line as the keybinding but aligned to the right? `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. It would make the manual longer, but at least it looks clean. It is easy to neglect the function names if one wants, and just as easy to skim through them. Andreas > > Thanks to Andreas for his work so far, and please, let me > hear more opinions. > > - Carsten > > > > > _______________________________________________ > 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