Re: keys and command name info

From: Dan Davison <davison@stats.ox.ac.uk>
To: "Andreas Röhler" <andreas.roehler@easy-emacs.de>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
	Carsten Dominik <carsten.dominik@gmail.com>
Subject: Re: keys and command name info
Date: Fri, 13 Aug 2010 10:20:34 -0400	[thread overview]
Message-ID: <87hbiyh9vx.fsf@stats.ox.ac.uk> (raw)
In-Reply-To: <4C654C8F.8050005@easy-emacs.de> ("Andreas Röhler"'s message of "Fri, 13 Aug 2010 15:45:51 +0200")

Andreas Röhler <andreas.roehler@easy-emacs.de> writes:

> 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.
>>
>
> Hi Carsten, Hi all,
>
> please permit some reflection again at this point, to get it out of my head:
>
> Agree right-aligned is the more pretty from the graphical point.
> But is it the most suitable from ergonomics?
>
> Doubt that.
> When reading the key, eyes are at the left corner (at least in
> english... :)
> If looking left, text on the right sight is not in focus.
> Would require an eye-move.

Which could be argued to be an advantage, because Carsten's original
ideas was that new non-programmer users would not want to know function
names. If those of us that do want to learn function names are prepared
to pay the cost in muscular contractions, then right-aligned could be a
good compromise.

> If the command is placed next or below, what I prefer meanwhile, as
> separating commata is nasty somehow,

When you say below, do you mean on its own line or as the first words of
the text? I believe there was a majority vote against the latter.

Dan

> it should safe some energy.
>
> Andreas
>
>
>
>
>
>
>
>
>> 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
>>
>>
>>
>>
>>>>
>>>> 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.
>>>>>
>>>>> _______________________________________________
>>>>> 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
>>
>>
>>
>>
>
>
> _______________________________________________
> 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