From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?ISO-8859-1?Q?Andreas_R=F6hler?= Subject: Re: Re: keys and command name info Date: Wed, 11 Aug 2010 12:23:49 +0200 Message-ID: <4C627A35.7090701@easy-emacs.de> References: <4C5086C1.9060000@easy-emacs.de> <20100808222636.GF20223@shi.workgroup> <770A61DC-4063-4A72-95F2-21F4E7DE6E77@gmail.com> <87fwyom8iv.fsf@gmx.net> <20100809101957.GC14007@shi.workgroup> <878w4f4oy4.fsf@stats.ox.ac.uk> <87tyn337rm.fsf@stats.ox.ac.uk> <21306250-E2A2-46A7-BFB5-891034F3FA59@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 8bit Return-path: Received: from [140.186.70.92] (port=50233 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Oj8UZ-0005gZ-Bk for emacs-orgmode@gnu.org; Wed, 11 Aug 2010 06:25:04 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Oj8UW-0000ar-FX for emacs-orgmode@gnu.org; Wed, 11 Aug 2010 06:25:02 -0400 Received: from moutng.kundenserver.de ([212.227.17.10]:51700) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Oj8UW-0000aW-0S for emacs-orgmode@gnu.org; Wed, 11 Aug 2010 06:25:00 -0400 In-Reply-To: <21306250-E2A2-46A7-BFB5-891034F3FA59@gmail.com> 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: Dan Davison , emacs-orgmode Am 11.08.2010 12:05, schrieb Carsten Dominik: > > On Aug 9, 2010, at 9:28 PM, Dan Davison wrote: > >> Dan Davison writes: >> >>> Gregor Zattler writes: >>> >>>> Hi Andreas, org-mode developers, >>>> * Andreas Burtzlaff [09. Aug. 2010]: >>>>> Carsten Dominik writes: >>>>>> 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) >>> >>> I would like the command names in the manual. >>> >>> - Emacs-lisp has a lovely tradition of naming functions *very* >>> descriptively and not being afraid to use long names in the interests >>> of accuracy. It's a shame to lose all that by displaying only key >>> sequences. It's a linguistic world of its own and I like being exposed >>> to it. >>> - While one can do C-h k, that's not the same as the way one learns the >>> function names by skimming the manual >> >> Also, it does not add length to the HTML version of the manual, because >> the key sequences are already on a line of their own. And the same is >> true for a certain proportion of the pdf entries (when the key sequence >> is long, then it seems to go on its own line). >> >> >>> >>>>>> - 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. >>> >>> I definitely would want them out on a line of their own with the key >>> sequence. I liked the right-aligned model. >>> >>> Or if not right-aligned, is it possible not to have the comma? Maybe a >>> different font? > > I also like the position on the key line best. So if there is a > more-or-less > general agreement that we should get the names in, this would be my > preferred > location as well. I knot that this is different from what the emacs > and gnus manuals do - but I still think that a solution like this would > be better. > > Andreas, can you be bothered to rework the patch? > > Unfortunately I have no idea if/how the right-aligned model could be > made to > work. So I think the safest way to do this would be to introduce the macro, > and we can then work on the macro to get the formatting right, and also > to do the > key and function index stuff fully automatically. > > Here is my proposal for now: > > @macro orgcmd{key,command} > @kindex \key\ > @findex \command\ > @item \key\ @ @ @ @ @ @ @ @ @ @ @r{(}\command\@r{)} > @end macro > > And then define keys/commands like this: > > @table @kbd > ..... > @orgcmd{@key{TAB}, org-cycle} > Here follows the description of the command > .... > @end table > > - Carsten OK, I'm on it next days. Cheers Andreas > > > > >>> >>> Dan >>> >>>>> >>>>> 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. >>>> >>>> +1 for the same reasons. >>>> >>>> This is especially true for paragraphs like those: >>>> >>>> C-c C-n (outline-next-visible-heading) Next heading. >>>> C-c C-p (outline-previous-visible-heading) Previous heading. >>>> C-c C-f (org-forward-same-level) Next heading same level. >>>> C-c C-b (org-backward-same-level) Previous heading same level. >>>> C-c C-u (outline-up-heading) Backward to higher level heading. >>>> C-c C-j (org-goto) Jump to a different place without changing the >>>> current outline >>>> visibility. Shows the document structure in a temporary buffer, >>>> where you can >>>> use the following keys to find your destination: >>>> >>>> >>>>> 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. >>>> >>>> +1 for the same reasons. >>>> But Andreas Röhlers original variant is IMHO even better: >>>> >>>>> | [ ... ] >>>>> | `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 Argument, file is added/moved to the end. >>> >>> Yes, but let's lose the extra comma. >>> >>> `C-c [' org-agenda-file-to-front >>> >>> >>> >>> >>> >>>> >>>> Here the command name serves as a kind of a heading, it's easy >>>> to search these locations while at the same time it's easy to >>>> skim over the pages and not bother with the command names. >>>> >>>> >>>> >>>> My preference: >>>> >>>> 1. as in Andreas Röhlers original ASCII rendering >>>> 2. as in Andreas Burtzlaffs ASCII rendering >>>> 3. not at all >>>> 4. as in the test manual >>>> >>>> >>>> >>>> Just me 2¢. Either way, org-mode is great. Gregor >>>> >>>> >>>> P.S.: Some of the command names don't help that much: >>>> >>>> C-c C-c (org-ctrl-c-ctrl-c) If there is a checkbox (see Section 5.6 >>>> [Checkboxes], >>>> page 46) in the item line, toggle the state of the checkbox. If not, >>>> this command >>>> makes sure that all the items on this list level use the same >>>> bullet. Furthermore, >>>> if this is an ordered list, make sure the numbering is OK. >>>> C-c - (org-ctrl-c-minus) Cycle the entire list level through the >>>> different item- >>>> ize/enumerate bullets (`-', `+', `*', `1.', `1)'). With a numeric >>>> prefix argument >>>> N, select the Nth bullet from this list. If there is an active >>>> region when calling >>>> this, all lines will be converted to list items. If the first line >>>> already was a list >>>> item, any item markers will be removed from the list. Finally, even >>>> without an >>>> active region, a normal line will be converted into a list item. >>>> C-c * (org-ctrl-c-star) Turn a plain list item into a headline (so >>>> that it becomes >>>> a subheading at its location). See Section 2.5 [Structure editing], >>>> page 7, for a >>>> detailed explanation. >>>> >>>> But even this gives a clue in how it all works. >>>> >