<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
-<!DOCTYPE document SYSTEM "dactyl://content/dtd">
+<!DOCTYPE document SYSTEM "dactyl://content/modes.dtd">
<document
name="map"
<p>
Key mappings are the most basic means &dactyl.appName; provides
for altering the actions of key presses. Each key mapping is
- associated with a mode, such as <link topic="insert-mode">insert</link>,
- <link>normal</link>, or
- <link topic="command-line-mode">command-line</link>, and only
+ associated with a mode, such as <link topic="insert-mode">Insert</link>,
+ <link>Normal</link>, or
+ <link topic="command-line-mode">Command Line</link>, and only
has effect when that mode is active. Although each mode has a
full suite of internal mappings, they may be easily augmented,
altered, or removed with the <ex>:map</ex> command and its
<dt>n</dt> <dd>Normal mode: When browsing normally</dd>
<dt>v</dt> <dd>Visual mode: When selecting text with the cursor keys</dd>
<dt>i</dt> <dd>Insert mode: When interacting with text fields on a website</dd>
- <dt>t</dt> <dd>TextEdit mode: When editing text fields in Vim-like NORMAL mode</dd>
- <dt>c</dt> <dd>Command-line mode: When typing into the &dactyl.appName; command line</dd>
+ <dt>t</dt> <dd>Text Edit mode: When editing text fields in Vim-like Normal mode</dd>
+ <dt>c</dt> <dd>Command Line mode: When typing into the &dactyl.appName; command line</dd>
</dl>
<p>
The ordinary <ex>:map</ex> and <ex>:noremap</ex> commands
- add mappings for normal and visual mode. In order to map key
+ add mappings for Normal and Visual mode. In order to map key
bindings in a different mode, any of the mapping commands may be
prefixed with one of the above letters. For instance,
- <ex>:imap</ex> creates a new key mapping in insert mode, while
- <ex>:cunmap</ex> removes a key mapping from command-line mode.
+ <ex>:imap</ex> creates a new key mapping in Insert mode, while
+ <ex>:cunmap</ex> removes a key mapping from Command Line mode.
Other modes can be specified using the -modes option described below.
</p>
saved via the <ex>:mk&dactyl.name;rc</ex> command.
</warning>
+<p tag="modes">
+ The following tree represents all of the modes understood by
+ dactyl. Mappings for a mode also apply to its children and
+ descendants. So a mapping in the Base mode, for instance, is
+ also active in Normal and Ex mode.
+</p>
+
+&modes.tree;
+
<h3 tag=":map-commands">Map commands</h3>
<item>
</description>
</item>
+<p tag=":map-overview">
+ Below is an overview of which modes each map command applies to:
+</p>
+
+<dl dt="width: 20em;">
+ <dt>:map :noremap :unmap</dt> <dd>Normal and Visual modes</dd>
+ <dt>:nmap :nnoremap :nunmap</dt> <dd>Normal mode</dd>
+ <dt>:vmap :vnoremap :vunmap</dt> <dd>Visual mode</dd>
+ <dt>:imap :inoremap :iunmap</dt> <dd>Insert mode</dd>
+ <dt>:tmap :tnoremap :tunmap</dt> <dd>Text Edit mode</dd>
+ <dt>:cmap :cnoremap :cunmap</dt> <dd>Command Line mode</dd>
+</dl>
+
+<note>
+ The <em>-modes</em> option, described below, provides a more flexible way
+ to specify the applicable modes.
+</note>
+
<h3 tag=":map-options">Map options</h3>
<p>
Any of the map commands may be given the following options:
<dt>-count</dt> <dd>Accept a count before the requisite key press. Sets the <tt>count</tt> parameter to the result. (short name <em>-c</em>)</dd>
<dt>-description</dt> <dd>A description of this mapping (short name <em>-d</em>)</dd>
<dt>-ex</dt> <dd>Execute <a>rhs</a> as an Ex command rather than keys (short name <em>-e</em>)</dd>
- <dt>-group=<a>group</a></dt> <dd>Add this command to the given <t>group</t> (short name <em>-g</em>)</dd>
+ <dt>-group=<a>group</a></dt> <dd>Add this command to the given <t>group</t> (short name <em>-g</em>). When listing commands this limits the output to the specified group.</dd>
<dt>-javascript</dt> <dd>Execute <a>rhs</a> as JavaScript rather than keys (short names <em>-js</em>, <em>-j</em>)</dd>
<dt>-literal=<a>n</a></dt> <dd>Parse the <a>n</a>th argument without specially processing any quote or meta characters. (short name <em>-l</em>)</dd>
- <dt>-modes</dt> <dd>Create this mapping in the given modes (short names <em>-mode</em>, <em>-m</em>)</dd>
+ <dt>-modes=<a>modes</a></dt> <dd>Create this mapping in the given modes (short names <em>-mode</em>, <em>-m</em>)</dd>
<dt>-nopersist</dt> <dd>Do not save this mapping to an auto-generated rc file (short name <em>-n</em>)</dd>
<dt>-silent</dt> <dd>Do not echo any generated keys to the command line (short name <em>-s</em>, also <em><silent></em> for Vim compatibility)</dd>
</dl>
<item>
<tags>:no :noremap</tags>
<spec>:no<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
- <tags>:nn :nnoremap</tags>
- <spec>:nn
<oa>oremap</oa> <a>lhs</a> <a>rhs</a></spec>
- <tags>:vn :vnoremap</tags>
- <spec>:vn
<oa>oremap</oa> <a>lhs</a> <a>rhs</a></spec>
+ <tags>:nno :nnoremap</tags>
+ <spec>:nn
o<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
+ <tags>:vno :vnoremap</tags>
+ <spec>:vn
o<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
<tags>:ino :inoremap</tags>
<spec>:ino<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
<tags>:tno :tnoremap</tags>
documentation of those options for more information.
</p>
-<h3 tag=":map-arguments">Special arguments</h3>
-
-<p>
- Below is an overview of which modes each map command applies to:
-</p>
-
-<!-- TODO: table format -->
-
-<code>
-:map :noremap :unmap :mapclear – both Normal and Visual modes
-:nmap :nnoremap :nunmap :nmapclear – Normal mode
-:vmap :vnoremap :vunmap :vmapclear – Visual mode
-:imap :inoremap :iunmap :imapclear – Insert mode
-:tmap :tnoremap :tunmap :tmapclear – Text Edit mode
-:cmap :cnoremap :cunmap :cmapclear – Command-line mode
-</code>
-
<h3 tag="key-notation key-sequence">Key sequences</h3>
<p>
<li><k name="C-␣" link="false"/>: The control or ctrl key.</li>
<li><k name="A-␣" link="false"/>: The alt key.</li>
<li><k name="M-␣" link="false"/>: The meta key, windows key, or command key.</li>
+ <li><k name="⌘-␣" link="false"/>: Same as <k name="M-␣" link="false"/>.</li>
<li><k name="S-␣" link="false"/>: The shift key.</li>
</ol>
<dl dt="width: 10em;">
<dt><k link="false">xc</k></dt>
- <dd>Type the ‘X’ key followed by the ‘C’ key.</dd>
+ <dd>Press the ‘X’ key followed by the ‘C’ key.</dd>
<dt><k name="C-x" link="false">c</k></dt>
<dd>
- Type the ‘X’ key while holding the ‘Control’ key, followed
+ Press the ‘X’ key while holding the ‘Control’ key, followed
by the ‘C’ key.
</dd>
<dt><k name="C-2" link="false"/></dt>
- <dd>Type the ‘2’ while holding the ‘Control’ key.</dd>
+ <dd>Type ‘2’ while holding the ‘Control’ key.</dd>
<dt><k name="C-@" link="false"/></dt>
- <dd>Type the ‘@’ key while holding the ‘Control’ key.</dd>
+ <dd>Press the ‘@’ key while holding the ‘Control’ key.</dd>
<dt><k name="S-Space" link="false"/></dt>
<dd>Press the space bar while holding the ‘Shift’ key.</dd>
<dt><k name="C-A-j" link="false"/></dt>
- <dd>Type the ‘J’ key while while holding both the ‘Control’ and ‘Alt’ keys.</dd>
+ <dd>Press the ‘J’ key while holding both the ‘Control’ and ‘Alt’ keys.</dd>
<dt><k name="C-A-J" link="false"/></dt>
<dd>Exactly the same as above.</dd>
<dt><k name="C-A-S-j" link="false"/></dt>
- <dd>Type the ‘J’ key while while holding both the ‘Control’, ‘Alt’, and ‘Shift’ keys.</dd>
+ <dd>Press the ‘J’ key while holding all of ‘Control’, ‘Alt’, and ‘Shift’ keys.</dd>
</dl>
<h3 tag=":map-special-chars">Special characters</h3>
<item>
<tags>:ab :abbreviate</tags>
- <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa> <a>lhs</a> <a>rhs</a></spec>
+ <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa> <
oa>-js</oa> <a>lhs</a> <a>rhs</a></spec>
<spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa> <a>lhs</a></spec>
<spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa></spec>
<description>
<spec>:ca<oa>bbreviate</oa></spec>
<description>
<p>
- Abbreviate a key sequence for Command-line mode. Same as
- <ex>:ab<oa>breviate</oa></ex>, but for
- <t>command-line</t> mode only.
+ Abbreviate a key sequence for Command Line mode. Same as
+ <ex>:ab<oa>breviate</oa></ex>, but for &mode.command-line; mode
+ only.
</p>
</description>
</item>
<description>
<p>
Abbreviate a key sequence for Insert mode. Same as
- <ex>:ab<oa>breviate</oa></ex>, but for insert mode only.
+ <ex>:ab<oa>breviate</oa></ex>, but for Insert mode only.
</p>
</description>
</item>
<spec>:cuna<oa>bbreviate</oa>!</spec>
<description>
<p>
- Remove abbreviation(s) for Command-line mode. Same as
- <ex>:una<oa>bbreviate</oa></ex>, but for
- <t>command-line</t> mode only.
+ Remove abbreviation(s) for Command Line mode. Same as
+ <ex>:una<oa>bbreviate</oa></ex>, but for &mode.command-line; mode
+ only.
</p>
</description>
</item>
<p>
The <em>-group</em> flag (short name: <em>-g</em>) can be used to
- assign this command to a specific <t>group</t>.
+ assign this command to a specific <t>group</t>. When listing
+ commands this limits the output to the specified group.
</p>
<h3 tag="E175 E176 :command-nargs">Argument handling</h3>
<p>
<em>completions</em> is a two-dimensional array of the form:
- <tt>[[arg1, description1], [arg2, description2], …]</tt>
+ <tt>[[val1, description1], [val2, description2], …]</tt>
</p>
<p>
<p>
Example:
<code><ex>:command foo -nargs=? -complete custom,<str delim="'">
- \ function (context) context.completions = [["arg1", "description1"], ["arg2", "description2"]]</str>
+ \ function (context) context.completions = [["val1", "description1"], ["val2", "description2"]]</str>
\ <ex>:echo</ex> <str>Useless </str> + <em><q-args></em></ex>
<ex>:command foo -nargs=?
- \ -complete custom,<str delim="'">[["arg1", "description1"], ["arg2, "description2"]]</str>
+ \ -complete custom,<str delim="'">[["val1", "description1"], ["val2", "description2"]]</str>
\ <ex>:echo</ex> <str>Same as above but simpler </str> + <em><q-args></em></ex></code>
</p>
projects / dactyl.git / blobdiff