[O] bug#28263: bug#28263: 24.5; Org: `C-c LETTER' keys
Drew Adamswrites: > 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.
[O] bug#28263: bug#28263: 24.5; Org: `C-c LETTER' keys
> 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.
[O] bug#28263: bug#28263: 24.5; Org: `C-c LETTER' keys
Hello, Drew Adamswrites: > 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 Goaziou0x80A93738
[O] bug#28263: bug#28263: 24.5; Org: `C-c LETTER' keys
> Drew Adamswrites: > > > 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".
[O] bug#28263: bug#28263: 24.5; Org: `C-c LETTER' keys
> 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.
[O] bug#28263: bug#28263: 24.5; Org: `C-c LETTER' keys
On Tue, Dec 5, 2017 at 7:15 AM, Drew Adamswrote: > > That's even worse, IMHO. And hardly "as neutral as possible". > > > > 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?