[nongnu] elpa/devil fc62e58314 1/2: Translate "m m" to "m" and "m z" to "M"

[ELPA Syncer]

branch: elpa/devil
commit fc62e583148b2a4d57987204a87e91f7ad52d48c
Author: Susam Pal <susam@susam.net>
Commit: Susam Pal <susam@susam.net>

    Translate "m m" to "m" and "m z" to "M"
---
 CHANGES.org    |  3 +++
 MANUAL.org     | 75 ++++++++++++++++++++++++++++++++++++++++++++--------------
 README.org     |  2 +-
 devil-tests.el | 13 +++++++++-
 devil.el       |  4 +++-
 5 files changed, 76 insertions(+), 21 deletions(-)

diff --git a/CHANGES.org b/CHANGES.org
index c765463150..d81cdab516 100644
--- a/CHANGES.org
+++ b/CHANGES.org
@@ -12,6 +12,9 @@
 - Add =, s= to the default list of repeatable keys.
 - Add =, d= to the default list of repeatable keys.
 - Add =, m m ^= to the default list of repeatable keys.
+- Translate =m m= to =m= to support typing key sequences like =C-c m=.
+- Translate =m z= to =M-= to support typing key sequences like =C-c
+  M-m= and =C-M-m=.
 
 *** Changed
 
diff --git a/MANUAL.org b/MANUAL.org
index f80ae602ed..d9ae1a61ab 100644
--- a/MANUAL.org
+++ b/MANUAL.org
@@ -309,9 +309,9 @@ the special keys, translation rules, or repeat rules, each 
=%k= is
 replaced with the actual value of =devil-key= before applying the
 rules.
 
-* Translation Rules
+** Translation Mechanism
 :PROPERTIES:
-:CUSTOM_ID: translation-rules
+:CUSTOM_ID: translation-mechanism
 :END:
 The following points provide an account of the translation rules that
 Devil follows in order to convert a Devil key sequence entered by the
@@ -346,34 +346,73 @@ user to an Emacs key sequence:
    to the previous points and then the result is translated to
    =C-M-S-v= according to this point.
 
-* Translation Examples
+* Default Translation Rules
 :PROPERTIES:
-:CUSTOM_ID: translation-examples
+:CUSTOM_ID: default-translation-rules
 :END:
 By default, Devil supports a small but peculiar set of translation
 rules that can be used to avoid modifier keys while typing various
 types of key sequences.  See =C-h v devil-translations RET= for the
 translation rules.  Here are some examples that demonstrate the
-default translation rules.  The obvious ones are shown first first.
-The more peculiar translations come later in the table.
-
-| Input     | Translated | Remarks                           |
-|-----------+------------+-----------------------------------|
-| =, s=     | =C-s=      | =,= is replaced with =C-=         |
-| =, m s=   | =C-M-s=    | =m= is replaced with =M-=         |
-| =, z s=   | =C-SPC=    | =, z= is replaced with =C-= too   |
-| =, z z=   | =C-z=      | ditto                             |
-| =, m m x= | =M-x=      | =, m m= is replaced with =M-= too |
-| =, c , ,= | =C-c ,=    | =, ,= is replaced with =,=        |
+default translation rules.  The obvious ones are shown first.  The
+more peculiar translations come later in the table.  The concluding
+paragraph of this subsection offers a guide on how to gradually and
+gently adopt these key sequences into your daily routine.
+
+| Input       | Translated | Remarks                           |
+|-------------+------------+-----------------------------------|
+| =, s=       | =C-s=      | =,= is replaced with =C-=         |
+| =, m s=     | =C-M-s=    | =m= is replaced with =M-=         |
+| =, z SPC=   | =C-SPC=    | =, z= is replaced with =C-= too   |
+| =, z z=     | =C-z=      | ditto                             |
+| =, z ,=     | =C-,=      | ditto                             |
+| =, c m m=   | =C-c m=    | =m m= is replaced with =m=        |
+| =, c m z m= | =C-c M-m=  | =m z= is replaced with =M-= too   |
+| =, m z m=   | =C-M-m=    | ditto                             |
+| =, m m x=   | =M-x=      | =, m m= is replaced with =M-= too |
+| =, c , ,=   | =C-c ,=    | =, ,= is replaced with =,=        |
 
 Note how we cannot use =, SPC= to set a mark because that key sequence
-is already reserved as a special key sequence in =devil-special-keys=,
-so Devil translates =, z= to =C-= too, so that we can still type
-=C-SPC= using =, z s= and set a mark.
+is already reserved as a special key sequence in =devil-special-keys=.
+In order to conveniently set a mark, Devil translates =, z= to =C-=
+too, so that we can still type =C-SPC= using =, z SPC= and set a mark.
 
 Also, note how the translation of =, m m= to =M-= allows us to enter a
 key sequence that begins with the =M-= modifier key.
 
+The default translation examples presented in the table above look
+weirder and weirder as we go down the table.  But the default
+translation rules are not as arbitrary as they might initially appear
+to be.  The translation rules are arranged in such a way that overall,
+we get the following effect:
+
+- In a Devil key sequence, we see that the special character =,=
+  translates to =C-= and similarly =m= translates to =M-= according to
+  the default translation rules.
+
+- If we really want the Devil key sequence to translate to an actual
+  =,= or =m=, then we need to double type the special character, i.e.,
+  in a Devil key sequence, we see that =, ,= translates to =,= and =m
+  m= translates to =m=.  Doubling the special character serves as an
+  escape mechanism to avoid the special meaning of the character and
+  get the literal form of the character instead.
+
+- Now since =, ,= translates to =,= we need another escape mechanism
+  to type =C-,=.  Putting =z= in between serves as this escape
+  mechanism, i.e., =, z ,= translates to =C-,= and similarly within a
+  Devil key sequence =m z m= translates to =M-m=.
+
+*Gentle guide to adopting these key sequences:* The above table pretty
+much summarizes the default translation rules.  For beginners using
+Devil, it is not necessary to memorize all of them right away.
+Understanding that =,= translates to =C-= and =m= translates to =M-=
+is sufficient to begin.  Subsequently, learning that =, m m= also
+translates to =M-= unlocks several more key sequences like =, m m x=
+(=M-x=), =, m m f= (=M-f=), etc.  As you encounter more key sequences
+that are not covered by these initial rules, revisit the table to pick
+up new translation rules and adopt them in your day-to-day usage of
+Devil.
+
 * Bonus Key Bindings
 :PROPERTIES:
 :CUSTOM_ID: bonus-key-bindings
diff --git a/README.org b/README.org
index ba4567d550..edbd93127c 100644
--- a/README.org
+++ b/README.org
@@ -24,7 +24,7 @@ that whispers wicked secrets into your fingertips!
 
 By default, Devil mode rebinds the comma key to activate Devil.  Once
 activated, Devil reads a so-called Devil key sequence from you.  As
-you type your Devil key sequence, Emacs translates the key sequence to
+you type your Devil key sequence, Devil translates the key sequence to
 a regular Emacs key sequence.  If any command is bound to the
 translated Emacs key sequence, Devil runs that command and then
 deactivates itself.
diff --git a/devil-tests.el b/devil-tests.el
index ac95e6c253..7150140fba 100644
--- a/devil-tests.el
+++ b/devil-tests.el
@@ -79,7 +79,18 @@
   (should (string= (devil-translate (vconcat ",\r")) "C-RET"))
   (should (string= (devil-translate (vconcat ",m\r")) "C-M-RET"))
   (should (string= (devil-translate (vconcat ",mm\r")) "M-RET"))
-  (should (string= (devil-translate (vconcat ",\r,R,mm\r")) "C-RET C-S-r 
M-RET")))
+  (should (string= (devil-translate (vconcat ",\r,R,mm\r")) "C-RET C-S-r 
M-RET"))
+  ;; Translations provided in the manual as examples.
+  (should (string= (devil-translate (vconcat ",s")) "C-s"))
+  (should (string= (devil-translate (vconcat ",ms")) "C-M-s"))
+  (should (string= (devil-translate (vconcat ",z ")) "C-SPC"))
+  (should (string= (devil-translate (vconcat ",zz")) "C-z"))
+  (should (string= (devil-translate (vconcat ",z,")) "C-,"))
+  (should (string= (devil-translate (vconcat ",cmm")) "C-c m"))
+  (should (string= (devil-translate (vconcat ",cmzm")) "C-c M-m"))
+  (should (string= (devil-translate (vconcat ",mzm")) "C-M-m"))
+  (should (string= (devil-translate (vconcat ",mmx")) "M-x"))
+  (should (string= (devil-translate (vconcat ",c,,")) "C-c ,")))
 
 (provide 'devil-tests)
 ;;; devil-tests.el ends here
diff --git a/devil.el b/devil.el
index f8ee68d388..66d96f00d9 100644
--- a/devil.el
+++ b/devil.el
@@ -4,7 +4,7 @@
 
 ;; Author: Susam Pal <susam@susam.net>
 ;; Maintainer: Susam Pal <susam@susam.net>
-;; Version: 0.4.0.pre4
+;; Version: 0.4.0.pre5
 ;; Package-Requires: ((emacs "24.4"))
 ;; Keywords: convenience, abbrev
 ;; URL: https://github.com/susam/devil
@@ -99,6 +99,8 @@ represent `key-description' of `devil-key' in the keys.")
   (list (cons "%k z" "C-")
         (cons "%k %k" "%k")
         (cons "%k m m" "M-")
+        (cons "m z" "M-")
+        (cons "m m" "m")
         (cons "%k"  "C-")
         (cons "m" "M-"))
   "Translation rules to convert Devil input to Emacs key sequence.