Re: Re: keys and command name info

[Carsten Dominik <dominik@uva.nl>]

On Aug 15, 2010, at 9:37 AM, Carsten Dominik wrote:

>
> On Aug 13, 2010, at 9:30 PM, Andreas Röhler wrote:
>
>> 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
>>>
>>>
>> [ ... ]
>>
>> Hi Carsten,
>>
>> attached a sreenshot, how it comes out for C-c C-b.
>> Doesn't look ok for me, as back-tick and quote are uncommon that way.
>
> Hi Andreas, you are correct, this does not look right.
> Seems like we will have to make the table ins @asis and
> then have the macro apply the formatting.  Sigh... :)

If you do insert all the macro calls with the command names, I will  
take care of the formatting.

- Carsten