Re: Re: keys and command name info

From: "Andreas Röhler" <andreas.roehler@easy-emacs.de>
To: Carsten Dominik <dominik@uva.nl>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Re: keys and command name info
Date: Fri, 20 Aug 2010 08:27:07 +0200	[thread overview]
Message-ID: <4C6E203B.8020900@easy-emacs.de> (raw)
In-Reply-To: <06DED7B3-E7C1-4389-BAE8-0C319A1DF7FD@uva.nl>

Am 18.08.2010 10:38, schrieb Carsten Dominik:
> Hi Andreas,
>
> this already goes in the right direction.
>
> I have a better definition for the macro, which does now
> push the command name all the way to the right (in PDF output).
> I hated the look of the command name separated by a fixed
> number of spaces - this is a lot better.
> Does anyone know how to do this for HTML and info?
>
> @macro orgcmd{key,command}
> @iftex
> @kindex \key\
> @findex \command\
> @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
> @end iftex
> @ifnottex
> @kindex \key\
> @findex \command\
> @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
> @end ifnottex
> @end macro
>
> Also, since the table is now an @asis table, lines which do not
> have a command name like
>
> @item C-u C-u C-u @key{TAB}
>
> will need an explicit formatting command, like this:
>
> @item @kbd{C-u C-u C-u @key{TAB}}
>
> Alternatively, we could have another macro
>
> @macro orgkey{key}
> @item @kbd{\key\}
> @end macro
>
> so that we could write keys for which we have no command name
> like this:
>
> @orgkey{C-u C-u C-u @key{TAB}}
>
> Hope this gets you on your way with a tideous task....

Hmm,

I'm afraid this starts walking the desert.
May be it helps keeping things apart for the beginning.

1) Introducing the command names
2) Completing the formatting

As views are different concerning the latter, thats a rather hard task 
for me, as I can't see the progress...

For me it's important seeing command names somewhere near its keys.
If beneath or at the right, doesn't matter that much IMHO.

>
> One more thing: I do frequently small changes in the manual,
> so please make sure to update your patch to the most recent
> version of Org.
>
>
>> Please have a look at lines 1097 and 1379.
>> Looks like an erronius replacements.
>> As its done by a script, ...
>
> Well, hand checking will absolutely be necessary with this patch.

Did that. Cancelled the warning already. Seems you didn't get the mail.

What about checkin in the patch as it's done so far?

Andreas

> Hope you can do as much as possible of that as well, maybe with
> comments in the text to get my attention to certain places.
>
> - Carsten
>
> On Aug 17, 2010, at 2:43 PM, Andreas Röhler wrote:
>
>> Am 16.08.2010 10:57, schrieb Carsten Dominik:
>>>
>>> On Aug 15, 2010, at 9:07 PM, Andreas Röhler wrote:
>>>
>>>> Am 15.08.2010 09:39, schrieb Carsten Dominik:
>>>>>
>>>>> 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
>>>>>
>>>>
>>>> Hi,
>>>>
>>>> will do that.
>>>>
>>>> Let us check nonetheless a working example first.
>>>>
>>>> While trying to put @asis at the right place, I get error messages and
>>>> it refuses to compile.
>>>>
>>>> Could you re-write the example for me?
>>>>
>>>> Sorry being that stupid :-)
>>>>
>>>> Andreas
>>>
>>> I mean it like this:
>>>
>>> @macro orgcmd{key,command}
>>> @kindex \key\
>>> @findex \command\
>>> @item @kbd{\key\} @ @ @ @ @ @ @ @ @ @ (@code{\command}\)
>>> @end macro
>>>
>>> And then define keys/commands like this:
>>>
>>> @table @asis
>>> .....
>>> @orgcmd{C-c C-x @key{TAB}, org-cycle}
>>> Here follows the description of the command
>>> ....
>>> @end table
>>>
>>>
>>> Does this work?
>>>
>>> - Carsten
>>
>>
>> Think so, thanks.
>> Patch relying upon attached.
>>
>>
>>
>> Andreas
>> <texi.patch>_______________________________________________
>> 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
>
>
>