Re: [Orgmode] Re: keys and command name info

[Andreas Röhler]

Am 20.08.2010 09:31, schrieb Carsten Dominik:
> Hi Andreas,
>
> On Aug 20, 2010, at 8:27 AM, Andreas Röhler wrote:
>
> > 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\} @address@hidden@address@hidden(@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.
>
> I am not sure what the problem is.


> For keys where you have a command name, you continue as you have been
> doing.
> For keys where you do not have the command names, just enclose the key
> after the @item into @kbd{...}
>
> This should get you very far.

Hi Carsten,

so let's proceed.

Patch attached.

Andreas



> I am not sure if I have the most recent patch - can you
> please send it again, so that I can check it?
>
> Thanks.
>
> - Carsten
>
>
> > > 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 <address@hidden> writes:
> > > > > > > > > > >
> > > > > > > > > > > > Gregor Zattler <address@hidden> writes:
> > > > > > > > > > > >
> > > > > > > > > > > > > Hi Andreas, org-mode developers,
> > > > > > > > > > > > > * Andreas Burtzlaff <address@hidden> [09. Aug. 2010]:
> > > > > > > > > > > > > > Carsten Dominik <address@hidden> 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{(address@hidden)}
> > > > > > > > > > @end macro
> > > > > > > > > >
> > > > > > > > > > And then define keys/commands like this:
> > > > > > > > > >
> > > > > > > > > > @table @kbd
> > > > > > > > > > .....
> > > > > > > > > > @address@hidden, 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.
> > > > address@hidden
> > > > http://lists.gnu.org/mailman/listinfo/emacs-orgmode
> >
> >
> > _______________________________________________
> > Emacs-orgmode mailing list
> > Please use `Reply All' to send replies to the list.
> > address@hidden
> > http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>
> - Carsten

org-texi.patch
Description: Text Data