This is loco.info, produced by makeinfo version 7.2 from loco.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Loco: (loco). Enter complex key sequences with ease!
END-INFO-DIR-ENTRY


File: loco.info,  Node: Top,  Next: Table of contents,  Up: (dir)

Loco
****

Loco is a library and minor mode to help you enter complex key sequences
with ease.

* Menu:

* Table of contents::
* Introduction::
* Installation::
* Background::
* Usage::
* Author and copyright::
* License::
* Colophon::


File: loco.info,  Node: Table of contents,  Next: Introduction,  Prev: Top,  Up: Top

1 Table of contents
*******************

   • *note Examples using the default configuration: Examples using the
     default configuration.

   • *note From MELPA: From MELPA.

   • *note From source: From source.

   • *note Keys key sequences and commands: Keys key sequences and
     commands.

   • *note How Loco is different: How Loco is different.

   • *note Enabling and disabling Loco: Enabling and disabling Loco.

   • *note The default configuration: The default configuration.
        • *note Activating Loco: Activating Loco.

        • *note Entering key sequences: Entering key sequences.
             • *note Normal operation ie when the Assist Menu is closed:
               Normal operation ie when the Assist Menu is closed.

             • *note Assisted operation ie when the Assist Menu is open:
               Assisted operation ie when the Assist Menu is open.

             • *note Rock and roll: Rock and roll.

             • *note Persistent keys: Persistent keys.

             • *note Typical key sequences and their translations:
               Typical key sequences and their translations.

             • *note More difficult key sequences and their
               translations: More difficult key sequences and their
               translations.

   • *note Describing commands: Describing commands.

   • *note Standard configurations: Standard configurations.
        • *note Details::

        • *note Summary::

   • *note Repeating commands: Repeating commands.

   • *note Working with physical modifier keys: Working with physical
     modifier keys.

   • *note Considerations when using a terminal: Considerations when
     using a terminal.

   • *note Customization::
        • *note Using the "Easy Customization Interface": Using the
          "Easy Customization Interface".

        • *note Mapping Caps Lock to Control: Mapping Caps Lock to
          Control.

        • *note Going further: Going further.


File: loco.info,  Node: Introduction,  Next: Installation,  Prev: Table of contents,  Up: Top

2 Introduction
**************

Loco is a package
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html)
for Emacs (https://www.gnu.org/software/emacs/).  Loco lets you type any
*note key sequence: Keys key sequences and commands, including those
requiring the modifiers ‘Alt’, ‘Control’, ‘Hyper’, ‘Meta’, or ‘Super’,
without using any physical modifier keys except ‘Shift’.  This makes it
easy to enter key sequences that are complicated or use hard-to-reach
keys.

Loco works by translating key sequences from one form to another.  It
does not redefine the standard key bindings
(https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf), nor does
it prevent you from defining your own
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Key-Bindings.html).
Learn the few rules of Loco and be productive immediately, using the key
bindings you already know.

Loco does not preclude the use of physical modifier keys; it integrates
well with them.  There may even be some key bindings for which you find
using physical modifier keys preferable.  And it works equally well in
the GUI (https://en.wikipedia.org/wiki/Graphical_user_interface) or the
terminal (https://en.wikipedia.org/wiki/Computer_terminal), working
around the *note limitations of terminals: Considerations when using a
terminal. that prevent the entry of certain keys, allowing you to move
between both easily.

When enabled, and using the default configuration, pressing ‘S-<return>’
will activate Loco.

     In Emacs, ‘S-<return>’ means hold ‘Shift’ then press ‘Return’.
Once activated, you can type any key sequence, taking advantage of the
following special keys to help you avoid pressing any physical modifier
keys:

   • ‘j’ to apply the modifier ‘Control’ to the next non‑special key;
   • ‘k’ to apply the modifier ‘Meta’ to the next non‑special key; or
   • ‘l’ to open a menu that includes options to:
        • apply other modifiers (for example, ‘Alt’, ‘Hyper’, or
          ‘Super’) to the next non‑special key; or
        • enter the special keys themselves as the literal characters
          _j_, _k_, or _l_.

* Menu:

* Examples using the default configuration::


File: loco.info,  Node: Examples using the default configuration,  Up: Introduction

2.1 Examples (using the default configuration)
==============================================

Typed Key Sequence   Translated Key Sequence   Command
---------------------------------------------------------------
‘j d’                ‘C-d’                     ‘delete-char’
‘k d’                ‘M-d’                     ‘kill-word’
‘j h i’              ‘C-h i’                   ‘info’
‘j x j s’            ‘C-x C-s’                 ‘save-buffer’

The default configuration is not the only way to use Loco, it is one of
a set of pre-defined *note standard configurations: Standard
configurations.  Loco can also be *note extensively customized:
Customization. with just a few lines of code.  Many options are
possible, including:

   • Changing the key bindings used to enable, disable, or activate
     Loco;
   • Changing the keys used while Loco reads a key sequence;
   • Configuring activation keys that also function as modifiers; and
   • Configuring activation keys that avoid modifiers completely.


File: loco.info,  Node: Installation,  Next: Background,  Prev: Introduction,  Up: Top

3 Installation
**************

* Menu:

* From MELPA::
* From source::


File: loco.info,  Node: From MELPA,  Next: From source,  Up: Installation

3.1 From MELPA
==============

To install Loco from MELPA (https://melpa.org), follow these steps:

  1. Modify your Emacs configuration

        • Open your Emacs init file
          (https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html)
          and add the following:

          ;; Add MELPA to the list of package archives
          (require 'package)
          (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
          (package-initialize)
          
          ;; Refresh the descriptions of all packages in all package archives
          (unless package-archive-contents
            (package-refresh-contents))
          
          ;; Install the `loco` package
          (unless (package-installed-p 'loco)
            (package-install 'loco))
          
          ;; Load `loco`
          (require 'loco)
          
          ;; Set the default configuration for Loco
          (loco-set-default-configuration)
          
          ;; Enable Loco in all buffers
          (global-loco-mode 1)

        • Apply your changes by either restarting Emacs or evaluating
          the modified sections of your configuration file.


File: loco.info,  Node: From source,  Prev: From MELPA,  Up: Installation

3.2 From source
===============

To install Loco from source, follow these steps:

  1. Clone the official repository (https://github.com/csmclaren/loco)
     from GitHub

     git clone https://github.com/csmclaren/loco.git

  2. Modify your Emacs configuration

        • Open your Emacs init file
          (https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html)
          and add the following, making sure to replace ‘/path/to/loco’
          with the path to your cloned repository:

          ;; Add the load path
          (add-to-list 'load-path "/path/to/loco")
          
          ;; Load `loco`
          (require 'loco)
          
          ;; Set the default configuration for Loco
          (loco-set-default-configuration)
          
          ;; Enable Loco in all buffers
          (global-loco-mode 1)

        • Apply your changes by either restarting Emacs or evaluating
          the modified sections of your configuration file.


File: loco.info,  Node: Background,  Next: Usage,  Prev: Installation,  Up: Top

4 Background
************

* Menu:

* Keys key sequences and commands::
* How Loco is different::


File: loco.info,  Node: Keys key sequences and commands,  Next: How Loco is different,  Up: Background

4.1 Keys, key sequences, and commands
=====================================

When discussing keys, it is helpful to distinguish between _physical_
keys and _logical_ keys.

A physical key is what you press with your fingers on the keyboard.
Some physical keys are called _modifier_ keys.  Emacs recognizes six
modifier keys: ‘Alt’, ‘Control’, ‘Hyper’, ‘Meta’, ‘Super’, and ‘Shift’.
Your keyboard may not have all of these keys.  Furthermore, your
keyboard may have different names for the modifier keys that it does
have.  For example, ‘Super’ is called ‘Command’ on Apple keyboards
(https://en.wikipedia.org/wiki/Apple_keyboards), and ‘Meta’ is called
‘Alt’ or ‘Option’ on most modern keyboards.  Most physical keys, like
letters, numbers, and symbols, are _non-modifier_ keys.

A logical key (or simply a _key_) is zero or more modifier keys pressed
simultaneously with a non-modifier key.  For example, holding down the
physical ‘Control’ key (written as ‘C-’) while pressing the physical ‘x’
key produces the key ‘C-x’.

Key sequences are composed of one or more keys.  For example, the key
sequence ‘C-x s’ is composed of two keys: ‘C-x’ and ‘s’.  Key sequences
can be bound to commands.  For example, ‘C-x s’ is bound to the command
‘save-all-files’.

By composing key sequences from keys, a large number of key sequences
can be created from a small number of keys.  This is similar to how an
alphabet can be used to compose the words of a language: a large number
of words can be created from a small number of letters.


File: loco.info,  Node: How Loco is different,  Prev: Keys key sequences and commands,  Up: Background

4.2 How Loco is different
=========================

On modern keyboards, which typically have small or hard-to-reach
modifier keys, or for people with RSI
(https://en.wikipedia.org/wiki/Repetitive_strain_injury) or other forms
of limited mobility, pressing one or more keys simultaneously can be
difficult or even painful.  This is especially true when two or more
modifier keys are required to complete a single key, or if a certain
modifier key is particularly hard to reach.

To help solve this problem, Loco extends the idea of composing key
sequences from keys to the level of the key itself.  In Loco, logical
keys can be composed of one or more physical keys pressed one after the
other, not simultaneously.  Additionally, Loco uses certain
easy-to-reach non-modifier keys (or _special_ keys) to assist you with
key entry.


File: loco.info,  Node: Usage,  Next: Author and copyright,  Prev: Background,  Up: Top

5 Usage
*******

* Menu:

* Enabling and disabling Loco::
* The default configuration::
* Describing commands::
* Standard configurations::
* Repeating commands::
* Working with physical modifier keys::
* Considerations when using a terminal::
* Customization::


File: loco.info,  Node: Enabling and disabling Loco,  Next: The default configuration,  Up: Usage

5.1 Enabling and disabling Loco
===============================

Loco works by adding a minor mode
(https://www.gnu.org/software/emacs/manual/html_node/elisp/Minor-Modes.html)
to Emacs.  This mode can be enabled or disabled in some or all buffers.

To enable or disable Loco _in the current buffer_, use the command
‘loco-mode’.  The key sequence ‘C-c ,’ is bound to this command;
pressing it will toggle Loco in the current buffer.

You can also call this command using Emacs Lisp with:

   • No argument, ‘nil’, or a positive number to enable Loco in the
     current buffer;

     (loco-mode 1) ; Enable in the current buffer

   • A zero or negative number to disable Loco in the current buffer; or

     (loco-mode 0) ; Disable in the current buffer

   • The symbol ‘toggle’ to toggle Loco in the current buffer.

     (loco-mode 'toggle) ; Toggle in the current buffer

To enable or disable Loco _in all buffers_, use the command
‘global-loco-mode’.  The key sequence ‘C-c .’ is bound to this command;
pressing it will toggle Loco in all buffers.

     This command will override any local settings.
You can also call this command using Emacs Lisp with:

   • No argument, ‘nil’, or a positive number to enable Loco in all
     buffers;

     (global-loco-mode 1) ; Enable in all buffers

   • A zero or negative number to disable Loco in all buffers; or

     (global-loco-mode 0) ; Disable in all buffers

   • The symbol ‘toggle’ to toggle Loco in all buffers.

     (global-loco-mode 'toggle) ; Toggle in all buffers

When Loco is _disabled_ in the current buffer, all keys can be typed
normally as if Loco were not installed, with the exception of ‘C-c ,’
and ‘C-c .’ themselves, which are bound in the global keymap.

When Loco is _enabled_ in the current buffer it will place an indicator,
which Emacs calls a "lighter", in the mode line of that buffer.  The
lighter for Loco is simply the string "Loco".


File: loco.info,  Node: The default configuration,  Next: Describing commands,  Prev: Enabling and disabling Loco,  Up: Usage

5.2 The default configuration
=============================

     This section assumes that you are using the default configuration
     for Loco, as recommended in *note Installation::.

* Menu:

* Activating Loco::
* Entering key sequences::


File: loco.info,  Node: Activating Loco,  Next: Entering key sequences,  Up: The default configuration

5.2.1 Activating Loco
---------------------

When Loco is enabled, it will bind two additional key sequences:
‘S-<return>’ and ‘C-h S-<return>’.  Pressing either of these will
_activate_ Loco.

When Loco is activated, it will prompt you to enter a key sequence, then
it will lookup whether or not that key sequence is bound to a command.
If a command is found, it will either execute or describe that command,
depending on which key sequence was used to activate it.  ‘S-<return>’
tells Loco that it should _execute_ the command.  ‘C-h S-<return>’ tells
Loco it should _describe_ the command.


File: loco.info,  Node: Entering key sequences,  Prev: Activating Loco,  Up: The default configuration

5.2.2 Entering key sequences
----------------------------

When Loco reads a key sequence:

   • It tracks a set of modifiers (‘Alt’, ‘Control’, ‘Hyper’, ‘Meta’,
     and ‘Super’) that it considers "pending".

   • ‘j’ and ‘k’ add ‘Control’ and ‘Meta’, respectively, to the set of
     pending modifiers, or represent themselves, if their respective
     modifiers are already pending.

   • ‘l’ opens the Assist Menu, a menu which includes commands to toggle
     pending modifiers (‘a’ ‘c’ ‘h’ ‘m’ and ‘s’) or enter keys for which
     there is no other way to enter because they have been repurposed by
     Loco (‘j’ ‘k’ and ‘l’ itself).

   • When a key is pressed to which modifiers could be applied, any
     pending modifiers from that set are applied to the key, as if the
     equivalent physical modifier keys were held down at the time the
     key was pressed.  The set (if not empty) is then cleared.  The key
     (now potentially modified) is then added to the key sequence.

   • When a key is added to the key sequence, Loco will check if the key
     sequence is bound to a command.  If it is a _partial match_ to one
     (or more) commands, Loco will continue to read keys.  If it is an
     _exact match_ to a command, Loco will stop reading keys and execute
     or describe that command (depending on how Loco was activated).
     Otherwise, Loco will stop reading keys and tell the user that no
     match was found.

   • It will display its prompt in the minibuffer.  The prompt will
     consist of:

        • A right-pointing triangle (▶);

        • The current key sequence, if any, displayed in the normal
          Emacs style;

        • The set of pending modifiers, if any, displayed in the normal
          Emacs style, i.e., ‘A-’, ‘C-’, ‘H-’, ‘M-’, and ‘s-’,
          corresponding to the modifiers ‘Alt’, ‘Control’, ‘Hyper’,
          ‘Meta’, and ‘Super’, respectively; and

        • The Assist Menu, if open, displayed as ‘[;]’ (in its collapsed
          state) or ‘[achms jkl q x ;]’ (in its expanded state).

The following tables explain exactly how key presses are handled while
reading a key sequence.

* Menu:

* Normal operation ie when the Assist Menu is closed::
* Assisted operation ie when the Assist Menu is open::
* Rock and roll::
* Persistent keys::
* Typical key sequences and their translations::
* More difficult key sequences and their translations::


File: loco.info,  Node: Normal operation ie when the Assist Menu is closed,  Next: Assisted operation ie when the Assist Menu is open,  Up: Entering key sequences

5.2.2.1 Normal operation (i.e., when the Assist Menu is closed)
...............................................................

Key   Rule
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
‘j’   There are two possibilities for how this key is handled.  If ‘Control’ is already pending, apply all pending modifiers to the key (clearing the modifiers), then add the modified key to the key sequence.  Otherwise, add ‘Control’ to the set of pending modifiers.
‘k’   There are two possibilities for how this key is handled.  If ‘Meta’ is already pending, apply all pending modifiers to the key (clearing the modifiers), then add the modified key to the key sequence.  Otherwise, add ‘Meta’ to the set of pending modifiers.
‘l’   Open the Assist Menu.
Other Apply any pending modifiers to the key (clearing the modifiers), then add the (potentially modified) key to the key sequence.


File: loco.info,  Node: Assisted operation ie when the Assist Menu is open,  Next: Rock and roll,  Prev: Normal operation ie when the Assist Menu is closed,  Up: Entering key sequences

5.2.2.2 Assisted operation (i.e., when the Assist Menu is open)
...............................................................

Key                      Rule
-------------------------------------------------------------------------------------------------------------------------------------------------------------
‘a’ ‘c’ ‘h’ ‘m’ or ‘s’   Toggle ‘Alt’ ‘Control’ ‘Hyper’ ‘Meta’ or ‘Super’ respectively, in the set of pending modifiers, and close the Assist Menu.
‘A’ ‘C’ ‘H’ ‘M’ or ‘S’   Toggle ‘Alt’ ‘Control’ ‘Hyper’ ‘Meta’ or ‘Super’ respectively, in the set of pending modifiers, but do not close the Assist Menu.
‘j’ ‘k’ or ‘l’           Apply any pending modifiers to the key (clearing the modifiers), add the (potentially modified) key to the key sequence, and
                         close the Assist Menu.
‘q’                      Close the Assist Menu and cancel the key sequence (equivalent to ‘C-g’).
‘x’                      Close the Assist Menu.
‘;’                      Toggle the Assist Menu between its collapsed and expanded states.
Other                    Discard the key, but do not close the Assist Menu.  If the Assist Menu is currently collapsed, expand it to remind the user of
                         all available options.


File: loco.info,  Node: Rock and roll,  Next: Persistent keys,  Prev: Assisted operation ie when the Assist Menu is open,  Up: Entering key sequences

5.2.2.3 Rock and roll
.....................

The keys ‘j’, ‘k’, and ‘l’ were chosen to represent ‘Control’, ‘Meta’,
and the Assist Menu, respectively, because on a QWERTY
(https://en.wikipedia.org/wiki/QWERTY) keyboard these keys are adjacent.
This allows you to roll from side to side or rock your fingers back and
forth over them.

Furthermore, you can build up the set of pending modifiers for a key in
any order; for example, both ‘j k’ and ‘k j’ translate to ‘C-M-’.

These design choices enable efficient key entry, enhancing your ability
to enter these important keys swiftly and accurately.


File: loco.info,  Node: Persistent keys,  Next: Typical key sequences and their translations,  Prev: Rock and roll,  Up: Entering key sequences

5.2.2.4 Persistent keys
.......................

On the Assist Menu, the keys used to toggle modifiers (‘a’, ‘c’, ‘h’,
‘m’, and ‘s’) can be pressed in conjunction with the physical ‘Shift’
key (‘A’, ‘C’, ‘H’, ‘M’, and ‘S’, respectively).

These ‘Shift’-modified keys perform the same operation as their
unmodified counterparts but make the Assist Menu _persistent_: after
use, the menu remains open to use again.

The advantage of these keys is that multiple modifiers can be added or
removed quickly.  The disadvantage is that another key (for example,
‘x’) is then required to close the Assist Menu.

These keys are optional and not shown on the Assist Menu.


File: loco.info,  Node: Typical key sequences and their translations,  Next: More difficult key sequences and their translations,  Prev: Persistent keys,  Up: Entering key sequences

5.2.2.5 Typical key sequences and their translations
....................................................

Most key sequences do not involve ‘Control’ or ‘Meta’ in conjunction
with ‘j’, ‘k’, or ‘l’, making them easy to enter.

Typed Key Sequence   Translated Key Sequence   Command
--------------------------------------------------------------------
‘j e’                ‘C-e’                     ‘move-end-of-line’
‘k e’                ‘M-e’                     ‘forward-sentence’
‘j k e’ or ‘k j e’   ‘C-M-e’                   ‘end-of-defun’


File: loco.info,  Node: More difficult key sequences and their translations,  Prev: Typical key sequences and their translations,  Up: Entering key sequences

5.2.2.6 More difficult key sequences and their translations
...........................................................

Nine key sequences involve ‘Control’ or ‘Meta’ in conjunction with ‘j’,
‘k’, or ‘l’, making them more difficult to enter.

Typed Key Sequence       Translated Key Sequence   Command
-------------------------------------------------------------------------------
‘j l j’ or ‘j j’         ‘C-j’                     ‘eval-print-last-sexp’
‘j l k’                  ‘C-k’                     ‘kill-line’
‘j l l’                  ‘C-l’                     ‘recenter-top-bottom’
‘k l j’                  ‘M-j’                     ‘default-indent-new-line’
‘k l k’ or ‘k k’         ‘M-k’                     ‘kill-sentence’
‘k l l’                  ‘M-l’                     ‘downcase-word’
‘j k j’ or ‘k j j’       ‘C-M-j’                   ‘default-indent-new-line’
‘j k k’ or ‘k j k’       ‘C-M-k’                   ‘kill-sexp’
‘j k l l’ or ‘k j l l’   ‘C-M-l’                   ‘reposition-window’


File: loco.info,  Node: Describing commands,  Next: Standard configurations,  Prev: The default configuration,  Up: Usage

5.3 Describing commands
=======================

The built-in command ‘describe-key’ waits for a key sequence to be
input.  If that key sequence is bound to a command, it describes the
command.  This is an excellent way to discover (or remind yourself) of
the command to which a key sequence is bound.

In the global keymap, ‘C-h k’ is bound to ‘describe-key’.

This command reads key sequences directly, without leveraging Loco, but
Loco provides similar functionality.

For purposes of describing a key sequence, when Loco is enabled in the
current buffer, use ‘C-h S-<return>’ to activate Loco.  Then enter a key
sequence, and Loco will describe the command to which it is bound.


File: loco.info,  Node: Standard configurations,  Next: Repeating commands,  Prev: Describing commands,  Up: Usage

5.4 Standard configurations
===========================

A standard configuration is a named set of keys and behaviours for
activating Loco and entering key sequences to execute or describe the
commands to which they are bound.  Eleven such configurations are
included in Loco.

Standard configurations can be installed or uninstalled easily by
applying ‘loco-set-standard-configuration’ or
‘loco-unset-standard-configuration’, respectively, to the name of the
configuration.

These allow one to use Loco beyond what is provided by the default
configuration, but without requiring more substantial customization.
The default configuration is itself defined as one of the standard
configurations (‘shift-return-jk’).

* Menu:

* Details::
* Summary::


File: loco.info,  Node: Details,  Next: Summary,  Up: Standard configurations

5.4.1 Details
-------------

   • ‘shift‑return‑jk’

     This is the default configuration, described *note above: The
     default configuration.

     Note that this:

     (loco-set-default-configuration)

     is equivalent to:

     (loco-set-standard-configuration 'shift‑return‑jk)

     Similarly, this:

     (loco-unset-default-configuration)

     is equivalent to:

     (loco-unset-standard-configuration 'shift‑return‑jk)

   • ‘control‑return‑jk’ and ‘super‑return‑jk’

     These are similar to ‘shift‑return‑jk’, but use different modifier
     keys for activation.

     Instead of using ‘S-<return>’ to activate Loco, they use
     ‘C-<return>’ and ‘s-<return>’, respectively.  And instead of using
     ‘C-h S-<return>’ for purposes of describing a key sequence, they
     use ‘C-h C-<return>’ and ‘C-h s-<return>’, respectively.

     These configurations may be preferable if ‘Control’ or ‘Super’ are
     better located on your keyboard or if you have already bound
     ‘S-<return>’ to another command.  Other than the change of
     activation key, all other functionality remains the same as per
     ‘shift‑return‑jk’.

   • ‘shift‑return‑cp’, ‘control‑return‑cp’, and ‘super‑return‑cp’

     These are similar to the above three configurations in terms of
     activation, but use different keys to enter key sequences.

     Instead of using ‘j’ for ‘Control’, ‘k’ for ‘Meta’, ‘l’ to open the
     Assist Menu, and ‘;’ to toggle the Assist Menu between its
     collapsed and expanded states, they use ‘,’, ‘.’, ‘m’, and ‘/’
     respectively.

     These configurations may be preferable for those who find it easier
     to mentally associate the modifiers to punctuation (‘,’ and ‘.’
     instead of ‘j’ and ‘k’, respectively), or remember ‘m’ as "menu".

     Note that by using ‘m’ to open the Assist Menu, we need to rely on
     the Assist Menu to help us enter a literal _m_ when necessary.
     There is a potential conflict here.  By default, the Assist Menu
     reserves ‘a’ ‘c’ ‘h’ ‘m’ and ‘s’ to toggle pending modifiers then
     close the Assist Menu.  To ensure that ‘m’ inserts a literal _m_,
     ‘m’ is removed from the list of keys that toggle pending modifiers
     in these configurations.  For clarity and consistency, we also
     remove _c_ from the Assist Menu in these configurations.

     The Assist Menu displays itself according to the keys as you've
     configured them.  When using the default configuration, for
     example, the Assist Menu will display itself (when open and
     expanded) like this: ‘[achms jkl q x ;]’.  In these configurations,
     it will display itself (when open and expanded) like this: ‘[ahs
     ,.m q x /]’.

          Note that, by default, the Assist Menu also reserves ‘A’ ‘C’
          ‘H’ ‘M’ and ‘S’ as the *note persistent: Persistent keys.
          versions of ‘a’ ‘c’ ‘h’ ‘m’ and ‘s’, respectively.  None of
          the persistent versions of these keys are removed from these
          configurations, so there does remain a means to toggle
          ‘Control’ and ‘Meta’ from the Assist Menu if desired.
   • ‘control‑jk’

     Activation keys can also function as modifiers, allowing you to
     both activate Loco and set a pending modifier with a single key.

     In this configuration, ‘C-j’ and ‘C-k’ both activate Loco to read a
     key sequence and execute the command to which it is bound, but
     ‘C-j’ activates Loco with ‘Control’ pending and ‘C-k’ with ‘Meta’
     pending.

     For purposes of describing a key sequence, ‘C-h C-j’ activates Loco
     with ‘Control’ pending and ‘C-h C-k’ with ‘Meta’ pending.

     Entering key sequences is similar to ‘shift‑return‑jk’,
     ‘control‑return‑jk’, and ‘super‑return‑jk’, but this configuration
     will also strip all modifiers from any key that it reads.

     As per *note Working with physical modifier keys: Working with
     physical modifier keys, Loco is happy to merge any modified keys
     with any pending modifiers.  When activating Loco with a key that
     is similar to the keys required to toggle pending modifiers,
     accidentally holding any physical modifier key past its intended
     key may modify subsequent keys, resulting in a key sequence bound
     to a different command that intended.  Stripping modifiers from
     keys allows for some forgiveness when typing quickly, to ensure the
     modifiers aren't incorrectly applied to the wrong keys.

   • ‘super‑jk’

     This configuration is similar to ‘control‑jk’, but uses different
     modifier keys for activation.

     In this configuration, ‘s-j’ and ‘s-k’ both activate Loco to read a
     key sequence and execute the command to which it is bound, but
     ‘s-j’ activates Loco with ‘Control’ pending and ‘s-k’ with ‘Meta’
     pending.

     For purposes of describing a key sequence, ‘C-h s-j’ activates Loco
     with ‘Control’ pending and ‘C-h s-k’ with ‘Meta’ pending.

     Entering key sequences is similar to ‘shift‑return‑jk’,
     ‘control‑return‑jk’, and ‘super‑return‑jk’, but this configuration
     will also strip all modifiers from any key that it reads, similar
     to ‘control‑jk’.

   • ‘control‑cp’

     In this configuration, ‘C-,’ and ‘C-.’ both activate Loco to read a
     key sequence and execute the command to which it is bound, but
     ‘C-,’ activates Loco with ‘Control’ pending and ‘C-.’ with ‘Meta’
     pending.

     For purposes of describing a key sequence, ‘C-h C-,’ activates Loco
     with ‘Control’ pending and ‘C-h C-.’ with ‘Meta’ pending.

     Entering key sequences is similar to ‘shift‑return‑cp’,
     ‘control‑return‑cp’, and ‘super‑return‑cp’, but this configuration
     will also strip all modifiers from any key that it reads, similar
     to ‘control‑jk’ and ‘super-jk’.

   • ‘super‑cp’

     In this configuration, ‘s-,’ and ‘s-.’ both activate Loco to read a
     key sequence and execute the command to which it is bound, but
     ‘s-,’ activates Loco with ‘Control’ pending and ‘s-.’ with ‘Meta’
     pending.

     For purposes of describing a key sequence, ‘C-h s-,’ activates Loco
     with ‘Control’ pending and ‘C-h s-.’ with ‘Meta’ pending.

     Entering key sequences is similar to ‘shift‑return‑cp’,
     ‘control‑return‑cp’, and ‘super‑return‑cp’, but this configuration
     will also strip all modifiers from any key that it reads, similar
     to ‘control‑jk’, ‘super-jk’, and ‘control-cp’.

   • ‘double-tap‑cp’

     Activation keys can avoid modifiers completely, allowing you use
     Loco without using any physical modifier keys.

     In this configuration, ‘,’ and ‘.’ both activate Loco to read a key
     sequence and execute the command to which it is bound, but ‘,’
     activates Loco with ‘Control’ pending and ‘.’ with ‘Meta’ pending.

     For purposes of describing a key sequence, ‘C-h ,’ activates Loco
     with ‘Control’ pending and ‘C-h .’ with ‘Meta’ pending.

     Entering key sequences is similar to ‘shift‑return‑cp’,
     ‘control‑return‑cp’, and ‘super‑return‑cp’, but this configuration
     will also strip all modifiers from any key that it reads, similar
     to ‘control‑jk’, ‘super-jk’, ‘control-cp’, and ‘super-cp’.  It will
     also apply the _double-tap_ rule.

     The effect of setting unmodified ‘,’ and ‘.’ as activation keys is
     significant.  By rebinding them to activation keys, they no longer
     perform their original purpose: to enter a literal comma or period,
     respectively.  Both are essential punctuation, second only to the
     letters and digits in terms of frequency of use.

     The double-tap rule, for this configuration, states that if ‘,’ is
     pressed when ‘Control’ is the _only_ pending modifier, or if ‘.’ is
     pressed when ‘Meta’ is the _only_ pending modifier, clear the
     modifier and add the key _unmodified_ to the key sequence.

     This rule permits ‘,’ and ‘.’ to be entered as ‘, ,’ or ‘. .’,
     respectively.  It is called double-tap because it takes effect when
     these keys are tapped twice in succession (provided no other
     modifiers are in effect).

     Without this rule, entering a literal comma or period would be
     unduly onerous.  For example, here are four alternate ways by which
     you could enter a literal comma or period, respectively:

       1. ‘, m C ,’ or ‘. m M .’

          This method uses the Assist Menu (once), but uses a *note
          persistent key: Persistent keys. to keep the menu open.

       2. ‘, m c m ,’ or ‘. m m m .’

          This method uses the Assist Menu (twice), but does not require
          a physical modifier key.

       3. ‘C-q ,’ or ‘C-q .’

          In Emacs, ‘C-q’ is bound to the command ‘quoted-insert’, which
          will read the next key and insert it.  This method uses
          ‘quoted-insert’, but requires a physical modifier key.

       4. ‘, q ,’ or ‘, q .’

          ‘C-q’ itself can be entered as ‘, q’.  This method uses
          ‘quoted-insert’, but does not require a physical modifier key.

     While the double-tap rule makes entering a literal comma or period
     easy, it does come with a cost.

     Without this rule, ‘, ,’ would be translated to ‘C-,’.  The first
     ‘,’ would tell Loco to consider ‘Control’ as pending, and the
     second ‘,’ would tell Loco to apply ‘Control’ to ‘,’.

     Similarly, ‘. .’ would be translated to ‘M-.’.  The first ‘.’ would
     tell Loco to consider ‘Meta’ as pending, and the second ‘.’ would
     tell Loco to apply ‘Meta’ to ‘.’.

     While ‘C-,’ and ‘M-.’ are less frequently used than literal commas
     and periods (‘C-,’ is not bound to any command and ‘M-.’ is bound
     to ‘xref-find-definition’), we must still be able to enter them.

     Fortunately, we can use the Assist Menu for this.  ‘C-,’ and ‘M-.’
     can be entered as ‘, m ,’ and ‘. m .’, respectively.


File: loco.info,  Node: Summary,  Prev: Details,  Up: Standard configurations

5.4.2 Summary
-------------

Name                  Activate                                            Apply ‘Control’   Apply ‘Meta’   O     E & C S   DT
-------------------------------------------------------------------------------------------------------------------------------
‘shift‑return‑jk’     ‘S‑<return>’                                        ‘j’               ‘k’            ‘l’   ‘;’
‘control‑return‑jk’   ‘C‑<return>’                                        ‘j’               ‘k’            ‘l’   ‘;’
‘super‑return‑jk’     ‘s‑<return>’                                        ‘j’               ‘k’            ‘l’   ‘;’
‘shift‑return‑cp’     ‘S‑<return>’                                        ‘,’               ‘.’            ‘m’   ‘/’
‘control‑return‑cp’   ‘C‑<return>’                                        ‘,’               ‘.’            ‘m’   ‘/’
‘super‑return‑cp’     ‘s‑<return>’                                        ‘,’               ‘.’            ‘m’   ‘/’
‘control‑jk’          ‘C‑j’ and apply ‘Control’, ‘C‑k’ and apply ‘Meta’   ‘j’               ‘k’            ‘l’   ‘;’   ✔︎
‘super‑jk’            ‘s‑j’ and apply ‘Control’, ‘s‑k’ and apply ‘Meta’   ‘j’               ‘k’            ‘l’   ‘;’   ✔︎
‘control‑cp’          ‘C‑,’ and apply ‘Control’, ‘C‑,’ and apply ‘Meta’   ‘,’               ‘.’            ‘m’   ‘/’   ✔︎
‘super‑cp’            ‘s‑,’ and apply ‘Control’, ‘s‑.’ and apply ‘Meta’   ‘,’               ‘.’            ‘m’   ‘/’   ✔︎
‘double‑tap‑cp’       ‘,’ and apply ‘Control’, ‘.’ and apply ‘Meta’       ‘,’               ‘.’            ‘m’   ‘/’   ✔︎   ✔︎

   • O: Open the Assist Menu
   • E & C: Expand & Collapse the Assist Menu
   • S: Strip modifiers
   • DT: Enable the double-tap rule


File: loco.info,  Node: Repeating commands,  Next: Working with physical modifier keys,  Prev: Standard configurations,  Up: Usage

5.5 Repeating commands
======================

One advantage of using physical modifier keys is that once held, the
non-modifier key can be pressed multiple times in sequence to repeat the
command.

Emacs provides a number of ways
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Repeating.html)
to assist with repeating a command, and Loco works well with all of
them.  In particular, using ‘repeat-mode’ to setup groups of commands
that can be repeated by pressing only their last letter is highly
recommended.


File: loco.info,  Node: Working with physical modifier keys,  Next: Considerations when using a terminal,  Prev: Repeating commands,  Up: Usage

5.6 Working with physical modifier keys
=======================================

While Loco aims to replace the need for physical modifier keys, there
may be some cases where you want to use key bindings that use them.
Because Loco does not replace or disable any keymaps, you are able to
use other key bindings as you see fit.

Furthermore, while not necessary, any physical modifier keys you use
while entering key sequences in Loco are properly merged with the set of
pending modifiers.


File: loco.info,  Node: Considerations when using a terminal,  Next: Customization,  Prev: Working with physical modifier keys,  Up: Usage

5.7 Considerations when using a terminal
========================================

In a GUI environment, applications receive key events directly from the
windowing system (https://en.wikipedia.org/wiki/Windowing_system) (for
example, X11, Wayland, or Quartz Compositor).  These systems have
comprehensive support for detecting various key combinations, including
multiple modifiers pressed simultaneously with other keys.  The only
limitation is usually from the operating system itself, which reserves
certain key combinations for its own functions.

Modern terminal applications are typically run within a terminal
emulator (https://en.wikipedia.org/wiki/Terminal_emulator), an
application that itself reserves certain key combinations for its own
functions.  This creates a disparity between the total number of keys
available to the GUI application and the terminal application.

Terminal emulators are designed to mimic the behaviour of older physical
terminals (for example, the VT100
(https://en.wikipedia.org/wiki/VT100)).  Most terminal emulators work by
encoding input into characters or escape sequences that the terminal
application interprets.  This limits how key events are handled by
terminal applications in several ways:

   • The ‘Control’ key is typically limited to modifying these specific
     32 characters: ‘@ A B C D E F G H I J K L M N O P Q R S T U V W X Y
     Z [ \ ] ^ _ ?’.  These characters have ASCII
     (https://en.wikipedia.org/wiki/ASCII) codes of 64 to 95 inclusive.
     When pressed in conjunction with ‘Control’, 64 is subtracted from
     their ASCII code, resulting in a Control Character
     (https://en.wikipedia.org/wiki/Control_character).  This form of
     encoding inherently limits which combinations are possible with
     ‘Control’ and does not work well in conjunction with any other
     modifier key.

   • Other modifier keys, and keys without ASCII equivalents (for
     example, the arrow and function keys), are either encoded as
     character sequences beginning with the ‘ESC’ character or not sent
     to terminal applications at all.  Interpreting these sequences can
     be less reliable, especially for complex combinations involving
     multiple modifiers.

By translating simple key sequences into complex ones, Loco can avoid
the above limitations.

Note that even the default configuration may not work perfectly in all
terminals, as certain terminal emulators will not recognize its
activation key, ‘S-<return>’.  ‘control-jk’ and ‘double-tap-cp’ are the
only standard configurations guaranteed to work in terminals.


File: loco.info,  Node: Customization,  Prev: Considerations when using a terminal,  Up: Usage

5.8 Customization
=================

     Some of this section assumes the reader has basic experience with
     Emacs Lisp
     (https://www.gnu.org/software/emacs/manual/html_node/eintr/).

* Menu:

* Using the "Easy Customization Interface"::
* Mapping Caps Lock to Control::
* Going further::


File: loco.info,  Node: Using the "Easy Customization Interface",  Next: Mapping Caps Lock to Control,  Up: Customization

5.8.1 Using the "Easy Customization Interface"
----------------------------------------------

The Easy Customization Interface
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html)
can be used to customize certain properties of Loco, including its
lighter and its prompts.

     You can also customize properties related to logging, which is
     useful if you are planning on modifying the source code for Loco.
     Logging is not explained in this document; see the source code for
     details.
Some of the properties presented in this interface take S-expressions
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Expressions.html)
as values.  These permit more possibilities for values; for example,
strings styled with custom colours and fonts.

All of the properties presented in this interface can be set using Emacs
Lisp as well.


File: loco.info,  Node: Mapping Caps Lock to Control,  Next: Going further,  Prev: Using the "Easy Customization Interface",  Up: Customization

5.8.2 Mapping Caps Lock to Control
----------------------------------

‘S-<return>’ is easy to press, but it would be easier still to be able
to activate Loco with a physical modifier key located right on the home
row.  If this physical modifier key were ‘Control’, you would also have
quick access to some very common Emacs key bindings without use of Loco.
For example, ‘C-n’ and ‘C-p’.

‘Caps Lock’, located to the left of ‘a’ on a QWERTY keyboard, is a
rarely-used key in a prime location.  As such, it is common to remap
this key to ‘Control’.

For most operating systems, there is both built-in support and
third-party tools available to remap keys.

For example, on MacOS, where keys are not easily remapped system-wide,
mapping ‘Caps Lock’ to ‘Control’ is possible without third-party tools:

   • In _System Preferences > Keyboard > Keyboard Shortcuts...  >
     Modifier Keys_, change _Caps Lock key_ to _Control_.

   • (Optional) You may also want to change _Control key_ to _Caps
     Lock_, effectively swapping the behaviour of the two keys, to
     ensure you still have a means to toggle ‘Caps Lock’ if desired.

   • (Optional) If you use multiple keyboards, ensure that you change
     these settings for each keyboard appropriately by selecting each
     keyboard in turn at the top of the dialog box.

   • Press _Done_ when complete.


File: loco.info,  Node: Going further,  Prev: Mapping Caps Lock to Control,  Up: Customization

5.8.3 Going further
-------------------

With only a few lines of code, you can specify the key sequences to
enable, disable, and activate Loco, as well as the set of keys and
behaviours for entering key sequences.

See the commands ‘loco-set-standard-configuration’ and
‘loco-unset-default-configuration’ in the source code to understand how
key sequences are bound and unbound, respectively, to enable, disble,
and activate Loco for each standard configuration (including the default
configuration).

See the command ‘loco-read-kseq’ in the source code to understand how
the set of keys and behaviours are specified for entering key sequences.
Note that all standard configurations ultimately call this one command.
It accepts many keyword arguments, all of which are explained in the
documentation for that command.


File: loco.info,  Node: Author and copyright,  Next: License,  Prev: Usage,  Up: Top

6 Author and copyright
**********************

This project was written and copyrighted in 2024 by Chris McLaren
(@csmclaren (https://www.github.com/csmclaren)).


File: loco.info,  Node: License,  Next: Colophon,  Prev: Author and copyright,  Up: Top

7 License
*********

Unless otherwise noted, all files in this project are licensed under the
GNU (https://www.gnu.org) General Public License v3.0.  See the COPYING
(/COPYING) file for details.


File: loco.info,  Node: Colophon,  Prev: License,  Up: Top

8 Colophon
**********

The logo for Loco is a representation of a tram
(https://en.wikipedia.org/wiki/Tram) car from the Unicode
(https://home.unicode.org) chart Transport and Map Symbols
(https://unicode.org/charts/PDF/U1F680.pdf).  Loco was created in
Lisbon, Portugal, a city with a history
(https://en.wikipedia.org/wiki/Trams_in_Lisbon) of using tram cars such
as these.


Tag Table:
Node: Top188
Node: Table of contents494
Node: Introduction2595
Node: Examples using the default configuration4960
Node: Installation6113
Node: From MELPA6275
Node: From source7539
Node: Background8597
Node: Keys key sequences and commands8779
Node: How Loco is different10493
Node: Usage11431
Node: Enabling and disabling Loco11785
Node: The default configuration13858
Node: Activating Loco14232
Node: Entering key sequences14948
Node: Normal operation ie when the Assist Menu is closed17610
Node: Assisted operation ie when the Assist Menu is open18906
Node: Rock and roll20458
Node: Persistent keys21243
Node: Typical key sequences and their translations22104
Node: More difficult key sequences and their translations22895
Node: Describing commands24220
Node: Standard configurations25045
Node: Details25926
Node: Summary36733
Node: Repeating commands38979
Node: Working with physical modifier keys39641
Node: Considerations when using a terminal40279
Node: Customization43054
Node: Using the "Easy Customization Interface"43450
Node: Mapping Caps Lock to Control44456
Node: Going further46008
Node: Author and copyright46938
Node: License47189
Node: Colophon47476

End Tag Table


Local Variables:
coding: utf-8
End:
