meta commands and Info manual

meta commands and Info manual

[Alan Wehmann]

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

I am a new user of Org.  I'm an experienced user of Emacs.  My first use of Org was to create a table.  I soon found myself wanting to insert a column.  I looked at Info node "(org) Built-in table editor" [This manual is for Org version 8.2.9.] and it said:

‘M-S-<right>     (org-table-insert-column)’
     Insert a new column to the left of the cursor position.

I now know that this was somewhat mis-leading, since that key combination is bound to "org-shiftmetaright", but at the time I was rather confused (see topic "Org keymap question" in "news group" gnu.emacs.help).  I'd recommend a revision to the Info manual, to describe more prominently command "org-shiftmetaright" and other "meta" commands like it (apologies in advance if there is a later version of the Info manual that addresses this).

Info node "(org) Conventions" does mention the use of the meta commands somewhat, but I certainly didn't see it right away.

I am using:

GNU Emacs 24.5.1 (x86_64-apple-darwin13.4.0, NS apple-appkit-1265.21) of 2015-04-10 on builder10-9.porkrind.org


[-- Attachment #2: Type: text/html, Size: 3678 bytes --]

Re: meta commands and Info manual

[Nicolas Goaziou]

Hello,

Alan Wehmann <alan.wehmann@gmail.com> writes:

> I am a new user of Org. I'm an experienced user of Emacs. My first use
> of Org was to create a table. I soon found myself wanting to insert
> a column. I looked at Info node "(org) Built-in table editor" [This
> manual is for Org version 8.2.9.] and it said:
>
> ‘M-S-<right>     (org-table-insert-column)’
>      Insert a new column to the left of the cursor position.
>
> I now know that this was somewhat mis-leading, since that key
> combination is bound to "org-shiftmetaright", but at the time I was
> rather confused (see topic "Org keymap question" in "news group"
> gnu.emacs.help). I'd recommend a revision to the Info manual, to
> describe more prominently command "org-shiftmetaright" and other
> "meta" commands like it (apologies in advance if there is a later
> version of the Info manual that addresses this).

I think meta commands are the ones confusing here. I mean, is

  M-S-<right>  (org-shiftmetaright)

informative?

Anyway, I'm not sure to understand what puzzled you in the first place.


Regards,

-- 
Nicolas Goaziou

Re: meta commands and Info manual

[Nick Dokos]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Alan Wehmann <alan.wehmann@gmail.com> writes:
>
>> I am a new user of Org. I'm an experienced user of Emacs. My first use
>> of Org was to create a table. I soon found myself wanting to insert
>> a column. I looked at Info node "(org) Built-in table editor" [This
>> manual is for Org version 8.2.9.] and it said:
>>
>> ‘M-S-<right>     (org-table-insert-column)’
>>      Insert a new column to the left of the cursor position.
>>
>> I now know that this was somewhat mis-leading, since that key
>> combination is bound to "org-shiftmetaright", but at the time I was
>> rather confused (see topic "Org keymap question" in "news group"
>> gnu.emacs.help). I'd recommend a revision to the Info manual, to
>> describe more prominently command "org-shiftmetaright" and other
>> "meta" commands like it (apologies in advance if there is a later
>> version of the Info manual that addresses this).
>
> I think meta commands are the ones confusing here. I mean, is
>
>   M-S-<right>  (org-shiftmetaright)
>
> informative?
>
> Anyway, I'm not sure to understand what puzzled you in the first place.
>

I think what's puzzling is that these are not "normal" emacs keybindings
(and therefore not discoverable using the "normal" emacs mechanisms):
there is an extra level of indirection that org mode imposes which you
just have to know about. But I'm not sure what the best way to document
them would be: maybe a section explaining the mechanism plus links (or
footnotes) to go from e.g. the description of M-S-<right> in the table
section to the mechanism section. Or maybe showing the indirection
explicitly:

‘M-S-<right>     (org-shiftmetaright) --> (org-table-insert-column)’

Nick

Re: meta commands and Info manual

[Suvayu Ali]

On Mon, Jul 20, 2015 at 06:08:56PM -0400, Nick Dokos wrote:

> Or maybe showing the indirection explicitly:
> 
> ‘M-S-<right>     (org-shiftmetaright) --> (org-table-insert-column)’

Particularly this suggestion would be very helpful, even for long time
Org users such as myself.

-- 
Suvayu

Open source is the future. It sets us free.

Re: meta commands and Info manual

[Nicolas Goaziou]

Hello,

Nick Dokos <ndokos@gmail.com> writes:

> I think what's puzzling is that these are not "normal" emacs keybindings
> (and therefore not discoverable using the "normal" emacs mechanisms):
> there is an extra level of indirection that org mode imposes which you
> just have to know about. But I'm not sure what the best way to document
> them would be: maybe a section explaining the mechanism plus links (or
> footnotes) to go from e.g. the description of M-S-<right> in the table
> section to the mechanism section. Or maybe showing the indirection
> explicitly:
>
> ‘M-S-<right>     (org-shiftmetaright) --> (org-table-insert-column)’

C-h k M-S-<right> should already show you the indirections.

Regards,

-- 
Nicolas Goaziou

Re: meta commands and Info manual

[Nick Dokos]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Nick Dokos <ndokos@gmail.com> writes:
>
>> I think what's puzzling is that these are not "normal" emacs keybindings
>> (and therefore not discoverable using the "normal" emacs mechanisms):
>> there is an extra level of indirection that org mode imposes which you
>> just have to know about. But I'm not sure what the best way to document
>> them would be: maybe a section explaining the mechanism plus links (or
>> footnotes) to go from e.g. the description of M-S-<right> in the table
>> section to the mechanism section. Or maybe showing the indirection
>> explicitly:
>>
>> ‘M-S-<right>     (org-shiftmetaright) --> (org-table-insert-column)’
>
> C-h k M-S-<right> should already show you the indirections.
>

Yes, it does - I should have tried it out before spouting off:
you very thoughtfully added the indirections to the doc string
of org-shiftmetaright.

Thanks for doing that and for pointing it out. If I ever knew
about it in the past, I certainly had forgotten it.

For my part I'm happy (and I suspect Suvayu is as well), so I
guess it's back to the OP: what, if anything, should be
changed?

-- 
Nick

Re: meta commands and Info manual

[Suvayu Ali]

On Tue, Jul 21, 2015 at 10:26:15PM -0400, Nick Dokos wrote:
> 
> For my part I'm happy (and I suspect Suvayu is as well), so I
> guess it's back to the OP: what, if anything, should be
> changed?

Indeed!  I happily shut up :).

As to the OP, the discussion towards the end of this section should
cover the subtlety for a new user, (info "(org) Conventions").

WDYT?

-- 
Suvayu

Open source is the future. It sets us free.