Re: Re: keys and command name info

["Andreas Röhler" <andreas.roehler@easy-emacs.de>]

Am 11.08.2010 12:05, schrieb Carsten Dominik:
>
> On Aug 9, 2010, at 9:28 PM, Dan Davison wrote:
>
>> Dan Davison <davison@stats.ox.ac.uk> writes:
>>
>>> Gregor Zattler <telegraph@gmx.net> writes:
>>>
>>>> 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)
>>>
>>> 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.
>>>>

>