From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: Re: keys and command name info Date: Wed, 11 Aug 2010 12:05:03 +0200 Message-ID: <21306250-E2A2-46A7-BFB5-891034F3FA59@gmail.com> 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> Mime-Version: 1.0 (Apple Message framework v936) Content-Type: text/plain; charset=ISO-8859-1; format=flowed; delsp=yes Content-Transfer-Encoding: quoted-printable Return-path: Received: from [140.186.70.92] (port=33070 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Oj8Be-0005Gn-Rr for emacs-orgmode@gnu.org; Wed, 11 Aug 2010 06:08:28 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Oj8BN-0005lL-80 for emacs-orgmode@gnu.org; Wed, 11 Aug 2010 06:05:14 -0400 Received: from mail-ew0-f41.google.com ([209.85.215.41]:57728) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Oj8BM-0005lE-VH for emacs-orgmode@gnu.org; Wed, 11 Aug 2010 06:05:13 -0400 Received: by ewy28 with SMTP id 28so4706104ewy.0 for ; Wed, 11 Aug 2010 03:05:12 -0700 (PDT) In-Reply-To: <87tyn337rm.fsf@stats.ox.ac.uk> 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: Dan Davison , =?ISO-8859-1?Q?Andreas_R=F6hler?= Cc: emacs-orgmode 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 =20 >> 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 =20 >> exposed >> to it. >> - While one can do C-h k, that's not the same as the way one learns =20= >> the >> function names by skimming the manual > > Also, it does not add length to the HTML version of the manual, =20 > 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 =20 > 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? =20 >> Maybe a >> different font? I also like the position on the key line best. So if there is a more-=20= or-less general agreement that we should get the names in, this would be my =20 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 =20 made to work. So I think the safest way to do this would be to introduce the =20= macro, and we can then work on the macro to get the formatting right, and =20 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 >> >> 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. =20 >>>> Personally, I >>>> would not have use for it. >>>> >>>> If the names are included in the manual I strongly object to them =20= >>>> being >>>> at the beginning of the first sentence. The fixed starting column =20= >>>> of the >>>> sentences becomes variable and that makes it hard to skim through =20= >>>> 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 =20= >>> current outline >>> visibility. Shows the document structure in a temporary =20 >>> buffer, where you can >>> use the following keys to find your destination: >>> >>> >>>> What about having them in the same line as the keybinding but =20 >>>> aligned to >>>> the right? >>>> >>>> `C-c [' org-agenda-file-=20 >>>> to-front >>>> Add current file to the list of agenda files. The file is =20 >>>> added to >>>> the front of the list. If it was already in the list, it is =20= >>>> 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 =20 >>>> as easy >>>> to skim through them. >>> >>> +1 for the same reasons. >>> But Andreas R=F6hlers 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 =20= >>>> added to >>>> | the front of the list. If it was already in the list, it =20 >>>> is moved >>>> | to the front. With prefix Argument, file is added/moved to =20= >>>> 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=F6hlers original ASCII rendering >>> 2. as in Andreas Burtzlaffs ASCII rendering >>> 3. not at all >>> 4. as in the test manual >>> >>> >>> >>> Just me 2=A2. 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 =20 >>> 5.6 [Checkboxes], >>> page 46) in the item line, toggle the state of the =20 >>> checkbox. If not, this command >>> makes sure that all the items on this list level use the =20 >>> 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 =20= >>> different item- >>> ize/enumerate bullets (`-', `+', `*', `1.', `1)'). With a =20 >>> numeric prefix argument >>> N, select the Nth bullet from this list. If there is an =20 >>> active region when calling >>> this, all lines will be converted to list items. If the =20 >>> first line already was a list >>> item, any item markers will be removed from the list. =20 >>> Finally, even without an >>> active region, a normal line will be converted into a list =20= >>> item. >>> C-c * (org-ctrl-c-star) Turn a plain list item into a headline =20 >>> (so that it becomes >>> a subheading at its location). See Section 2.5 [Structure =20 >>> editing], page 7, for a >>> detailed explanation. >>> >>> But even this gives a clue in how it all works. >>> >>> _______________________________________________ >>> 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 >> >> _______________________________________________ >> 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 > > _______________________________________________ > 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 - Carsten