Re: Re: keys and command name info

From: Carsten Dominik <carsten.dominik@gmail.com>
To: Gregor Zattler <telegraph@gmx.net>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Re: keys and command name info
Date: Mon, 9 Aug 2010 12:31:51 +0200	[thread overview]
Message-ID: <3781A4D8-2A56-4755-A5B2-DEF018E13AA7@gmail.com> (raw)
In-Reply-To: <20100809101957.GC14007@shi.workgroup>

On Aug 9, 2010, at 12:19 PM, Gregor Zattler wrote:

> Hi Andreas, org-mode developers,
> * Andreas Burtzlaff <andy13@gmx.net> [09. Aug. 2010]:
>> Carsten Dominik <carsten.dominik@gmail.com> 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)
>>> - 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.
>
> +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.
>
> 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.

For these cases the dispatcher command could be replaced with the  
specific command that will be
called by the dispatcher when in this context......

- Carsten

>
> 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

- Carsten