[nongnu] elpa/devil b84cd61eec 40/49: Format .org files consistently

[ELPA Syncer]

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

    Format .org files consistently
---
 CHANGES.org |  10 +
 LICENSE.org |   2 +-
 MANUAL.org  | 694 +++++++++++++++++++++++++++++++++---------------------------
 README.org  |  50 +++--
 4 files changed, 418 insertions(+), 338 deletions(-)

diff --git a/CHANGES.org b/CHANGES.org
index 85a7d6322e..260c80ab9e 100644
--- a/CHANGES.org
+++ b/CHANGES.org
@@ -1,6 +1,9 @@
 * Changelog
 
 ** 0.3.0 (2023-05-11)
+:PROPERTIES:
+:CUSTOM_ID: 0.3.0
+:END:
 
 *** Added
 
@@ -15,7 +18,11 @@
 - Fix spacing in documentation strings.
 - Remove =devil-version= and =devil-show-version=.
 
+
 ** 0.2.0 (2023-05-09)
+:PROPERTIES:
+:CUSTOM_ID: 0.2.0
+:END:
 
 *** Added
 
@@ -40,6 +47,9 @@
 
 
 ** 0.1.0 (2023-05-07)
+:PROPERTIES:
+:CUSTOM_ID: 0.1.0
+:END:
 
 *** Added
 
diff --git a/LICENSE.org b/LICENSE.org
index 6cdd83ec6b..baa8cf143f 100644
--- a/LICENSE.org
+++ b/LICENSE.org
@@ -1,6 +1,6 @@
 * The MIT License (MIT)
 :PROPERTIES:
-:CUSTOM_ID: the-mit-license-mit
+:CUSTOM_ID: the-mit-license
 :END:
 Copyright (c) 2022-2023 Susam Pal
 
diff --git a/MANUAL.org b/MANUAL.org
index 3cd3ca982b..2bdcc2b11d 100644
--- a/MANUAL.org
+++ b/MANUAL.org
@@ -9,109 +9,124 @@
 
 #+texinfo: @insertcopying
 
+Devil mode trades your comma key in exchange for a modifier-free
+editing experience!  Yes, the comma key!  The key you would normally
+wield for punctuation in nearly every corner of text.  Yes, this is
+twisted!  It would not be called the Devil otherwise, would it?  If it
+were any more rational, we might call it something divine, like, uh,
+the God mode?  But alas, there is nothing divine to be found here.
+Welcome, instead, to the realm of the Devil!  You will be granted the
+occasional use of the comma key for punctuation, but only if you can
+charm the Devil!  But beware, for in this sinister domain, you must
+relinquish your comma key and embrace an editing experience that
+whispers wicked secrets into your fingertips!
+
+* Introduction
+:PROPERTIES:
+:CUSTOM_ID: introduction
+:END:
 Devil mode intercepts our keystrokes and translates them to Emacs key
-sequences according to a configurable set of translation rules. For
+sequences according to a configurable set of translation rules.  For
 example, with the default translation rules, when we type =, x , f=,
 Devil translates it to =C-x C-f=.
 
 The choice of the comma key (=,=) to mean the control modifier key
-(=C-=) may seem outrageous. After all, the comma is a very important
-punctuation both in prose as well as in code. Can we really get away
-with using =,= to mean the =C-= modifier? It turns out, this terrible
-idea can be made to work without too much of a hassle. At least it works
-for me! It might work for you too. If it does not, Devil can be
-configured to use another key instead of =,= to mean the =C-= modifier.
-See the section [[#custom-devil-key][Custom Devil Key]] for an example.
-
-A sceptical reader may rightfully ask: If =,= is translated to =C-=, how
-on earth are we going to insert a literal =,= into the text when we need
-to? The section [[#typing-commas][Typing Commas]] answers this. But
-before we get there, we have some fundamentals to cover. Take the plunge
-and see what unfolds! Maybe you will like this! Maybe you will not! If
-you do not like this, you can always retreat to God mode, Evil mode, the
-vanilla key bindings, or whatever piques your fancy!
+(=C-=) may seem outrageous.  After all, the comma is a very important
+punctuation both in prose as well as in code.  Can we really get away
+with using =,= to mean the =C-= modifier?  It turns out, this terrible
+idea can be made to work without too much of a hassle.  At least it
+works for me!  It might work for you too.  If it does not, Devil can
+be configured to use another key instead of =,= to mean the =C-=
+modifier.  See the section [[*Custom Devil Key]] for an example.
+
+A sceptical reader may rightfully ask: If =,= is translated to =C-=,
+how on earth are we going to insert a literal =,= into the text when
+we need to?  The section [[*Typing Commas]] answers this.  But before we
+get there, we have some fundamentals to cover.  Take the plunge and
+see what unfolds!  Maybe you will like this!  Maybe you will not!  If
+you do not like this, you can always retreat to God mode, Evil mode,
+the vanilla key bindings, or whatever piques your fancy!
 
 * Notation
 :PROPERTIES:
 :CUSTOM_ID: notation
 :END:
 A quick note about the notation used in the document: The previous
-example shows that =, x , f= is translated to =C-x C-f=. What this
-really means is that the key sequence ,x,f is translated to ctrl+x
-ctrl+f. We do not really type any space after the commas. The key , is
-directly followed by the key x. However, the key sequence notation used
-in this document contains spaces between each keystroke. This is
-consistent with how key sequences are represented in Emacs in general
-and how Emacs functions like =key-description=, =describe-key=, etc.
-represent key sequences. When we really need to type a space, it is
-represented as =SPC=.
+example shows that =, x , f= is translated to =C-x C-f=.  What this
+really means is that the keystrokes =,x,f= is translated to =ctrl+x
+ctrl+f=.  We do not really type any space after the commas.  The key
+=,= is directly followed by the key =x=.  However, the key sequence
+notation used in this document contains spaces between each keystroke.
+This is consistent with how key sequences are represented in Emacs in
+general and how Emacs functions like =key-description=,
+=describe-key=, etc.  represent key sequences.  When we really need to
+type a space, it is represented as =SPC=.
 
 * Install
 :PROPERTIES:
 :CUSTOM_ID: install
 :END:
+
 ** Install Interactively from MELPA
 :PROPERTIES:
 :CUSTOM_ID: install-interactively-from-melpa
 :END:
-Devil is available via [[https://melpa.org/][MELPA]]. You may already
-have a preferred way of installing packages from MELPA. If so, install
-the package named =devil= to get Devil. For the sake of completeness,
-here is a very basic way of installing Devil from MELPA:
+Devil is available via [[https://melpa.org/][MELPA]].  You may already have a 
preferred way of
+installing packages from MELPA.  If so, install the package named
+=devil= to get Devil.  For the sake of completeness, here is a very
+basic way of installing Devil from MELPA:
 
-1. Add the following to the Emacs initialization file (i.e., =~/.emacs=
-   or =~/.emacs.d/init.el= or =~/.config/emacs/init.el=):
+1. Add the following to the Emacs initialization file (i.e.,
+   =~/.emacs= or =~/.emacs.d/init.el= or =~/.config/emacs/init.el=):
 
-   #+begin_src sh
+   #+begin_src elisp
      (require 'package)
      (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/";) 
t)
      (package-initialize)
    #+end_src
 
-2. Start Emacs with the updated initialization file and then type these
-   commands:
+2. Start Emacs with the updated initialization file and then type
+   these commands:
 
    #+begin_example
-   M-x package-refresh-contents RET
-   M-x package-install RET devil RET
+     M-x package-refresh-contents RET
+     M-x package-install RET devil RET
    #+end_example
 
 3. Confirm that Devil is installed successfully with this command:
 
    #+begin_example
-   M-x devil-show-version RET
+     C-h f devil RET
    #+end_example
 
 4. Enable Devil mode with this command:
 
    #+begin_example
-   M-x global-devil-mode RET
+     M-x global-devil-mode RET
    #+end_example
 
 5. Type =, x , f= and watch Devil translate it to =C-x C-f= and invoke
    the corresponding command.
 
 ** Install Automatically from MELPA
-:PROPERTIES:
-:CUSTOM_ID: install-automatically-from-melpa
-:END:
-Here is yet another basic way to install and enable Devil using Elisp:
 
-#+begin_example
-(require 'package)
-(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/";) t)
-(package-initialize)
-(unless package-archive-contents
-  (package-refresh-contents))
-(unless (package-installed-p 'devil)
-  (package-install 'devil))
-(global-devil-mode)
-(global-set-key (kbd "C-,") 'global-devil-mode)
-#+end_example
+Here is yet another basic way to install and enable Devil using Elisp:
 
-Now type =, x , f= and watch Devil translate it to =C-x C-f= and invoke
-the corresponding command. Type =C-,= to disable Devil mode. Type =C-,=
-again to enable it.
+#+begin_src elisp
+  (require 'package)
+  (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/";) t)
+  (package-initialize)
+  (unless package-archive-contents
+    (package-refresh-contents))
+  (unless (package-installed-p 'devil)
+    (package-install 'devil))
+  (global-devil-mode)
+  (global-set-key (kbd "C-,") 'global-devil-mode)
+#+end_src
+
+Now type =, x , f= and watch Devil translate it to =C-x C-f= and
+invoke the corresponding command.  Type =C-,= to disable Devil mode.
+Type =C-,= again to enable it.
 
 ** Install from Git Source
 :PROPERTIES:
@@ -122,196 +137,200 @@ steps:
 
 1. Clone Devil to your system:
 
-   #+begin_src sh
-   git clone https://github.com/susam/devil.git
+   #+begin_src shell
+     git clone https://github.com/susam/devil.git
    #+end_src
 
 2. Add the following to your Emacs initialization:
 
-   #+begin_example
-   (add-to-list 'load-path "/path/to/devil/")
-   (require 'devil)
-   (global-devil-mode)
-   (global-set-key (kbd "C-,") 'global-devil-mode)
-   #+end_example
+   #+begin_src elisp
+     (add-to-list 'load-path "/path/to/devil/")
+     (require 'devil)
+     (global-devil-mode)
+     (global-set-key (kbd "C-,") 'global-devil-mode)
+   #+end_src
 
-3. Start the Emacs editor. Devil mode should now be enabled in all
-   buffers. The modeline of each buffer should show the =Devil= lighter.
+3. Start the Emacs editor.  Devil mode should now be enabled in all
+   buffers.  The modeline of each buffer should show the =Devil=
+   lighter.
 
 4. Type =, x , f= and watch Devil translate it to =C-x C-f= and invoke
-   the corresponding command. Type =C-,= to disable Devil mode. Type
+   the corresponding command.  Type =C-,= to disable Devil mode.  Type
    =C-,= again to enable it.
 
 * Use Devil
-   :PROPERTIES:
-   :CUSTOM_ID: use-devil
-   :END:
-Assuming vanilla Emacs key bindings have not been changed and Devil has
-not been customised, here are some examples that demonstrate how Devil
-may be used:
+:PROPERTIES:
+:CUSTOM_ID: use-devil
+:END:
+Assuming vanilla Emacs key bindings have not been changed and Devil
+has not been customised, here are some examples that demonstrate how
+Devil may be used:
 
 1. Type =, x , f= and watch Devil translate it to =C-x C-f= and invoke
-   the find file functionality.
+   the =find-file= command.
 
 2. Type =, p= to move up one line.
 
-3. To move up multiple lines, type =, p p p= and so on. Some Devil key
-   sequences are repeatable keys. The repeatable Devil key sequences can
-   be repeated by typing the last key of the Devil key sequence over and
-   over again.
+3. To move up multiple lines, type =, p p p= and so on.  Some Devil
+   key sequences are repeatable keys by default.  The repeatable Devil
+   key sequences can be repeated by typing the last key of the Devil
+   key sequence over and over again.
 
-4. Another example of a repeatable Devil key sequence is =, f f f= which
-   moves the cursor word by multiple characters. A few other examples of
-   repeatable keys are =, k k k= to kill lines, =, / / /= to undo
-   changs, etc. Type =C-h v devil-repeatable-keys RET= to see the
-   complete list of repeatable keys.
+4. Another example of a repeatable Devil key sequence is =, f f f=
+   which moves the cursor word by multiple characters.  A few other
+   examples of repeatable keys are =, k k k= to kill lines, =, / / /=
+   to undo changs, etc.  Type =C-h v devil-repeatable-keys RET= to see
+   the complete list of repeatable keys.
 
 5. Type =, s= and watch Devil translate it to =C-s= and invoke
    incremental search.
 
 6. Type =, m s= and watch Devil translate it to =C-M-s= and invoke
-   regular-expression-based incremental search. Yes, =m= is translated
-   to =M-=.
+   regular-expression-based incremental search.  Yes, =m= is
+   translated to =M-=.
 
 7. Type =, m m x= and watch Devil translate it to =M-x= and invoke the
    corresponding command.
 
-8. Type =, u , f= and watch Devil translate it to =C-u C-f= and move the
-   cursor forward by 4 characters.
+8. Type =, u , f= and watch Devil translate it to =C-u C-f= and move
+   the cursor forward by 4 characters.
 
-9. Type =, u u , f= and the cursor moves forward by 16 characters. Devil
-   uses its translation rules and an additional keymap to make the input
-   key sequence behave like =C-u C-u C-f= which moves the cursor forward
-   by 16 characters.
+9. Type =, u u , f= and the cursor moves forward by 16 characters.
+   Devil uses its translation rules and an additional keymap to make
+   the input key sequence behave like =C-u C-u C-f= which moves the
+   cursor forward by 16 characters.
 
-10. Type =, SPC= to type a comma followed by space. This is a special
-    key sequence to make it convenient to type a comma in the text. Note
-    that this sacrifices the use of =, SPC= to mean =C-SPC= which could
-    have been a convenient way to set a mark.
+10. Type =, SPC= to type a comma followed by space.  This is a special
+    key sequence to make it convenient to type a comma in the text.
+    Note that this sacrifices the use of =, SPC= to mean =C-SPC= which
+    could have been a convenient way to set a mark.
 
 11. Type =, z SPC= and watch Devil translate it to =C-SPC= and set a
-    mark. Yes, =, z= is translated to =C-= too.
+    mark.  Yes, =, z= is translated to =C-= too.
 
-12. Similarly, type =, RET= to type a comma followed by the return key.
-    This is another special key.
+12. Similarly, type =, RET= to type a comma followed by the =enter=
+    key.  This is another special key.
 
-13. Type =, ,= to type a single comma. This special key is useful for
+13. Type =, ,= to type a single comma.  This special key is useful for
     cases when you really need to type a single literal comma.
 
 * Typing Commas
-   :PROPERTIES:
-   :CUSTOM_ID: typing-commas
-   :END:
-Devil makes the questionable choice of using the comma as its activation
-key. As illustrated in the previous section, typing =, x , f= produces
-the same effect as typing =C-x C-f=. One might naturally wonder how then
-we are supposed to type literal commas.
+:PROPERTIES:
+:CUSTOM_ID: typing-commas
+:END:
+Devil makes the questionable choice of using the comma as its
+activation key.  As illustrated in the previous section, typing =, x ,
+f= produces the same effect as typing =C-x C-f=.  One might naturally
+wonder how then we are supposed to type literal commas.
 
 Most often when we edit text, we do not really type a comma in
-isolation. Often we immediately follow the comma with a space or a
-newline. This assumption usually holds good while editing regular text.
-However, this assumption may not hold in some situations, like while
-working with code when we need to add a single comma at the end of an
-existing line.
+isolation.  Often we immediately follow the comma with a space or a
+newline.  This assumption usually holds good while editing regular
+text.  However, this assumption may not hold in some situations, like
+while working with code when we need to add a single comma at the end
+of an existing line.
 
 In scenarios where the above assumption holds good, typing =, SPC=
-inserts a comma and a space. Similarly, typing =, RET= inserts a comma
-and a newline.
+inserts a comma and a space.  Similarly, typing =, RET= inserts a
+comma and a newline.
 
 In scenarios, when we do need to type a single comma, type =, ,=
 instead.
 
 Also, it is worth mentioning here that if all this fiddling with the
 comma key feels clumsy, we could always customise the Devil key to
-something else that feels better. We could also disable Devil mode
-temporarily and enable it again later with =C-,= as explained in section
-[[#use-devil][Use Devil]].
+something else that feels better.  We could also disable Devil mode
+temporarily and enable it again later with =C-,= as explained in
+section [[*Install]].
 
 * Devil Reader
-   :PROPERTIES:
-   :CUSTOM_ID: devil-reader
-   :END:
+:PROPERTIES:
+:CUSTOM_ID: devil-reader
+:END:
 The following points briefly describe how Devil reads Devil key
 sequences, translates them to Emacs key sequences, and runs commands
 bound to the key sequences:
 
 1. As soon as the Devil key is typed (which is =,= by default), Devil
-   wakes up and starts reading Devil key sequences. Type
-   =C-h v     devil-key RET= to see the current Devil key.
+   wakes up and starts reading Devil key sequences.  Type =C-h v
+   devil-key RET= to see the current Devil key.
 
 2. After each keystroke is read, Devil checks if the key sequence
-   accumulated is a special key. If it is, then the special command
-   bound to the special key is executed immediately. Note that this step
-   is performed before any translation rules are applied to the input
-   key sequence. This is how the Devil special key sequence =,     SPC=
-   inserts a comma and a space. Type =C-h v     devil-special-keys RET=
-   to see the list of special keys and the commands bound to them.
+   accumulated is a special key.  If it is, then the special command
+   bound to the special key is executed immediately.  Note that this
+   step is performed before any translation rules are applied to the
+   input key sequence.  This is how the Devil special key sequence =,
+   SPC= inserts a comma and a space.  Type =C-h v devil-special-keys
+   RET= to see the list of special keys and the commands bound to
+   them.
 
 3. If the key sequence accumulated so far is not a special key, then
    Devil translates the Devil key sequence to a regular Emacs key
-   sequence. If the regular Emacs key sequence turns out to be a
+   sequence.  If the regular Emacs key sequence turns out to be a
    complete key sequence and some command is found to be bound to it,
-   then that command is executed immediately. This is how the Devil key
-   sequence =, x , f= is translated to =C-x C-f= and the corresponding
-   binding is executed. If the translated key sequence is a complete key
-   sequence but no command is bound to it, then Devil displays a message
-   that the key sequence is undefined. Type
-   =C-h v devil-translations RET= to see the list of translation rules.
+   then that command is executed immediately.  This is how the Devil
+   key sequence =, x , f= is translated to =C-x C-f= and the
+   corresponding binding is executed.  If the translated key sequence
+   is a complete key sequence but no command is bound to it, then
+   Devil displays a message that the key sequence is undefined.  Type
+   =C-h v devil-translations RET= to see the list of translation
+   rules.
 
 4. After successfully translating a Devil key sequence to an Emacs key
    sequence and executing the command bound to it, Devil checks if the
-   key sequence is a repeatable key sequence. If it is found to be a
-   repeatable key sequence, then Devil sets a transient map so that the
-   command can be repeated merely by typing the last keystroke of the
-   input key sequence. This is how =, p p p= moves the cursor up by
-   three lines. Type =C-h v devil-repeatable-keys     RET= to see the
+   key sequence is a repeatable key sequence.  If it is found to be a
+   repeatable key sequence, then Devil sets a transient map so that
+   the command can be repeated merely by typing the last keystroke of
+   the input key sequence.  This is how =, p p p= moves the cursor up
+   by three lines.  Type =C-h v devil-repeatable-keys RET= to see the
    list of repeatable Devil key sequences.
 
 The variables =devil-special-keys=, =devil-translations=, and
-=devil-repeatable-keys= may contain keys or values with the string =%k=
-in them. This is a placeholder for =devil-key=. While applying the
-special keys, translation rules, or repeat rules, each =%k= is replaced
-with the actual value of =devil-key= before applying the rules.
+=devil-repeatable-keys= may contain keys or values with the string
+=%k= in them.  This is a placeholder for =devil-key=.  While applying
+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
-   :PROPERTIES:
-   :CUSTOM_ID: translation-rules
-   :END:
+:PROPERTIES:
+:CUSTOM_ID: translation-rules
+: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
 user to an Emacs key sequence:
 
 1. The input key vector read from the user is converted to a key
    description (i.e., the string functions like =describe-key=,
-   =key-description=, produce). For example, if the user types ,x,f, it
-   is converted to =, x , f=.
+   =key-description=, produce).  For example, if the user types ,x,f,
+   it is converted to =, x , f=.
 
 2. Now the resulting key description is translated with simple string
-   replacements. If any part of the string matches a key in
+   replacements.  If any part of the string matches a key in
    =devil-translations=, then it is replaced with the corresponding
-   value. For example, =, x , f= is translated to =C- x C- f=. Then
+   value.  For example, =, x , f= is translated to =C- x C- f=.  Then
    Devil normalises the result to =C-x C-f= by removing superfluous
    spaces after the modifier keys.
 
 3. However, if the simple string based replacement leads to an invalid
    Emacs key sequence, it skips the replacement that causes the
-   resulting Emacs key sequence to become invalid. For example
-   =,     m ,= results in =C-M-C-= after the simple string replacement
-   because the default translation rules replace =,= with =C-= and =m=
-   with =M-=. However, =C-M-C-= is an invalid key sequence, so the
-   replacement of the second =,= to =C-= is skipped. Therefore, the
+   resulting Emacs key sequence to become invalid.  For example =, m
+   ,= results in =C-M-C-= after the simple string replacement because
+   the default translation rules replace =,= with =C-= and =m= with
+   =M-=.  However, =C-M-C-= is an invalid key sequence, so the
+   replacement of the second =,= to =C-= is skipped.  Therefore, the
    input =, m ,= is translated to =C-M-,= instead.
 
 * Translation Examples
-   :PROPERTIES:
-   :CUSTOM_ID: translation-examples
-   :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.
+:PROPERTIES:
+:CUSTOM_ID: translation-examples
+: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                           |
 |-----------+------------+-----------------------------------|
@@ -324,119 +343,160 @@ translations come later in the table.
 
 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.
+so Devil translates =, z= to =C-= too, so that we can still type
+=C-SPC= using =, z s= 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.
 
 * Bonus Key Bindings
-   :PROPERTIES:
-   :CUSTOM_ID: bonus-key-bindings
-   :END:
+:PROPERTIES:
+:CUSTOM_ID: bonus-key-bindings
+:END:
 Devil adds the following additional key bindings only when Devil is
 enabled globally with =global-devil-mode=:
 
-- Adds the Devil key to =isearch-mode-map=, so that Devil key sequences
-  work in incremental search too.
+- Adds the Devil key to =isearch-mode-map=, so that Devil key
+  sequences work in incremental search too.
 
-- Adds =u= to =universal-argument-more= to allow repeating the universal
-  argument command =C-u= simply by repeating =u=.
+- Adds =u= to =universal-argument-more= to allow repeating the
+  universal argument command =C-u= simply by repeating =u=.
 
 As mentioned before these features are available only when Devil is
-enabled globally with =global-devil-mode=. If Devil is enabled locally
-with =devil-mode=, then these features are not available.
+enabled globally with =global-devil-mode=.  If Devil is enabled
+locally with =devil-mode=, then these features are not available.
 
 * Custom Configuration Examples
-   :PROPERTIES:
-   :CUSTOM_ID: custom-configuration-examples
-   :END:
+:PROPERTIES:
+:CUSTOM_ID: custom-configuration-examples
+:END:
 In the examples presented below, the =(require 'devil)= calls may be
-omitted if Devil has been installed from MELPA. There are appropriate
+omitted if Devil has been installed from MELPA.  There are appropriate
 autoloads in place in the Devil package that would ensure that it is
-loaded automatically on enabling Devil mode. However, the =require=
+loaded automatically on enabling Devil mode.  However, the =require=
 calls have been included in the examples below for the sake of
 completeness.
 
 ** Local Mode
-    :PROPERTIES:
-    :CUSTOM_ID: local-mode
-    :END:
-While the section [[#use-devil][Use Devil]] shows how we enable Devil mode 
globally,
+:PROPERTIES:
+:CUSTOM_ID: local-mode
+:END:
+While the section [[*Install]] shows how we enable Devil mode globally,
 this section shows how we can enable it locally.  Here is an example
 initialization code that enables Devil locally only in text buffers.
 
-#+begin_example
-(require 'devil)
-(add-hook 'text-mode-hook 'devil-mode)
-(global-set-key (kbd "C-,") 'devil-mode)
-#+end_example
+#+begin_src elisp
+  (require 'devil)
+  (add-hook 'text-mode-hook 'devil-mode)
+  (global-set-key (kbd "C-,") 'devil-mode)
+#+end_src
 
-This is not recommended though because this does not provide a seamless
-Devil experience. For example, with Devil enabled locally in a text
-buffer like this, although we can type =, x , f= to launch the find-file
-minibuffer, we cannot use Devil key sequences in the minibuffer. Further
-the special keymaps described in the previous section work only when
-Devil is enabled globally.
+This is not recommended though because this does not provide a
+seamless Devil experience.  For example, with Devil enabled locally in
+a text buffer like this, although we can type =, x , f= to launch the
+find-file minibuffer, we cannot use Devil key sequences in the
+minibuffer.  Further the special keymaps described in the previous
+section work only when Devil is enabled globally.
 
 ** Custom Appearance
-    :PROPERTIES:
-    :CUSTOM_ID: custom-appearance
-    :END:
+:PROPERTIES:
+:CUSTOM_ID: custom-appearance
+:END:
 The following initialization code shows how we can customise Devil to
-show a Devil smiley (😈) in the modeline and the echo area.
+show a Devil smiley (😈) in the modeline and in the Devil prompt.
 
-#+begin_example
-(require 'devil)
-(setq devil-lighter " \U0001F608")
-(setq devil-prompt "\U0001F608 %t")
-(global-devil-mode)
-(global-set-key (kbd "C-,") 'global-devil-mode)
-#+end_example
-
-This is how Emacs may look if emojis are rendered correctly:
+#+begin_src elisp
+  (require 'devil)
+  (setq devil-lighter " \U0001F608")
+  (setq devil-prompt "\U0001F608 %t")
+  (global-devil-mode)
+  (global-set-key (kbd "C-,") 'global-devil-mode)
+#+end_src
 
-[[https://i.imgur.com/oYtwnGi.png][[[https://i.imgur.com/oYtwnGi.png]]]]
+** Reclaim , SPC to Set Mark
+:PROPERTIES:
+:CUSTOM_ID: reclaim-comma-spc-to-set-mark
+:END:
+The default configuration for special keys reserves =, SPC= to insert
+a literal comma followed by space.  This default makes it easy to type
+space in various contexts.  However, this means that =, SPC= does not
+translate to =C-SPC=.  Therefore =, SPC= cannot be used to set mark.
+Instead, the default translation rules offer =, z SPC= as a way to set
+mark.
+
+If you would rather set mark using =, SPC= and you are happy with the
+special key =, ,= alone to insert a literal comma and you are okay
+with typing comma twice everytime you want to insert a literal comma,
+then the special keys
+
+#+begin_src elisp
+  (require 'devil)
+  (global-devil-mode)
+  (setq devil-special-keys '(("%k %k" . (lambda () (interactive) 
(devil-run-key "%k")))))
+#+end_src
+
+This reduces the number of special keys so that only =, ,= is treated
+as special.  All the other special key definitions (=, SPC= was one of
+them) are removed.  As a result, =, SPC= is now translated to =C-SPC=.
 
 ** Custom Devil Key
-    :PROPERTIES:
-    :CUSTOM_ID: custom-devil-key
-    :END:
+:PROPERTIES:
+:CUSTOM_ID: custom-devil-key
+:END:
 The following initialization code shows how we can customise Devil to
 use a different Devil key.
 
-#+begin_example
-(defvar devil-key "<left>")
-(defvar devil-special-keys '(("%k %k" . (lambda () (interactive) 
(devil-run-key "%k")))))
-(require 'devil)
-(global-devil-mode)
-(global-set-key (kbd "C-<left>") 'global-devil-mode)
-#+end_example
+#+begin_src elisp
+  (defvar devil-key ";")
+  (require 'devil)
+  (global-devil-mode)
+  (global-set-key (kbd "C-;") 'global-devil-mode)
+#+end_src
+
+The above example sets the Devil key to the semicolon, perhaps another
+dubious choice for the Devil key.  With this configuration, we can use
+=; x ; f= and have Devil translate it to =C-x C-f=.
+
+** Yet Another Custom Devil Key
+:PROPERTIES:
+:CUSTOM_ID: yet-another-custom-devil-key
+:END:
+The following initialization code shows how we can customise Devil to
+use yet another different Devil key.
+
+#+begin_src elisp
+  (defvar devil-key "<left>")
+  (defvar devil-special-keys '(("%k %k" . (lambda () (interactive) 
(devil-run-key "%k")))))
+  (require 'devil)
+  (global-devil-mode)
+  (global-set-key (kbd "C-<left>") 'global-devil-mode)
+#+end_src
 
 The above example sets the Devil key to the left arrow key, perhaps
-another dubious choice for the Devil key. With this configuration, we
+another dubious choice for the Devil key.  With this configuration, we
 can use =<left> x <left> f= and have Devil translate it to =C-x C-f=.
 
 Additionally, the above example defines the =devil-special-keys=
 variable to have a single entry that allows typing =<left> <left>= to
-produce the same effect as the original =<left>=. It removes the other
-entries, so that =<left> SPC= is no longer reserved as a special key.
-Thus =<left> SPC= can now be used to set a mark like one would normally
-expect.
+produce the same effect as the original =<left>=.  It removes the
+other entries, so that =<left> SPC= is no longer reserved as a special
+key.  Thus =<left> SPC= can now be used to set a mark like one would
+normally expect.
 
 ** Multiple Devil Keys
-    :PROPERTIES:
-    :CUSTOM_ID: multiple-devil-keys
-    :END:
-While this package provides the comma (=,=) as the default and the only
-Devil key, nothing stops you from extending the mode map to support
-multiple Devil keys. Say, you decide that in addition to activating
-Devil with =,= which also plays the role of =C-=, you also want to
-activate Devil with =.= which must now play the role of =M-=. To achieve
-such a result, you could use this initialization code as a starting
-point and then customise it further based on your requirements:
-
-#+begin_example
+:PROPERTIES:
+:CUSTOM_ID: multiple-devil-keys
+:END:
+While this package provides the comma (=,=) as the default and the
+only Devil key, nothing stops you from extending the mode map to
+support multiple Devil keys.  Say, you decide that in addition to
+activating Devil with =,= which also plays the role of =C-=, you also
+want to activate Devil with =.= which must now play the role of =M-=.
+To achieve such a result, you could use this initialization code as a
+starting point and then customise it further based on your
+requirements:
+
+#+begin_src elisp
 (defvar devil-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key map (kbd ",") #'devil)
@@ -448,99 +508,100 @@ point and then customise it further based on your 
requirements:
                              ("." . "M-")))
 (require 'devil)
 (global-devil-mode)
-#+end_example
+#+end_src
 
 With this configuration, we can type =, x , f= for =C-x C-f= like
-before. But now we can also type =. x= for =M-x=. Similarly, we can type
-=, . s= for =C-M-s= and so on. Further, =, ,= inserts a literal comma
-and =. .= inserts a literal dot.
+before.  But now we can also type =. x= for =M-x=.  Similarly, we can
+type =, . s= for =C-M-s= and so on.  Further, =, ,= inserts a literal
+comma and =. .= inserts a literal dot.
 
 Note that by default Devil configures only one activation key (=,=)
 because the more activation keys we add, the more intrusive Devil
-becomes during regular editing tasks. Every key that we reserve for
-activating Devil loses its default function and then we need workarounds
-to somehow invoke the default function associated with that key (like
-repeating =.= twice to insert a single =.= in the above example).
-Therefore, it is a good idea to keep the number of Devil keys as small
-as possible.
+becomes during regular editing tasks.  Every key that we reserve for
+activating Devil loses its default function and then we need
+workarounds to somehow invoke the default function associated with
+that key (like repeating =.= twice to insert a single =.= in the above
+example).  Therefore, it is a good idea to keep the number of Devil
+keys as small as possible.
 
 * Why?
-   :PROPERTIES:
-   :CUSTOM_ID: why
-   :END:
-Why go to the trouble of creating and using something like this? Why not
-just remap caps lock to ctrl like every other sane person does? Or if it
-is so important to avoid modifier keys, why not use something like God
-mode or Evil mode?
+:PROPERTIES:
+:CUSTOM_ID: why
+:END:
+Why go to the trouble of creating and using something like this?  Why
+not just remap =caps lock= to =ctrl= like every other sane person
+does?  Or if it is so important to avoid modifier keys, why not use
+something like God mode or Evil mode?
 
 Well, for one, both God mode and Evil mode are modal editing modes.
 Devil, on the other hand, provides a modeless editing experience of
 Emacs as possible.
 
-Devil mode began as a fun little tiny experiment. From the outset, it
+Devil mode began as a fun little tiny experiment.  From the outset, it
 was clear that using something as crucial as the comma for specifying
-the modifier key is asking for trouble. However, I still wanted to see
-how far I could go with it. It turned out that in a matter of days, I
-was using it full-time for all of my Emacs usage.
+the modifier key is asking for trouble.  However, I still wanted to
+see how far I could go with it.  It turned out that in a matter of
+days, I was using it full-time for all of my Emacs usage.
 
 This experiment was partly motivated by Macbook keyboards which do not
-have a right ctrl key. Being a touch-typist myself, I found it
+have a right =ctrl= key.  Being a touch-typist myself, I found it
 inconvenient to type key combinations like =C-x=, =C-a=, =C-w=, =C-s=,
-etc. where both the modifier key and the modified key need to be pressed
-with the left hand fingers. I am not particularly fond of remapping caps
-lock to behave like ctrl because that still suffers from the problem
-that key combinations like =C-x=, =C-a= require pressing both the
-modifier key and the modified key with the left hand fingers. I know
-many people remap both their caps lock and enter to behave like ctrl.
-While I think that is a fine solution, I was not willing to put up with
-the work required to make that work seamlessly across all the various
-operating systems I work on.
-
-What began as a tiny whimsical experiment a few years ago turned out to
-be quite effective, at least to me. I like that this solution is
+etc.  where both the modifier key and the modified key need to be
+pressed with the left hand fingers.  I am not particularly fond of
+remapping caps lock to behave like =ctrl= because that still suffers
+from the problem that key combinations like =C-x=, =C-a= require
+pressing both the modifier key and the modified key with the left hand
+fingers.  I know many people remap both their =caps lock= and =enter=
+to behave like =ctrl=.  While I think that is a fine solution, I was
+not willing to put up with the work required to make that work
+seamlessly across all the various operating systems I work on.
+
+What began as a tiny whimsical experiment a few years ago turned out
+to be quite effective, at least to me.  I like that this solution is
 implemented purely as Elisp and therefore does not have any external
-dependency. I am sharing this solution here in the form of a minor mode,
-just in case, there is someone out there who might find this useful too.
+dependency.  I am sharing this solution here in the form of a minor
+mode, just in case, there is someone out there who might find this
+useful too.
 
 * Comparison with God Mode
-   :PROPERTIES:
-   :CUSTOM_ID: comparison-with-god-mode
-   :END:
-God mode provides a modal editing experience but Devil does not. Devil
-has the same underlying philosophy as that of God mode, i.e., the user
-should not have to learn new key bindings. However, Devil does not have
-a hard separation between insert mode and command mode like God mode
-has. Instead, Devil waits for an activation key (=,= by default) and as
-soon as it is activated, it intercepts and translates keys, runs the
-corresponding command, and then gets out of the way. So Devil tries to
-retain the modeless editing experience of vanilla Emacs as much as
-possible.
-
-Now it is worth mentioning that some of this modeless editing experience
-can be reproduced in god-mode too using its
-=god-execute-with-current-bindings= function. Here is an example:
-
-#+begin_example
-(global-set-key (kbd ",") #'god-execute-with-current-bindings)
-#+end_example
+:PROPERTIES:
+:CUSTOM_ID: comparison-with-god-mode
+:END:
+God mode provides a modal editing experience but Devil does not.
+Devil has the same underlying philosophy as that of God mode, i.e.,
+the user should not have to learn new key bindings.  However, Devil
+does not have a hard separation between insert mode and command mode
+like God mode has.  Instead, Devil waits for an activation key (=,= by
+default) and as soon as it is activated, it intercepts and translates
+keys, runs the corresponding command, and then gets out of the way.
+So Devil tries to retain the modeless editing experience of vanilla
+Emacs as much as possible.
+
+Now it is worth mentioning that some of this modeless editing
+experience can be reproduced in god-mode too using its
+=god-execute-with-current-bindings= function.  Here is an example:
+
+#+begin_src elisp
+  (global-set-key (kbd ",") #'god-execute-with-current-bindings)
+#+end_src
 
 With this configuration, God mode translates =, x f= to =C-x C-f=.
-Similarly =, g x= invokes =M-x= and =, G s= invokes =C-M-x=. This
-provides a modeless editing experience in God mode too. However, this
-experience does not extend seamlessly to minibuffers. Devil does extend
-its Devil key translation to minibuffers.
-
-Further note that in God mode the ctrl modifier has sticky behaviour,
-i.e., the modifier remains active automatically for the entire key
-sequence. Therefore in the above example, we type =,= only once while
-typing =, x f= to invoke =C-x C-f=. However, this sticky behaviour
-implies that we need some way to disambiguate between key sequences like
-=C-x C-o= (delete blank lines) and =C-x o= (other window). God mode
-solves this by introducing =SPC= to deactivate the modifier, e.g.,
-=, x o= translates to =C-x C-o= but =, x SPC o= translates to =C-x o=.
-Devil does not treat the modifier key as sticky which leads to simpler
-key sequences at the cost of a little additional typing, i.e., =, x , o=
-translates to =C-x C-o= and =, x o= translates to =C-x o=.
+Similarly =, g x= invokes =M-x= and =, G s= invokes =C-M-x=.  This
+provides a modeless editing experience in God mode too.  However, this
+experience does not extend seamlessly to minibuffers.  Devil does
+extend its Devil key translation to minibuffers.
+
+Further note that in God mode the =ctrl= modifier has sticky
+behaviour, i.e., the modifier remains active automatically for the
+entire key sequence.  Therefore in the above example, we type =,= only
+once while typing =, x f= to invoke =C-x C-f=.  However, this sticky
+behaviour implies that we need some way to disambiguate between key
+sequences like =C-x C-f= (find-file) and =C-x o= (set-fill-column).
+God mode solves this by introducing =SPC= to deactivate the modifier,
+e.g., =x f= translates to =C-x C-f= but =x SPC o= translates to =C-x
+o=.  Devil does not treat the modifier key as sticky which leads to
+simpler key sequences at the cost of a little additional typing, i.e.,
+=, x , o= translates to =C-x C-o= and =, x o= translates to =C-x o=.
 
 To summarize, there are primarily three things that Devil does
 differently:
@@ -548,17 +609,16 @@ differently:
 - Provide a modeless editing experience from the outset.
 - Seamlessly extend the same editing experience to minibuffer,
   incremental search, etc.
-- Translate key sequences using string replacements. This allows for
+- Translate key sequences using string replacements.  This allows for
   arbitrary and sophisticated key translations for the adventurous.
 - Choose non-sticky behaviour for the modifier keys.
 
-These differences could make Devil easier to use than God mode for some
-people but clumsy for other people. It depends on one's tastes and
-preferences.
+These differences could make Devil easier to use than God mode for
+some people but clumsy for other people.  It depends on one's tastes
+and preferences.
 
 * Support
-   :PROPERTIES:
-   :CUSTOM_ID: support
-   :END:
-To report bugs, suggest improvements, or ask questions,
-[[https://github.com/susam/devil/issues][create issues]].
+:PROPERTIES:
+:CUSTOM_ID: support
+:END:
+To report bugs, suggest improvements, or ask questions, 
[[https://github.com/susam/devil/issues][create issues]].
diff --git a/README.org b/README.org
index 0a3b82572f..1e00f9c587 100644
--- a/README.org
+++ b/README.org
@@ -1,21 +1,23 @@
 * Devil Mode
 
-Devil mode trades your comma key in exchange for a modifier-free editing
-experience! Yes, the comma key! The key you would normally wield for
-punctuation in nearly every corner of text. Yes, this is twisted! It
-would not be called the Devil otherwise, would it? If it were any more
-rational, we might call it something divine, like, uh, the God mode? But
-alas, there is nothing divine to be found here. Welcome, instead, to the
-realm of the Devil! You will be granted the occasional use of the comma
-key for punctuation, but only if you can charm the Devil! But beware,
-for in this sinister domain, you must relinquish your comma key and
-embrace an editing experience that whispers wicked secrets into your
-fingertips!
+Devil mode trades your comma key in exchange for a modifier-free
+editing experience!  Yes, the comma key!  The key you would normally
+wield for punctuation in nearly every corner of text.  Yes, this is
+twisted!  It would not be called the Devil otherwise, would it?  If it
+were any more rational, we might call it something divine, like, uh,
+the God mode?  But alas, there is nothing divine to be found here.
+Welcome, instead, to the realm of the Devil!  You will be granted the
+occasional use of the comma key for punctuation, but only if you can
+charm the Devil!  But beware, for in this sinister domain, you must
+relinquish your comma key and embrace an editing experience that
+whispers wicked secrets into your fingertips!
 
 Read the [[./MANUAL.org][manual]] for more details on how to use Devil.
 
 ** Channels
-
+:PROPERTIES:
+:CUSTOM_ID: channels
+:END:
 The author of this project hangs out at the following places online:
 
 - Website: [[https://susam.net][susam.net]]
@@ -24,13 +26,21 @@ The author of this project hangs out at the following 
places online:
 - GitHub: [[https://github.com/susam][@susam]]
 
 You are welcome to subscribe to, follow, or join one or more of the
-above channels to receive updates from the author or ask questions about
-this project.
-
-** More
+above channels to receive updates from the author or ask questions
+about this project.
 
-See [[https://github.com/susam/emacs4cl][Emacs4CL]], a DIY quick-starter
-kit to set up Emacs for Common Lisp programming.
+* Support
+:PROPERTIES:
+:CUSTOM_ID: support
+:END:
+To report bugs, suggest improvements, or ask questions, 
[[https://github.com/susam/devil/issues][create issues]].
 
-See [[https://github.com/susam/emfy][Emfy]], a DIY quick-starter kit to
-set up Emacs for general purpose editing and programming.
+** More
+:PROPERTIES:
+:CUSTOM_ID: more
+:END:
+See [[https://github.com/susam/emacs4cl][Emacs4CL]], a DIY quick-starter kit 
to set up Emacs for Common Lisp
+programming.
+
+See [[https://github.com/susam/emfy][Emfy]], a DIY quick-starter kit to set up 
Emacs for general purpose
+editing and programming.