Clarifying the C-c letter guideline

Clarifying the C-c letter guideline

[Philip Kaludercic]

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


Hi,

a few days ago, there was a discussion on help-gnu-emacs[0],
specifically on this one paragraph from (elisp) Key Binding Conventions:

> • Don’t define ‘C-c LETTER’ as a key in Lisp programs.  Sequences
>   consisting of ‘C-c’ and a letter (either upper or lower case) are
>   reserved for users; they are the *only* sequences reserved for
>   users, so do not block them.

There seems to be some uncertainty in how this should be
interpreted. Does this mean that...

- No package/library/third-party code may ever bind a command or map to
  C-c LETTER, under any circumstances (in the letter of the law).

- A package/library/third-party code may bind a command or a map to C-c
  LETTER, if the user is explicitly asked and he or she gives
  permission (in the spirit of the law).

I lean towards the second interpretation, which would allow something
like

    (defcustom foobar-bind-to nil
      "Bind command `foobar' to C-c LETTER."
      :set (lambda (sym val)
	     (cond (val (global-set-key (format "%c" val) #'foobar))
		   ((where-is-internal #'foobar)
		    (global-set-key (car (where-is-internal #'foobar)) nil)))
	     (set-default sym val))
      :type '(choice (const :tag "Don't bind" nil)
		     (character :tag "Bind to")))

(even though I don't think code like this is necessary in the first
place, but this is just an example).

The background of this discussion is to settle the question, whether/how
packages might suggest binding a global command, if their interface is
not a major or minor mode, but a specific command
(e.g. magit-status). Using defcustom is probably not the best idea, but
something I think that something along these lines might be interesting
to have.

So I'd be interested in what the mailing list has to say on this
question. Should this section be rephrased to clarify the guideline?

[0] https://lists.gnu.org/archive/html/help-gnu-emacs/2021-02/msg00426.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: Clarifying the C-c letter guideline

[Jean Louis]

* Philip Kaludercic <philipk@posteo.net> [2021-02-14 15:14]:
> 
> Hi,
> 
> a few days ago, there was a discussion on help-gnu-emacs[0],
> specifically on this one paragraph from (elisp) Key Binding Conventions:
> 
> > • Don’t define ‘C-c LETTER’ as a key in Lisp programs.  Sequences
> >   consisting of ‘C-c’ and a letter (either upper or lower case) are
> >   reserved for users; they are the *only* sequences reserved for
> >   users, so do not block them.
> 
> There seems to be some uncertainty in how this should be
> interpreted. Does this mean that...
> 
> - No package/library/third-party code may ever bind a command or map to
>   C-c LETTER, under any circumstances (in the letter of the law).

Convention is not a law, rather normative example. There are third
party packages that are not public, or not free software, you may bind
such as you wish and do what you wish at your home or office, it is
free software, you can bind keys as you really wish and want.

As a normative example C-c LETTER keys shall be reserved for users, so
third party packages should not bind globally and automatically those.

> - A package/library/third-party code may bind a command or a map to C-c
>   LETTER, if the user is explicitly asked and he or she gives
>   permission (in the spirit of the law).

It is understandable that you can make programs to do whatever you
wish and program may ask user to decide on which key to bind some
function. It is not breaking any law. I just don't believe that
package that globally sets key on C-c LETTER would be accepted in
GNU ELPA or Non-GNU ELPA repository.

But I do not think that MELPA or other repository would object to it.

Short recursive grep in 2500 *.el packages from MELPA tells me that
there is almost no package binding anything on C-c LETTER.

They will rather suggest it to be bound by user or one will provide a
single function to bind all keys like it is in lorem-ipsum package
./lorem-ipsum-20190819.2042.el\076:

In that sense, many packages decide to sugest to user to use C-c
LETTER for commands or prefix keys.

There is nothing wrong in suggesting it to user through interactive
function, artificial intelligence, to bind the key on some of
suggested keys or letters as that will then be decided by user and not
by programmer.

Function can also ask user to invoke manually the preferred key and to
bind it to such desired chosen key without suggesting to user series
or list of keys.

Jean


79 matches for ""C-c" in buffer: *grep*
      5:./dpaste-20160303.2113.el\054:;;     (global-set-key (kbd "C-c p") 'dpaste-region-or-buffer)
     40:./simple-call-tree-20180224.2056.el\0318:;; (global-set-key (kbd "C-c S") 'simple-call-tree-display-buffer)
     53:./project-root-20160408.1600.el\056:;; (global-set-key (kbd "C-c p f") 'project-root-find-file)
     54:./project-root-20160408.1600.el\057:;; (global-set-key (kbd "C-c p g") 'project-root-grep)
     55:./project-root-20160408.1600.el\058:;; (global-set-key (kbd "C-c p a") 'project-root-ack)
     56:./project-root-20160408.1600.el\059:;; (global-set-key (kbd "C-c p d") 'project-root-goto-root)
     57:./project-root-20160408.1600.el\060:;; (global-set-key (kbd "C-c p p") 'project-root-run-default-command)
     58:./project-root-20160408.1600.el\061:;; (global-set-key (kbd "C-c p l") 'project-root-browse-seen-projects)
     59:./project-root-20160408.1600.el\063:;; (global-set-key (kbd "C-c p M-x")
     86:./scratch-ext-20140104.516.el\056:;;     (global-set-key (kbd "C-c i") 'scratch-ext-insert-newest-log)
     87:./scratch-ext-20140104.516.el\057:;;     (global-set-key (kbd "C-c r") 'scratch-ext-restore-last-scratch)
     91:./eyuml-20170413.2141.el\032:;; (global-set-key (kbd "C-c a") 'eyuml-create-activity-diagram)
     92:./eyuml-20170413.2141.el\033:;; (global-set-key (kbd "C-c c") 'eyuml-create-class-diagram)
     93:./eyuml-20170413.2141.el\034:;; (global-set-key (kbd "C-c u") 'eyuml-create-usecase-diagram)
    108:./helm-spaces-20161001.1409.el\034:;; (global-set-key (kbd "C-c s") 'helm-spaces)
    125:./jump-to-line-20130122.1653.el\049:;; (global-set-key (kbd "C-c C-j") 'jump-to-line) ; Jump
    126:./jump-to-line-20130122.1653.el\050:;; (global-set-key (kbd "C-c b")   'jtl-back)     ; Back
    135:./region-convert-20190104.1108.el\040:;;;      (global-set-key (kbd "C-c r") 'region-convert)
    137:./org-mru-clock-20201019.824.el\047:;;; (global-set-key (kbd "C-c C-x i") #'org-mru-clock-in)
    138:./org-mru-clock-20201019.824.el\048:;;; (global-set-key (kbd "C-c C-x C-j") #'org-mru-clock-select-recent-task)
    139:./sqlup-mode-20190814.46.el\051:;; (global-set-key (kbd "C-c u") 'sqlup-capitalize-keywords-in-region)
    156:./ietf-docs-20190420.851.el\037:;; (global-set-key (kbd "C-c i o") 'ietf-docs-open-at-point)
    171:./helm-c-moccur-20151230.924.el\0492:;; e.x, (global-set-key (kbd "C-c f") (helm-c-moccur-define-occur-command "defun "))
    197:./hide-lines-20151127.1840.el\046:;; (global-set-key (kbd "C-c /") 'hide-lines)
    209:./org-gtd-20200825.1410.el\074:;;   (global-set-key (kbd "C-c d c") 'org-gtd-capture) ;; add item to inbox
    210:./org-gtd-20200825.1410.el\075:;;   (global-set-key (kbd "C-c d p") 'org-gtd-process-inbox) ;; process entire inbox
    211:./org-gtd-20200825.1410.el\076:;;   (global-set-key (kbd "C-c d a") 'org-agenda-list) ;; see what's on your plate today
    212:./org-gtd-20200825.1410.el\077:;;   (global-set-key (kbd "C-c d n") 'org-gtd-show-all-next) ;; see all NEXT items
    213:./org-gtd-20200825.1410.el\078:;;   (global-set-key (kbd "C-c d s") 'org-gtd-show-stuck-projects) ;; see projects that don't have a NEXT item
    221:./decide-20190201.2137.el\0127:;; (global-set-key (kbd "C-c r") 'decide-roll-dice)
    223:./panda-20200917.520.el\028:;;        (global-set-key (kbd "C-c b") 'panda-map) ;; b for "Bamboo"
    225:./number-20170901.1312.el\045:;; (global-set-key (kbd "C-c C-+") 'number/add)
    226:./number-20170901.1312.el\046:;; (global-set-key (kbd "C-c C--") 'number/sub)
    227:./number-20170901.1312.el\047:;; (global-set-key (kbd "C-c C-*") 'number/multiply)
    228:./number-20170901.1312.el\048:;; (global-set-key (kbd "C-c C-/") 'number/divide)
    229:./number-20170901.1312.el\049:;; (global-set-key (kbd "C-c C-0") 'number/pad)
    230:./number-20170901.1312.el\050:;; (global-set-key (kbd "C-c C-=") 'number/eval)
    244:./string-inflection-20200927.747.el\066:;;   (global-set-key (kbd "C-c C-u") 'string-inflection-all-cycle)
    247:./right-click-context-20190528.1832.el\0182:    (global-set-key (kbd \"C-c :\") #'right-click-context-menu)
    250:./helm-grepint-20200811.1616.el\053:;;         (global-set-key (kbd "C-c g") #'helm-grepint-grep)
    251:./helm-grepint-20200811.1616.el\054:;;         (global-set-key (kbd "C-c G") #'helm-grepint-grep-root)
    255:./auto-shell-command-20180817.1502.el\051:;; (global-set-key (kbd "C-c C-m") 'ascmd:toggle) ; Temporarily on/off auto-shell-command run
    256:./auto-shell-command-20180817.1502.el\052:;; (global-set-key (kbd "C-c C-,") 'ascmd:popup)  ; Pop up '*Auto Shell Command*'
    257:./auto-shell-command-20180817.1502.el\053:;; (global-set-key (kbd "C-c C-.") 'ascmd:exec)   ; Exec-command specify file name
    277:./helm-bm-20160321.1331.el\033:;; (global-set-key (kbd "C-c b") 'helm-bm)
    280:./helm-swoop-20200814.448.el\049:;; (global-set-key (kbd "C-c M-i") 'helm-multi-swoop)
    294:./heaven-and-hell-20190713.1830.el\040:;; (global-set-key (kbd "C-c <f6>") 'heaven-and-hell-load-default-theme)
    309:./helm-git-grep-20170614.1411.el\034:;; (global-set-key (kbd "C-c g") 'helm-git-grep)
    311:./test-kitchen-20171129.2035.el\044:;;   (global-set-key (kbd "C-c C-d") 'test-kitchen-destroy)
    312:./test-kitchen-20171129.2035.el\045:;;   (global-set-key (kbd "C-c C-t") 'test-kitchen-test)
    313:./test-kitchen-20171129.2035.el\046:;;   (global-set-key (kbd "C-c l") 'test-kitchen-list)
    314:./test-kitchen-20171129.2035.el\047:;;   (global-set-key (kbd "C-c C-kv") 'test-kitchen-verify)
    315:./test-kitchen-20171129.2035.el\048:;;   (global-set-key (kbd "C-c C-kc") 'test-kitchen-converge)
    316:./quick-shell-keybind-20171023.613.el\033:;;     (global-set-key (kbd "C-c C-t") #'quick-shell-keybind)
    360:./org-board-20200619.1016.el\0324:;;  (global-set-key (kbd "C-c o") org-board-keymap)
    364:./browse-kill-ring-20200210.921.el\043:;; (global-set-key (kbd "C-c k") 'browse-kill-ring)
    381:./lorem-ipsum-20190819.2042.el\058:;; (global-set-key (kbd "C-c C-l s") 'lorem-ipsum-insert-sentences)
    382:./lorem-ipsum-20190819.2042.el\059:;; (global-set-key (kbd "C-c C-l p") 'lorem-ipsum-insert-paragraphs)
    383:./lorem-ipsum-20190819.2042.el\060:;; (global-set-key (kbd "C-c C-l l") 'lorem-ipsum-insert-list)
    384:./lorem-ipsum-20190819.2042.el\076:  (global-set-key (kbd "C-c l s") 'lorem-ipsum-insert-sentences)
    385:./lorem-ipsum-20190819.2042.el\077:  (global-set-key (kbd "C-c l p") 'lorem-ipsum-insert-paragraphs)
    386:./lorem-ipsum-20190819.2042.el\078:  (global-set-key (kbd "C-c l l") 'lorem-ipsum-insert-list))
    387:./firefox-controller-20160529.55.el\0136:;;   | (global-set-key (kbd "C-c m L")
    388:./firefox-controller-20160529.55.el\0196:;;   | (global-set-key (kbd "C-c m g")
    389:./org-journal-20201019.1813.el\0421:(global-set-key (kbd "C-c C-j") 'org-journal-new-entry)
    426:./org-working-set-20200914.456.el\01030:     "- As above, but edit your .emacs and insert a setq-clause: (setq org-working-set-id \"XXX\"), where XXX is the id of your node. You might want to add a keybinding too, e.g. (global-set-key (kbd  \"C-c w\") 'org-working-set)"
    435:./iy-go-to-char-20150927.226.el\052:;;     (global-set-key (kbd "C-c f") 'iy-go-to-char)
    436:./iy-go-to-char-20150927.226.el\053:;;     (global-set-key (kbd "C-c F") 'iy-go-to-char-backward)
    437:./iy-go-to-char-20150927.226.el\054:;;     (global-set-key (kbd "C-c ;") 'iy-go-to-or-up-to-continue)
    438:./iy-go-to-char-20150927.226.el\055:;;     (global-set-key (kbd "C-c ,") 'iy-go-to-or-up-to-continue-backward)
    439:./iy-go-to-char-20150927.226.el\059:;;     (global-set-key (kbd "C-c f") 'iy-go-up-to-char)
    440:./iy-go-to-char-20150927.226.el\060:;;     (global-set-key (kbd "C-c F") 'iy-go-up-to-char-backward)
    443:./cbm-20171116.1240.el\039:;; (global-set-key (kbd "C-c o") #'cbm-find-org-agenda-file)
    445:./quick-preview-20191017.1920.el\036:;; (global-set-key (kbd "C-c q") 'quick-preview-at-point)
    446:./sudo-edit-20200625.142.el\040:;;     (global-set-key (kbd "C-c C-r") 'sudo-edit)
    451:./helm-backup-20180911.614.el\036:;; (global-set-key (kbd "C-c b") 'helm-backup)
    455:./sharper-20201014.335.el\026:;;       (global-set-key (kbd "C-c n") 'sharper-main-transient) ;; For "n" for "dot NET"
    459:./todotxt-20200530.2337.el\050:;;  - Bind 'todotxt' to some accelerator like C-c t: (global-set-key (kbd "C-c t") 'todotxt)
    465:./helm-sheet-20130630.1239.el\031:;; (global-set-key (kbd "C-c s") 'helm-sheet)

Re: Clarifying the C-c letter guideline

[Philip Kaludercic]

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

Jean Louis <bugs@gnu.support> writes:

> * Philip Kaludercic <philipk@posteo.net> [2021-02-14 15:14]:
>> 
>> Hi,
>> 
>> a few days ago, there was a discussion on help-gnu-emacs[0],
>> specifically on this one paragraph from (elisp) Key Binding Conventions:
>> 
>> > • Don’t define ‘C-c LETTER’ as a key in Lisp programs.  Sequences
>> >   consisting of ‘C-c’ and a letter (either upper or lower case) are
>> >   reserved for users; they are the *only* sequences reserved for
>> >   users, so do not block them.
>> 
>> There seems to be some uncertainty in how this should be
>> interpreted. Does this mean that...
>> 
>> - No package/library/third-party code may ever bind a command or map to
>>   C-c LETTER, under any circumstances (in the letter of the law).
>
> Convention is not a law, rather normative example. There are third
> party packages that are not public, or not free software, you may bind
> such as you wish and do what you wish at your home or office, it is
> free software, you can bind keys as you really wish and want.

Well, of course. The only reason I'm using the word "Law" is in
reference to the dichotomy of the "spirit" and the "letter" of some law,
or for our sake guideline. I might just as well have said a "literal
interpretation" or a "interpretation assuming indent".

-- 
	Philip K.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: Clarifying the C-c letter guideline

[Matt Armstrong]

Philip Kaludercic <philipk@posteo.net> writes:

> Hi,
>
> a few days ago, there was a discussion on help-gnu-emacs[0],
> specifically on this one paragraph from (elisp) Key Binding Conventions:
>
>> • Don’t define ‘C-c LETTER’ as a key in Lisp programs.  Sequences
>>   consisting of ‘C-c’ and a letter (either upper or lower case) are
>>   reserved for users; they are the *only* sequences reserved for
>>   users, so do not block them.
>
> There seems to be some uncertainty in how this should be
> interpreted. Does this mean that...
>
> - No package/library/third-party code may ever bind a command or map to
>   C-c LETTER, under any circumstances (in the letter of the law).
>
> - A package/library/third-party code may bind a command or a map to C-c
>   LETTER, if the user is explicitly asked and he or she gives
>   permission (in the spirit of the law).

Hey Philip, I think your first rule is too strict to be unusuable, so
the second interpretation is the reasonable one.

Think of this example from use-package:
https://jwiegley.github.io/use-package/keywords/#bind-keymap-bind-keymap,
which even uses an example C-c LETTER binding in its
documentation. Under your first rule that would be illegal --
use-package would be a "List program" that is binding C-c LETTER
bindings.

Now, you may say that argument is silly because the user has told
use-package to make that binding. That is fine, but at that point you
are arguing for the second interpretation, not the first.

Re: Clarifying the C-c letter guideline

[chad]

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

On Sun, Feb 14, 2021 at 4:14 AM Philip Kaludercic <philipk@posteo.net>
wrote:

> > • Don’t define ‘C-c LETTER’ as a key in Lisp programs.  Sequences
> >   consisting of ‘C-c’ and a letter (either upper or lower case) are
> >   reserved for users; they are the *only* sequences reserved for
> >   users, so do not block them.
>
> There seems to be some uncertainty in how this should be
> interpreted. Does this mean that...
>
> - No package/library/third-party code may ever bind a command or map to
>   C-c LETTER, under any circumstances (in the letter of the law).
>
> - A package/library/third-party code may bind a command or a map to C-c
>   LETTER, if the user is explicitly asked and he or she gives
>   permission (in the spirit of the law).
>

IIRC, the intent was roughly "anyone interested in binding key inside Emacs
should assume that individual users may have arbitrary bindings to anything
inside C-c", with the strong implication that they cannot "safely"
establish any common or conventional binding inside that space. (I don't
recall if the original intent was restricted to C-c [alpha], C-c
[alphanum], or C-c [any-single].

If my memory from ~30 years ago is correct, this didn't outlaw a local
group from making packages that used C-c bindings, with the understanding
that a given lab or research group would manage conflicts within themselves
as needed. Of course, in those times a given elisp "package" was likely to
be distributed  uuencoded via email, ftp, or usenet, with changes noted in
RCS or SCCS headers, so "distribution" wasn't the same sort of concern.

Hope that helps,
~Chad

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

Re: Clarifying the C-c letter guideline

[Matt Armstrong]

chad <yandros@gmail.com> writes:

> On Sun, Feb 14, 2021 at 4:14 AM Philip Kaludercic <philipk@posteo.net>
> wrote:
>
>> > • Don’t define ‘C-c LETTER’ as a key in Lisp programs.  Sequences
>> >   consisting of ‘C-c’ and a letter (either upper or lower case) are
>> >   reserved for users; they are the *only* sequences reserved for
>> >   users, so do not block them.
>>
>> There seems to be some uncertainty in how this should be
>> interpreted. Does this mean that...
>>
>> - No package/library/third-party code may ever bind a command or map to
>>   C-c LETTER, under any circumstances (in the letter of the law).
>>
>> - A package/library/third-party code may bind a command or a map to C-c
>>   LETTER, if the user is explicitly asked and he or she gives
>>   permission (in the spirit of the law).
>>
>
> IIRC, the intent was roughly "anyone interested in binding key inside Emacs
> should assume that individual users may have arbitrary bindings to anything
> inside C-c", with the strong implication that they cannot "safely"
> establish any common or conventional binding inside that space. (I don't
> recall if the original intent was restricted to C-c [alpha], C-c
> [alphanum], or C-c [any-single].
>
> If my memory from ~30 years ago is correct, this didn't outlaw a local
> group from making packages that used C-c bindings, with the understanding
> that a given lab or research group would manage conflicts within themselves
> as needed. Of course, in those times a given elisp "package" was likely to
> be distributed  uuencoded via email, ftp, or usenet, with changes noted in
> RCS or SCCS headers, so "distribution" wasn't the same sort of concern.

Neat bit of history Chat.

I will say that I have successfully convinced non-Emacs packages to move
their default bindings off C-c <letter> based on this writeup. Most were
happy to do so once I pointed them to the docs.