emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
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: Tue, 17 Aug 2010 14:43:14 +0200	[thread overview]
Message-ID: <4C6A83E2.9020304@easy-emacs.de> (raw)
In-Reply-To: <DB628FE2-2233-45F2-9B1F-69D64654FFD2@uva.nl>

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

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.

Please have a look at lines 1097 and 1379.
Looks like an erronius replacements.
As its done by a script, ...


Andreas

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

diff --git a/doc/org.texi b/doc/org.texi
index 1624111..5cb1878 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
@@ -898,9 +903,8 @@ Org uses just two commands, bound to @key{TAB} and
 @cindex folded, subtree visibility state
 @cindex children, subtree visibility state
 @cindex subtree, subtree visibility state
-@table @kbd
-@kindex @key{TAB}
-@item @key{TAB}
+@table @asis
+@orgcmd{@key{TAB}, org-cycle}
 @emph{Subtree cycling}: Rotate current subtree among the states
 
 @example
@@ -940,19 +944,16 @@ tables, @kbd{S-@key{TAB}} jumps to the previous field.
 @kindex C-u C-u C-u @key{TAB}
 @item C-u C-u C-u @key{TAB}
 Show all, including drawers.
-@kindex C-c C-r
-@item C-c C-r
+@orgcmd{C-c C-r, org-reveal}
 Reveal context around point, showing the current entry, the following heading
 and the hierarchy above.  Useful for working near a location that has been
 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
 (@pxref{Agenda commands}).  With a prefix argument show, on each
 level, all sibling headings.  With double prefix arg, also show the entire
 subtree of the parent.
-@kindex C-c C-k
-@item C-c C-k
+@orgcmd{C-c C-k, org-kill-note-or-show-branches}
 Expose all the headings of the subtree, CONTENT view for just one subtree.
-@kindex C-c C-x b
-@item C-c C-x b
+@orgcmd{C-c C-x b, org-tree-to-indirect-buffer}
 Show the current subtree in an indirect buffer@footnote{The indirect
 buffer
 @ifinfo
@@ -1009,24 +1010,18 @@ entries.
 @cindex headline navigation
 The following commands jump to other headlines in the buffer.
 
-@table @kbd
-@kindex C-c C-n
-@item C-c C-n
+@table @asis
+@orgcmd{C-c C-n, outline-next-visible-heading}
 Next heading.
-@kindex C-c C-p
-@item C-c C-p
+@orgcmd{C-c C-p, outline-previous-visible-heading}
 Previous heading.
-@kindex C-c C-f
-@item C-c C-f
+@orgcmd{C-c C-f, org-forward-same-level}
 Next heading same level.
-@kindex C-c C-b
-@item C-c C-b
+@orgcmd{C-c C-b, org-backward-same-level}
 Previous heading same level.
-@kindex C-c C-u
-@item C-c C-u
+@orgcmd{C-c C-u, outline-up-heading}
 Backward to higher level heading.
-@kindex C-c C-j
-@item C-c C-j
+@orgcmd{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:
@@ -1061,9 +1056,8 @@ See also the variable @code{org-goto-interface}.
 @cindex sorting, of subtrees
 @cindex subtrees, cut and paste
 
-@table @kbd
-@kindex M-@key{RET}
-@item M-@key{RET}
+@table @asis
+@orgcmd{M-@key{RET}, org-insert-heading}
 @vindex org-M-RET-may-split-line
 Insert new heading with same level as current.  If the cursor is in a
 plain list item, a new item is created (@pxref{Plain lists}).  To force
@@ -1093,47 +1087,36 @@ variable @code{org-treat-insert-todo-heading-as-state-change}.
 Insert new TODO entry with same level as current heading.  Like
 @kbd{C-@key{RET}}, the new headline will be inserted after the current
 subtree.
-@kindex @key{TAB}
-@item @key{TAB} @r{in new, empty entry}
+@orgcmd{@key{TAB}, org-cycle}
 In a new entry with no text yet, the first @key{TAB} demotes the entry to
 become a child of the previous one.  The next @key{TAB} makes it a parent,
 and so on, all the way to top level.  Yet another @key{TAB}, and you are back
 to the initial level.
-@kindex M-@key{left}
-@item M-@key{left}
+@orgcmd{M-@key{left}, org-metaleft}
 Promote current heading by one level.
-@kindex M-@key{right}
-@item M-@key{right}
+@orgcmd{M-@key{right}, org-metaright}
 Demote current heading by one level.
-@kindex M-S-@key{left}
-@item M-S-@key{left}
+@orgcmd{M-S-@key{left}, org-shiftmetaleft}
 Promote the current subtree by one level.
-@kindex M-S-@key{right}
-@item M-S-@key{right}
+@orgcmd{M-S-@key{right}, org-shiftmetaright}
 Demote the current subtree by one level.
-@kindex M-S-@key{up}
-@item M-S-@key{up}
+@orgcmd{M-S-@key{up}, org-shiftmetaup}
 Move subtree up (swap with previous subtree of same
 level).
-@kindex M-S-@key{down}
-@item M-S-@key{down}
+@orgcmd{M-S-@key{down}, org-shiftmetadown}
 Move subtree down (swap with next subtree of same level).
-@kindex C-c C-x C-w
-@item C-c C-x C-w
+@orgcmd{C-c C-x C-w, org-cut-special}
 Kill subtree, i.e. remove it from buffer but save in kill ring.
 With a numeric prefix argument N, kill N sequential subtrees.
-@kindex C-c C-x M-w
-@item C-c C-x M-w
+@orgcmd{C-c C-x M-w, org-copy-special}
 Copy subtree to kill ring.  With a numeric prefix argument N, copy the N
 sequential subtrees.
-@kindex C-c C-x C-y
-@item C-c C-x C-y
+@orgcmd{C-c C-x C-y, org-paste-special}
 Yank subtree from kill ring.  This does modify the level of the subtree to
 make sure the tree fits in nicely at the yank position.  The yank level can
 also be specified with a numeric prefix argument, or by yanking after a
 headline marker like @samp{****}.
-@kindex C-y
-@item C-y
+@orgcmd{C-y, org-yank}
 @vindex org-yank-adjusted-subtrees
 @vindex org-yank-folded-subtrees
 Depending on the variables @code{org-yank-adjusted-subtrees} and
@@ -1146,19 +1129,16 @@ previously visible.  Any prefix argument to this command will force a normal
 force a normal yank is @kbd{C-u C-y}.  If you use @code{yank-pop} after a
 yank, it will yank previous kill items plainly, without adjustment and
 folding.
-@kindex C-c C-x c
-@item C-c C-x c
+@orgcmd{C-c C-x c, org-clone-subtree-with-time-shift}
 Clone a subtree by making a number of sibling copies of it.  You will be
 prompted for the number of copies to make, and you can also specify if any
 timestamps in the entry should be shifted.  This can be useful, for example,
 to create a number of tasks related to a series of lectures to prepare.  For
 more details, see the docstring of the command
 @code{org-clone-subtree-with-time-shift}.
-@kindex C-c C-w
-@item C-c C-w
+@orgcmd{C-c C-w, org-refile}
 Refile entry or region to a different location.  @xref{Refiling notes}.
-@kindex C-c ^
-@item C-c ^
+@orgcmd{C-c ^, org-sort}
 Sort same-level entries.  When there is an active region, all entries in the
 region will be sorted.  Otherwise the children of the current headline are
 sorted.  The command prompts for the sorting method, which can be
@@ -1175,8 +1155,7 @@ Narrow buffer to current subtree.
 @kindex C-x n w
 @item C-x n w
 Widen buffer to remove narrowing.
-@kindex C-c *
-@item C-c *
+@orgcmd{C-c *, org-ctrl-c-ctrl-c}
 Turn a normal line or plain list item into a headline (so that it becomes a
 subheading at its location).  Also turn a headline into a normal line by
 removing the stars.  If there is an active region, turn all lines in the
@@ -1220,9 +1199,8 @@ and you will see immediately how it works.
 Org-mode contains several commands creating such trees, all these
 commands can be accessed through a dispatcher:
 
-@table @kbd
-@kindex C-c /
-@item C-c /
+@table @asis
+@orgcmd{C-c /, org-sparse-tree}
 This prompts for an extra key to select a sparse-tree creating command.
 @kindex C-c / r
 @item C-c / r
@@ -1347,9 +1325,8 @@ the current list-level) improves readability, customize the variable
 The following commands act on items when the cursor is in the first line
 of an item (the line with the bullet or number).
 
-@table @kbd
-@kindex @key{TAB}
-@item @key{TAB}
+@table @asis
+@orgcmd{@key{TAB}, org-cycle}
 @vindex org-cycle-include-plain-lists
 Items can be folded just like headline levels.  Normally this works only if
 the cursor is on a plain list item.  For more details, see the variable
@@ -1360,8 +1337,7 @@ headlines, however; the hierarchies remain completely separated.
 
 If @code{org-cycle-include-plain-lists} has not been set, @key{TAB}
 fixes the indentation of the current line in a heuristic way.
-@kindex M-@key{RET}
-@item M-@key{RET}
+@orgcmd{M-@key{RET}, org-insert-heading}
 @vindex org-M-RET-may-split-line
 Insert new item at current level.  With a prefix argument, force a new
 heading (@pxref{Structure editing}).  If this command is used in the middle
@@ -1375,13 +1351,11 @@ bullet, a bullet is added to the current line.
 @kindex M-S-@key{RET}
 @item M-S-@key{RET}
 Insert a new item with a checkbox (@pxref{Checkboxes}).
-@kindex @key{TAB}
-@item @key{TAB} @r{in new, empty item}
+@orgcmd{@key{TAB}, org-cycle}
 In a new item with no text yet, the first @key{TAB} demotes the item to
 become a child of the previous one.  The next @key{TAB} makes it a parent,
 and so on, all the way to the left margin.  Yet another @key{TAB}, and you
 are back to the initial level.
-@kindex S-@key{up}
 @kindex S-@key{down}
 @item S-@key{up}
 @itemx S-@key{down}

[-- Attachment #3: 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

  reply	other threads:[~2010-08-17 12:44 UTC|newest]

Thread overview: 44+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2010-07-28 19:36 keys and command name info Andreas Röhler
2010-07-29  6:45 ` Tassilo Horn
2010-07-29 13:47   ` Andreas Röhler
2010-07-29 15:19     ` Andreas Röhler
2010-07-29 18:08       ` Tassilo Horn
2010-07-30  9:40         ` Andreas Röhler
2010-08-07 19:39           ` Carsten Dominik
2010-08-08 13:57             ` Andreas Röhler
2010-07-31  8:53     ` Bastien
2010-07-31 17:53       ` Andreas Röhler
2010-07-31 19:02         ` Thomas S. Dye
2010-08-01  9:42         ` Bastien
2010-08-01 16:40           ` Andreas Röhler
2010-08-02  6:32 ` Carsten Dominik
2010-08-08 22:26   ` Gregor Zattler
2010-08-09  6:43     ` Carsten Dominik
2010-08-09  9:37       ` Andreas Burtzlaff
2010-08-09 10:19         ` Gregor Zattler
2010-08-09 10:31           ` Carsten Dominik
2010-08-09 18:32           ` Dan Davison
2010-08-09 19:28             ` Dan Davison
2010-08-11 10:05               ` Carsten Dominik
2010-08-11 10:23                 ` Andreas Röhler
2010-08-11 10:27                   ` Carsten Dominik
2010-08-13 13:45                 ` Andreas Röhler
2010-08-13 14:20                   ` Dan Davison
2010-08-13 19:30                 ` Andreas Röhler
2010-08-15  7:37                   ` Carsten Dominik
2010-08-15  7:39                     ` Carsten Dominik
2010-08-15 19:07                       ` Andreas Röhler
2010-08-16  8:57                         ` Carsten Dominik
2010-08-17 12:43                           ` Andreas Röhler [this message]
2010-08-18  8:38                             ` Carsten Dominik
2010-08-20  6:27                               ` Andreas Röhler
2010-08-20  7:31                                 ` Carsten Dominik
2010-08-20  8:13                                   ` Andreas Röhler
2010-08-20  7:44                                 ` Carsten Dominik
2010-08-17 15:44                           ` Andreas Röhler
2010-08-10  1:28             ` Memnon Anon
2010-08-09 14:23       ` Nick Dokos
2010-08-10  7:48       ` OT: smex.el (was Re: keys and command name info) Austin Frank
2010-08-20 11:20 ` keys and command name info Carsten Dominik
2010-08-20 11:32   ` Stefan Vollmar
2010-08-20 13:23   ` Bernt Hansen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=4C6A83E2.9020304@easy-emacs.de \
    --to=andreas.roehler@easy-emacs.de \
    --cc=dominik@uva.nl \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).