Bind markdown-insert-list-item to M-RET rather than M-<return>
commitc0fc52461e845baa3c55d9b6f9e67c451a9ffa8d
authorKévin Le Gouguec <kevin.legouguec@gmail.com>
Wed, 14 Feb 2018 18:27:22 +0000 (14 19:27 +0100)
committerJason Blevins <jblevins@xbeta.org>
Sat, 26 May 2018 02:09:30 +0000 (25 22:09 -0400)
treeffd5cae529eb6a20e593add512c01850eefeb7b5
parent668de4a965980d618637a3b5754e721b54c51e83
Bind markdown-insert-list-item to M-RET rather than M-<return>

This follows what e.g. org-mode and tex-mode do:

    lisp/org/org.el:            (org-defkey org-mode-map (kbd "M-RET") #'org-meta-return)
    lisp/textmodes/tex-mode.el: (define-key map "\M-\r" 'latex-insert-item)

Long story short (but hopefully accurate):

- <return> refers to the physical "⏎" function key;

- terminals do not tell applications  that a function key was pressed,
  rather they send a character sequence;

- so on terminals, M-<return> cannot work;

- RET ≡  \r is  not an  actual key, but  rather the  control character
  emitted by pressing Control-M in a terminal;

- on graphical displays, Emacs  automatically translates <return> into
  RET if there is no binding for <return>.

Using M-RET rather than M-<return> allows the following things:

1. the binding works on terminals[^1];
2. C-M-m  now also works  as an alternative  (…  which was  my initial
   motivation to investigate this).

Sources and gory details:

- (emacs) Keymaps

    > Most modern  keyboards have function  keys as well  as character
    > keys.  Function  keys send input  events just as  character keys
    > do, and keymaps can have bindings for them.
    >
    > …
    >
    > On  text terminals,  typing a  function key  actually sends  the
    > computer a  sequence of characters;  the precise details  of the
    > sequence depends on the function key and on the terminal type.

- (emacs) Named ASCII Chars

    > Emacs can distinguish  these two kinds of input  if the keyboard
    > does.  It treats the special  keys as function keys named ‘tab’,
    > ‘return’,  ‘backspace’,  ‘linefeed’,   ‘escape’,  and  ‘delete’.
    > These   function   keys   translate   automatically   into   the
    > corresponding  ASCII characters  _if_ they  have no  bindings of
    > their own.
    >
    > If you  do not want  to distinguish between (for  example) <TAB>
    > and  ‘C-i’,  make just  one  binding,  for the  ASCII  character
    > <TAB> (octal code 011).  If you do want to distinguish, make one
    > binding for this  ASCII character, and another  for the function
    > key ‘tab’.
    >
    > With an ordinary ASCII terminal,  there is no way to distinguish
    > between <TAB>  and ‘C-i’  (and likewise  for other  such pairs),
    > because the terminal sends the same character in both cases.

- Xah Lee:

    - <http://ergoemacs.org/emacs/emacs_key_notation_return_vs_RET.html>
    - <http://ergoemacs.org/emacs/keyboard_shortcuts.html>
    - <http://ergoemacs.org/emacs/keystroke_rep.html>

- a *scratch* buffer:

        (kbd "RET")         ; "^M"
        (kbd "\r")          ; "^M"
        (kbd "C-m")         ; "^M"
        (kbd "<return>")    ; [return]

- on X:

        C-h c ⏎ ; RET (translated from <return>) runs the command newline

- on a TTY:

        C-h c ⏎ ; RET runs the command newline

[^1]:  Provided the  terminals send  the correct  character sequences.
This is not always straightforward.   Here are the results of pressing
Alt-⏎ on three different terminals:

    - on a TTY:         M-RET
    - on Terminator:    C-M-j
    - on XTerm:         toggles fullscreen

    With this .Xresources snippet:

        XTerm.vt100.translations: #override \n\
            Alt <Key>Return: insert-eight-bit()

    XTerm also sends M-RET.

Also add test for M-RET adding list items.
CHANGES.md
markdown-mode.el
tests/markdown-test.el