[O] bug#28263: 24.5; Org: `C-c LETTER' keys

[Drew Adams]

> >> Org's manual suggests to bind `org-agenda' to `C-c a', 
> >> but doesn't bind it by default.
> >
> > I'm not even sure that's a great idea.  I think not.
> >
> > I suppose it's "legit", as the user, not the Org code,
> > would be making the binding.  But in my libraries I 
> > provide binding suggestions only for keys that are not 
> > reserved for use by users.
> >
> > If a commonly used Emacs library (Org is the best example
> > of that) suggests to users that they bind `C-c a' to 
> > something then that key becomes pretty much, in effect,
> > lost as a key reserved for user customization.
> >
> > IOW, if 90% of Emacs users follow that suggestion then there 
> > is little difference between that situation and the situation 
> > of Org binding `C-c a' by default.
> >
> > My vote would be that Org should not do this.  Just one 
> > opinion.
> 
> I understand your concern. However, Org tries to be as neutral
> as possible with this. Quoting the manual:
> 
>  The manual suggests a few global key bindings, in particular 
>  @kbd{C-c a} for @code{org-agenda} and @kbd{C-c c} for 
>  @code{org-capture}.  These are only suggestions, but the rest 
>  of the manual assumes that these key bindings are in place in 
>  order to list commands by key access.

That's even worse, IMHO.  And hardly "as neutral as possible".

Why should the manual list commands by key access that Org
does _not_ bind to keys?  What's wrong with listing the
commands by name?  That's what Emacs does in its doc.

My suggestion would be to bind keys in Org keymaps only,
and leave it at that.

The manual should definitely not present key bindings that
are  not made by Org, tossing out an introductory comment
that they are shown only to "clarify bindings shown" or to
prevent having to show command names or whatever.

That approach is a bit backhanded, and it really flies
against the spirit of (really!) reserving C-c LETTER keys
for users.

> As explained here, this "suggestion" is only necessary
> to clarify key bindings in the manual.

Clarify key bindings in the manual?  Why are those key
bindings in the manual?  Describe the commands, not
(formally, supposedly) fictitious key bindings for them.

Either it is _important_ for Org to bind those commands
to keys or it's not.  If it is, then Org should find keys
that are not reserved for users.

As I said:

 > > provide binding suggestions only for keys that are
 > > not reserved for use by users

If it is not important for Org itself to bind such keys,
then no such "fictitious" global keys should be presented
in the manual.

> `org-agenda' and `org-capture' bindings are
> really prefixes for many other commands. Having to write, e.g.,
> "the prefix you chose for `org-agenda' then #" instead of
> "C-c a #" would be a lot more verbose, and ultimately, cripple 
> documentation.

My response to that: suck it up, or find a better way
to describe it.

You can perfectly well say "PK #", where PK is a
prefix key bound to `org-agenda'.  Or you can use,
for illustration purposes, a key such as .
(But using  or C-c a is no better than using
PK or whatever - you still need to say something like
"Supposing that  is a prefix key bound to
`org-agenda'...").

And why do you need to refer to a key at all, instead
of referring to the command?  As I say, if it is so
important that the command be bound to a key then
bind it - but to a key that is not reserved for users.

Don't ask users to bind their keys to provide something
that you think Org really needs.  If it needs keys for
this then bind keys for it.  If it does not then
hands-off, and just speak about the commands.  That's
what other Emacs doc does.

This is the wrong thing to do, IMO:

 The four Org commands 'org-store-link', 'org-capture',
 'org-agenda', and 'org-iswitchb' should be accessible 
 through global keys (i.e., anywhere in Emacs, not just
 in Org buffers).  Here are suggested bindings for these 
 keys, please modify the keys to your own liking.

 (global-set-key "\C-cl" 'org-store-link)
 (global-set-key "\C-ca" 'org-agenda)
 (global-set-key "\C-cc" 'org-capture)
 (global-set-key "\C-cb" 'org-iswitchb)

If those commands "should" be on global keys then
_Org should bind them to global keys_.  And those
global keys should _not_ be keys reserved for users.

This looks like a shame-faced way of getting around
the prohibition of libraries binding such keys
globally.  Especially for a library such as Org,
which is very widely used.

My suggestion would be to propose, to emacs-devel,
to bind 4 keys globally for those Org commands -
if you really feel they "should" be bound globally.
IOW, stick up for what you believe.  And if it is
decided to bind those commands you can be sure that
the keys decided on then will not be keys reserved
for users.

> I think the current state is quite fair.

I disagree.  It's a shame.  (FWIW.)  Emacs "should"
do better.

Just one opinion.

[O] bug#28263: 24.5; Org: `C-c LETTER' keys

[Nicolas Goaziou]

Hello,

Drew Adams  writes:

>> > Dunno whether there are actual bindings in Org that correspond to these
>> > occurrences in the source code of `C-c' followed by a letter.  Might be
>> > worth checking.  (Bindings of `C-c' followed by a letter are reserved
>> > for users.)  Possibly these are just vestigial doc indications, which
>> > could be corrected/updated.
>> 
>> Org's manual suggests to bind `org-agenda' to `C-c a', but doesn't bind
>> it by default.
>
> I'm not even sure that's a great idea.  I think not.
>
> I suppose it's "legit", as the user, not the Org code, would be
> making the binding.  But in my libraries I provide binding
> suggestions only for keys that are not reserved for use by users.
>
> If a commonly used Emacs library (Org is the best example of that)
> suggests to users that they bind `C-c a' to something then that
> key becomes pretty much, in effect, lost as a key reserved for
> user customization.
>
> IOW, if 90% of Emacs users follow that suggestion then there is
> little difference between that situation and the situation of
> Org binding `C-c a' by default.
>
> My vote would be that Org should not do this.  Just one opinion.

I understand your concern. However, Org tries to be as neutral as
possible with this. Quoting the manual:

The manual suggests a few global key bindings, in particular @kbd{C-c a} for
@code{org-agenda} and @kbd{C-c c} for @code{org-capture}.  These are only
suggestions, but the rest of the manual assumes that these key bindings are 
in
place in order to list commands by key access.

As explained here, this "suggestion" is only necessary to clarify key
bindings in the manual. `org-agenda' and `org-capture' bindings are
really prefixes for many other commands. Having to write, e.g., "the
prefix you chose for `org-agenda' then #" instead of "C-c a #" would be
a lot more verbose, and ultimately, cripple documentation.

I think the current state is quite fair.

Regards,

-- 
Nicolas Goaziou0x80A93738

[O] bug#28263: 24.5; Org: `C-c LETTER' keys

[Drew Adams]

> > Dunno whether there are actual bindings in Org that correspond to these
> > occurrences in the source code of `C-c' followed by a letter.  Might be
> > worth checking.  (Bindings of `C-c' followed by a letter are reserved
> > for users.)  Possibly these are just vestigial doc indications, which
> > could be corrected/updated.
> 
> Org's manual suggests to bind `org-agenda' to `C-c a', but doesn't bind
> it by default.

I'm not even sure that's a great idea.  I think not.

I suppose it's "legit", as the user, not the Org code, would be
making the binding.  But in my libraries I provide binding
suggestions only for keys that are not reserved for use by users.

If a commonly used Emacs library (Org is the best example of that)
suggests to users that they bind `C-c a' to something then that
key becomes pretty much, in effect, lost as a key reserved for
user customization.

IOW, if 90% of Emacs users follow that suggestion then there is
little difference between that situation and the situation of
Org binding `C-c a' by default.

My vote would be that Org should not do this.  Just one opinion.

> Fixed (I used \\[org-agenda] instead of C-c a). Thank you.

Thanks for doing that.

[O] bug#28263: 24.5; Org: `C-c LETTER' keys

[Nicolas Goaziou]

Hello,

Drew Adams  writes:

> Dunno whether there are actual bindings in Org that correspond to these
> occurrences in the source code of `C-c' followed by a letter.  Might be
> worth checking.  (Bindings of `C-c' followed by a letter are reserved
> for users.)  Possibly these are just vestigial doc indications, which
> could be corrected/updated.

Org's manual suggests to bind `org-agenda' to `C-c a', but doesn't bind
it by default.

> In org-agenda.el:
>
>   ["Find FLAGGED Tasks" (org-agenda nil "?") :active t :keys "C-c a ?"]
>
>   (defun org-agenda-kill-all-agenda-buffers ()
> "Kill all buffers in `org-agenda-mode'.
>   This is used when toggling sticky agendas.
>   You can also explicitly invoke it with `C-c a C-k'."...
>
> In org.el:
>
>   commands `org-search-view' (`C-c a s') and `org-occur-in-agenda-files'.
>   ["Global TODO list" org-todo-list :active t :keys "C-c a t"]
>   ["Find FLAGGED Tasks" (org-agenda nil "?") :active t :keys "C-c
>   a ?"]

Fixed (I used \\[org-agenda] instead of C-c a). Thank you.

Regards,

-- 
Nicolas Goaziou0x80A93738