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

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.

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 ?"]


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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

[Nicolas Goaziou]

Hello,

Drew Adams <drew.adams@oracle.com> 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 Goaziou                                                0x80A93738

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.

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

[Nicolas Goaziou]

Hello,

Drew Adams <drew.adams@oracle.com> 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 Goaziou                                                0x80A93738

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 <F10>.
(But using <F10> or C-c a is no better than using
PK or whatever - you still need to say something like
"Supposing that <F10> 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.

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

[Allen Li]

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

[Allen Li]

On Tue, Dec 5, 2017 at 7:15 AM, Drew Adams <drew.adams@oracle.com> wrote:
>
> That's even worse, IMHO.  And hardly "as neutral as possible".
>
> <snip 100 lines>
>
> Just one opinion.

Could you summarize how you think the situation could be improved in
one or two sentences?

I think what you are trying to say is, Org mode should make global
key bindings for some commands.

However, this is problematic because there are pretty much no global
keys available that are not reserved for major modes, minor modes, or
the user, and at any rate I don’t think we could justify binding
global keys by default since Org mode is a pretty small application
within Emacs.  calendar.el does not have a global key.  remember.el
does not have a global key.  et cetera.  Org mode is no different.

If we make an Org minor mode, that’s really no better than the user
just binding his own keys vs turning on the minor mode.  Also, the
reserved minor mode keys are not very good (hard to press), and they
can conflict with other minor modes, which is probably undesirable for
Org users.

Is your complaint simply that we suggest a key for the user to bind?

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

[Drew Adams]

> Could you summarize how you think the situation could be improved in
> one or two sentences?
> 
> I think what you are trying to say is, Org mode should make global
> key bindings for some commands.

No.  I'm saying that Org should not suggest that users bind
keys that are reserved for use by users to Org commands.

And it should not then present those keys in the doc.

And it should not say anything about the doc using those
keys for illustrative purposes or assuming that users
have bound those keys.

Org should do _nothing_ with such reserved keys.  It
should not mention them at all in its doc.

If Org wants to recommend or suggest that users bind some
particular commands to keys, including to prefix keys, it
can do that.  But don't mention any particular keys
(preferably), and certainly do not suggest using any
particular keys.

*IF* Org feels that certain commands should definitely be
bound globally *THEN* (1) it should present that as a
concrete proposal to emacs-devel for consideration and
(2) if agreed on, Org should just bind those keys globally.

That's Org's decision.  I'm not in any way suggesting
that Org should bind global keys.  In fact, I hope it
does not do so.  But I can't decide what's best for
everyone here.  Maybe some global keys should be
sacrificed for Org.  I doubt it, but maybe Emacs Dev
would decide that that's appropriate.

What Org does now is, IMO, a shame-faced way of getting
a bunch of keys bound globally for its purposes, without
actually binding them.  And what's more, the keys in
question are keys that are always reserved for users.
That's not right.

> However, this is problematic because there are pretty much no global
> keys available that are not reserved for major modes, minor modes, or
> the user,

Tough.  We're all in that boat.  (And anyway, it's not true
in such absolute terms.)  That's the whole point of
reserving keys - to prevent things like Org from gobbling
them all up.

And nothing prevents Org from defining a minor mode that
it intends all Org users to use all the time - in effect
providing a whole new space for its "global" key bindings.

(Not `org-mode', of course, if you want the keys available
even when Org mode is turned off.)

> and at any rate I don’t think we could justify binding
> global keys by default since Org mode is a pretty small application
> within Emacs.  calendar.el does not have a global key.  remember.el
> does not have a global key.  et cetera.  Org mode is no different.

Exactly.  Please follow their example: Don't suggest to
users to bind keys reserved to them to Org commands.

> If we make an Org minor mode, that’s really no better than the user
> just binding his own keys vs turning on the minor mode.

Defining such a minor mode is exactly the way to go, to
get pretty much global behavior without locking in keys
to the absolutely global `global-map'.

Turning on a minor mode that binds keys in its keymap
_is_ a bit like binding your own keys globally.  The
difference is that they are not bound globally.  In
both cases the user makes the choice.  But in one
case the user does not (and ALL users do not) sacrifice
the global keys reserved for users.

Turn the mode on to get its bindings.  Turn it off
to be rid of its bindings.  That's the clean Emacs
way to handle such things. Sneakily recommending to
users that they bind keys reserved for users to Org
commands is not right.  It's not fair to users, most
of all.  And it's not fair to other modes and the
rest of Emacs.  You might say it's "orgocentric".


> Also, the
> reserved minor mode keys are not very good (hard to press), and they
> can conflict with other minor modes, which is probably undesirable for
> Org users.

Tough.  We all live with it.  Emacs is not only for Org.

And in any case, you can put any number of keys on a
prefix key.  And there are plenty of prefix keys that
are not reserved for users.

> Is your complaint simply that we suggest a key for the user to bind?

See above.  If you take the approach of suggesting a key
to bind, it should not be a key that is reserved for users.

This really shouldn't be hard to understand.  Please see
how other packages/modes deal with it.

Yes, key sequences are a limited resource.  For _all_ of us.
For all of Emacs and for all users.  If Org is just starting
to realize this and play fair then it's about time.

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

[Allen Li]

On Wed, Dec 6, 2017 at 7:23 AM, Drew Adams <drew.adams@oracle.com> wrote:
> [paraphrased] Org should not suggest user reserved key bindings

I agree with you in general.  However, when I first started using
Emacs for Org mode years ago, I found the documentation very helpful.
Furthermore, I did not find the documentation misleading about the
fact that these keys are not standard.

For users that are not accustomed to Emacs, the ability to bind keys
freely is paralyzing.  I had no idea what keys would be okay or not
okay to bind.

This could be solved by instead linking to the Emacs key binding
guidelines and pointing out ranges of keys or example keys that would
be safe to bind. I interpret the current documentation as suggesting
such example keys.

For comparison, calendar.el et al do not suggest global key bindings
for their commands.  However, Org mode is different because it is one
of Emacs’s "killer apps".  It is something that a non-Emacs user would
start using Emacs for.  No one is going to switch to Emacs to use
calendar.el, but there are many people that switch to Emacs to use Org
mode.  Therefore, there is a benefit in adding some tips for very new
users.

As a matter of practicality, I suspect many users are just blindly
copying Emacs Lisp code from various guides online, so there is no
good way to fight de facto standards from emerging.  Projectile is a
particularly blatant offender, a popular package that reserves the C-c
p key for its minor mode.

However, the Emacs documentation is quite clear about key binding
rules.  All built in libraries follow it, including Org mode.  I do
not interpret the Org documentation as implying otherwise.

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

[Drew Adams]

> Drew Adams <drew.adams@oracle.com> writes:
> 
> > No.  I'm saying that Org should not suggest that
> > users bind keys that are reserved for use by users
> > to Org commands.
> >
> > And it should not then present those keys in the doc.
> >
> > And it should not say anything about the doc using
> > those keys for illustrative purposes or assuming
> > that users have bound those keys.
> >
> > Org should do _nothing_ with such reserved keys.
> > It should not mention them at all in its doc.
> 
> This is your own interpretation of the two paragraphs in
> the Elisp manual that treat about reserved keys, IMO.

It's my opinion of what Org mode _should_ do.

And it coincides with what other libraries do.  And it
fits what the manual suggests.

Your opinion is apparently that Emacs (in the Org-mode
doc) should recommend that users sacrifice those keys
to Org.  We disagree about that.

You want Emacs to (1) tell users that these keys are
reserved for them to bind, BUT also to (2) recommend
that if they use Org mode (which most users probably
do now) then they should bind them to Org commands.
I don't want Emacs to do #2.  #1 is good; #2 is bad,
and it, in effect, undercuts #1.

In my opinion no library should suggest that users
sacrifice their reserved keys for that library.
Users are free to do that, of course.  But it's
impolite, IMO, for a library to recommend that they
do so.

Users aren't stupid - they can figure out, if they
end up using some commands often, that they might
want to bind them to keys, including perhaps to
their reserved keys.  They don't need a library to
pitch them that idea.  And newbie users might well
get the wrong idea that they really need to follow
that suggestion or they could have a "bad experience".

Libraries that are purely 3rd-party can of course
do anything they like (not that they should, but
they can).

But I'd offer the same opinion for purely 3rd-party
libraries: Don't recommend that users globally bind
their reserved keys for your mode.

Org mode is not only a 3rd-party library.  It is
now part of GNU Emacs.  All the more reason to be
nice to users.

> Anyway, for the record, I modified Org manual (for Org 9.2) so it
> doesn't assume anymore users followed advice and bound `C-c a', `C-c
> l'... In fact, I removed every reference to user reserved keybindings,

Very good.  Thank you for doing the right thing there.

> but one, in the following paragraphs:
>
>   For a better experience, the three Org commands ~org-store-link~,
>   ~org-capture~ and ~org-agenda~ ought to be accessible anywhere in
>   Emacs, not just in Org buffers.  To that effect, you need to bind
>   them
>   to globally available keys, like the ones reserved for users (see
>   [[info:elisp::Key%20Binding%20Conventions]]).  Here are suggested
>   bindings, please modify the keys to your own liking.
> 
>   #+begin_src emacs-lisp
>     (global-set-key "\C-cl" 'org-store-link)
>     (global-set-key "\C-ca" 'org-agenda)
>     (global-set-key "\C-cc" 'org-capture)
>   #+end_src

Not good, IMHO.

And there is _no need_ to mention those keys.
It should be fine and enough to leave off the part
about ", like the ones reserved ... #+end_src."

That part's not needed for users to understand
that if they want global behavior then they can
bind global keys - which is the only message you
need to get across about those commands.

And, once again, those words shamefacedly suggest
that users use those keys.  Same problem.

Again:

> > Org should not suggest that users bind keys that
> > are reserved for use by users to Org commands.

Org is widely used.  Recommending that users use
those keys for Org is nearly tantamount to no
longer reserving them for users.  Not quite as bad
as actually binding them to Org commands on their
behalf (which would clearly contravene the guideline),
but almost as bad.

And totally unnecessary.

> I dare to think this is a good enough advice to belong to the manual,
> with enough safeguards to let users know what it entails. I also think
> it is fair, because the manual doesn't talk about these bindings anymore
> later on.

I'm on record, at least, as disagreeing with that.
One opinion.

Anyway, thank you for no longer having the rest of
the Org manual depend on the assumption that users
have sacrificed those keys to Org.

Perhaps someday someone else will finish the job by
removing the manual's suggestion that they should
make that sacrifice, "for a better experience".

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

[Nicolas Goaziou]

Hello,

Drew Adams <drew.adams@oracle.com> writes:

> It's my opinion of what Org mode _should_ do.

That's what I meant.

> And it coincides with what other libraries do.

This doesn't prove the model is right.

> And it fits what the manual suggests.

Unfortunately, the manual suggests nothing. I think that's the main
issue here.

> Your opinion is apparently that Emacs (in the Org-mode
> doc) should recommend that users sacrifice those keys
> to Org.  We disagree about that.

Not at all.

I want _Emacs_ (not the Elisp manual) to tell users about so-called user
reserved keys and what are their benefits. Since this isn't the case,
Org manual takes care of this.

> You want Emacs to (1) tell users that these keys are
> reserved for them to bind, BUT also to (2) recommend
> that if they use Org mode (which most users probably
> do now) then they should bind them to Org commands.

Not at all.

We recommend to bind globally available keys, but only give an example
on what the binding should look like. We even invite users to modify
them to their own liking.

> Org mode is not only a 3rd-party library.  It is
> now part of GNU Emacs.  All the more reason to be
> nice to users.

Note that we are really disagreeing about the definition of being nice
to the users. I'm convinced we both want to be nice to them.

> It should be fine and enough to leave off the part
> about ", like the ones reserved ... #+end_src."
>
> That part's not needed for users to understand
> that if they want global behavior then they can
> bind global keys - which is the only message you
> need to get across about those commands.

I searched the Emacs manual about "global keys" (menu, concept index,
regexp). I miserably failed. As a user, what can I do now?

> Perhaps someday someone else will finish the job by
> removing the manual's suggestion that they should
> make that sacrifice, "for a better experience".

I will happily remove the part you consider to be offending -- whereas
I consider it to be helpful -- once we can point users towards
appropriate information within the Emacs manual. Would you like to
report a bug about it?


Regards,

-- 
Nicolas Goaziou                                                0x80A93738

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

[Drew Adams]

> I will happily remove the part you consider to be offending

Great.

> once we can point users towards appropriate information
> within the Emacs manual. Would you like to report a bug
> about it?

OK.  I filed bug #30530.  Please feel free to chime in
there, if your idea of what needs to be done differs
from what I requested.

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

[Nicolas Goaziou]

Drew Adams <drew.adams@oracle.com> writes:

> OK.  I filed bug #30530.  Please feel free to chime in
> there, if your idea of what needs to be done differs
> from what I requested.

I fully agree with your report. Thank you.