Re: Re: keys and command name info

From: "Andreas Röhler" <andreas.roehler@easy-emacs.de>
To: Carsten Dominik <carsten.dominik@gmail.com>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Re: keys and command name info
Date: Fri, 13 Aug 2010 21:30:43 +0200	[thread overview]
Message-ID: <4C659D63.1090003@easy-emacs.de> (raw)
In-Reply-To: <21306250-E2A2-46A7-BFB5-891034F3FA59@gmail.com>

[-- Attachment #1: Type: text/plain, Size: 3158 bytes --]

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.

Also diff for the code applied.

Andreas

[-- Attachment #2: texi.diff --]
[-- Type: text/x-patch, Size: 653 bytes --]

diff --git a/doc/org.texi b/doc/org.texi
index ac52c70..05ef8eb 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -22,6 +22,11 @@
 @finalout
 
 @c Macro definitions
+@macro orgcmd{key,command}
+@kindex \key\
+@findex \command\
+@item \key\ @ @ @ @ @ @ @ @ @ @ @r{(}\command\@r{)}
+@end macro
 @iftex
 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
 @end iftex
@@ -1006,8 +1011,9 @@ Previous heading.
 @kindex C-c C-f
 @item C-c C-f
 Next heading same level.
-@kindex C-c C-b
-@item C-c C-b
+@orgcmd{C-c C-b, org-backward-same-level}
+@c @kindex C-c C-b
+@c @item C-c C-b
 Previous heading same level.
 @kindex C-c C-u
 @item C-c C-u

[-- Attachment #3: org-texi.png --]
[-- Type: image/png, Size: 67164 bytes --]

[-- Attachment #4: Type: text/plain, Size: 201 bytes --]

_______________________________________________
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
