[dactyl.git] / common / locale / en-US / map.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>

<!DOCTYPE document SYSTEM "dactyl://content/dtd">

<document
    name="map"
    title="&dactyl.appName; Key Mappings"
    xmlns="&xmlns.dactyl;"
    xmlns:dactyl="&xmlns.dactyl;"
    xmlns:html="&xmlns.html;">

<h1 tag="keyboard-shortcuts">Keyboard shortcuts and commands</h1>
<toc start="2"/>

<p>
    &dactyl.appName; provides a number of commands to change the
    behavior of key presses. This can mean anything from
    automatically substituting one key for another or automatically
    replacing one typed word for another, to launching a dialog or
    running a command.
</p>

<h2 tag="key-mapping mapping map macro">Key mapping</h2>

<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
    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
    variants. These commands, in essence, allow the user to quickly
    substitute one sequence of key presses for another.
    For instance,
</p>

<code><ex>:map <k name="F2" link="false"/></ex> <ex>:echo Date()<k name="CR"/></ex></code>

<p>
    causes “<ex>:echo Date()<k name="CR"/></ex>” to be typed out
    whenever <k name="F2" link="false"/> is pressed, thus echoing the full date
    to the command line.
</p>

<p tag=":map-modes">
    Standard key mapping commands are provided for the five most
    common modes,
</p>

<dl dt="width: 8em;">
    <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>
</dl>

<p>
    The ordinary <ex>:map</ex> and <ex>:noremap</ex> commands
    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.
    Other modes can be specified using the -modes option described below.
</p>

<warning>
    It is important to note that mappings are <em>not</em>
    automatically saved between sessions. In order to preserve them,
    they must either be added to your <tt><t>&dactyl.name;rc</t></tt> or
    saved via the <ex>:mk&dactyl.name;rc</ex> command.
</warning>

<h3 tag=":map-commands">Map commands</h3>

<item>
    <tags>:map</tags>
    <spec>:map <a>lhs</a> <a>rhs</a></spec>
    <tags>:nm :nmap</tags>
    <spec>:nm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:vm :vmap</tags>
    <spec>:vm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:im :imap</tags>
    <spec>:im<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:tm :tmap</tags>
    <spec>:tm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:cm :cmap</tags>
    <spec>:cm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <description>
        <p>
            Map the <t>key-sequence</t> <a>lhs</a> to <a>rhs</a> for
            the applicable mode(s). The keys of <a>rhs</a> respect
            user-defined mappings, so the following will result in
            an infinite loop,
        </p>
        <code><ex>:map a b</ex>
<ex>:map b a</ex></code>
        <p>
            In order to avoid this shortcoming, the <ex>:noremap</ex> command
            or the <em>-builtin</em> option may be used.
        </p>
    </description>
</item>

<h3 tag=":map-options">Map options</h3>
<p>
    Any of the map commands may be given the following options:
</p>

<dl dt="width: 12em;">
    <dt></dt> <dd></dd>

    <dt>-arg</dt> <dd>Accept an argument after the requisite key press. Sets the <tt>arg</tt> parameter to the result. (short name <em>-a</em>)</dd>
    <dt>-builtin</dt> <dd>Execute this mapping as if there were no user-defined mappings (short name <em>-b</em>)</dd>
    <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>-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>-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>&lt;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>:ino :inoremap</tags>
    <spec>:ino<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:tno :tnoremap</tags>
    <spec>:tno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:cno :cnoremap</tags>
    <spec>:cno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <description>
        <p>
            Map the <t>key-sequence</t> <a>lhs</a> to <a>rhs</a> for
            the applicable mode(s). The keys in <a>rhs</a> do not
            respect user-defined key mappings, so the following
            effectively reverses the default meanings of the keys
            <k>d</k> and <k>D</k>
        </p>
        <code><ex>:noremap d D</ex>
<ex>:noremap D d</ex></code>
    </description>
</item>

<item>
    <spec>:unmap <a>lhs</a></spec>
    <tags>:unm :unmap</tags>
    <spec>:unmap!</spec>
    <spec>:nun<oa>map</oa> <a>lhs</a></spec>
    <tags>:nun :nunmap</tags>
    <spec>:nun<oa>map</oa>!</spec>
    <spec>:vun<oa>map</oa> <a>lhs</a></spec>
    <tags>:vun :vunmap</tags>
    <spec>:vun<oa>map</oa>!</spec>
    <spec>:iu<oa>nmap</oa> <a>lhs</a></spec>
    <tags>:iu :iunmap</tags>
    <spec>:iu<oa>nmap</oa>!</spec>
    <spec>:tu<oa>nmap</oa> <a>lhs</a></spec>
    <tags>:tu :tunmap</tags>
    <spec>:tu<oa>nmap</oa>!</spec>
    <spec>:cu<oa>nmap</oa> <a>lhs</a></spec>
    <tags>:cu :cunmap</tags>
    <spec>:cu<oa>nmap</oa>!</spec>
    <description>
        <p>Remove the mapping of <a>lhs</a> (or all mappings if <oa>!</oa> is
            given) for the applicable mode(s).</p>
    </description>
</item>

<item>
    <spec>:map</spec>
    <spec>:nm<oa>ap</oa></spec>
    <spec>:vm<oa>ap</oa></spec>
    <spec>:im<oa>ap</oa></spec>
    <spec>:tm<oa>ap</oa></spec>
    <spec>:cm<oa>ap</oa></spec>
    <description>
        <p>
            List all mappings for the applicable mode(s). Mappings are
            partitioned into <t>groups</t>.
        </p>
    </description>
</item>

<item>
    <tags>:map_l</tags>
    <spec>:map <a>lhs</a></spec>
    <tags>:nmap_l</tags>
    <spec>:nm<oa>ap</oa> <a>lhs</a></spec>
    <tags>:vmap_l</tags>
    <spec>:vm<oa>ap</oa> <a>lhs</a></spec>
    <tags>:imap_l</tags>
    <spec>:im<oa>ap</oa> <a>lhs</a></spec>
    <tags>:tmap_l</tags>
    <spec>:tm<oa>ap</oa> <a>lhs</a></spec>
    <tags>:cmap_l</tags>
    <spec>:cm<oa>ap</oa> <a>lhs</a></spec>
    <description>
        <p>List all mappings starting with <a>lhs</a> for the applicable mode(s).</p>
    </description>
</item>

<h3 tag=":map-timeout map-timeout">Mapping timeout</h3>
<p>
    When &dactyl.appName; receives a key event that has a separate binding and
    at the same time is part of a key chain, values of the <o>timeout</o> and
    <o>timeoutlen</o> options are used to decide what to do. See the
    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>
    Most keys in key sequences are represented simply by the
    character that you see on the screen when you type them.
    However, as a number of these characters have special meanings,
    and a number of keys have no visual representation, a special
    notation is required.
</p>

<ul>
    <li>
        The first argument to the <ex>:map</ex> commands must be
        <link topic="quoting">quoted</link> if it contains spaces,
        quotation marks or back-slashes. A space may additionally be
        typed as <k name="Space"/>.
    </li>
    <li key="&lt;lt>">
        As special key names start with the <em>&lt;</em> character,
        a literal &lt; must be typed as <k name="lt" link="false"/>.
    </li>
    <li>
        <k name="Left"/>, <k name="Right"/>, <k name="Up"/>,
        and <k name="Down"/> represent the standard arrow keys.
    </li>
    <li>
        <k name="CapsLock" link="false"/>, <k name="NumLock" link="false"/>, <k name="Insert"/>
        <k name="Del" link="false"/>, <k name="Tab"/>, <k name="PageUp"/>,
        <k name="PageDown"/>, and <k name="Esc"/> work as
        expected.
   </li>
    <li>
        <k name="Return" link="false"/> or <k name="CR"/> represent the carriage
        return key.
    </li>
    <li><k name="BS" link="false"/> represents the backspace key.</li>
    <li><k name="F1"/> through <k name="F12" link="false"/> work as expected.</li>
    <li>
        <k name="K0" link="false"/> through <k name="K9" link="false"/> represent keys on the
        numeric keypad.
    </li>
    <li>
        <k name="Uxxxx" link="false"/>, where <em>xxxx</em> is any 4 hexadecimal
        digits, represents the character at that Unicode codepoint.
        For instance, <k name="U263a" link="false"/> represents ☺.
    </li>
</ul>

<p>
    In order to represent key presses using the Control, Alt, Meta,
    or Shift keys, the following prefixes may be used,
</p>

<ol>
    <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="S-␣" link="false"/>: The shift key.</li>
</ol>

<p>
    These prefixes can be combined however you see fit.
</p>

<note>
    Within angle brackets all alphabetic characters are read as lowercase.
    Uppercase characters can only be specified with the <em>S-</em> modifier.
</note>

<p>
    The following key sequences are interpreted as described:
</p>

<dl dt="width: 10em;">
    <dt><k link="false">xc</k></dt>
    <dd>Type 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
        by the ‘C’ key.
    </dd>

    <dt><k name="C-2" link="false"/></dt>
    <dd>Type the ‘2’ while holding the ‘Control’ key.</dd>

    <dt><k name="C-@" link="false"/></dt>
    <dd>Type 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>

    <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>
</dl>

<h3 tag=":map-special-chars">Special characters</h3>

<item>
    <tags><![CDATA[<Nop>]]></tags>
    <strut/>
    <spec><![CDATA[<Nop>]]></spec>
    <description>
        <p>
            Do nothing. This pseudo-key is useful for disabling a
            specific builtin mapping. For example,
            <ex>:map <k name="C-n"/> <k name="Nop"/></ex> will prevent <k name="C-n"/>
            from doing anything.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<Pass>]]></tags>
    <spec><![CDATA[<Pass>]]></spec>
    <description short="true">
        <p>
            Pass the events consumed by the last executed mapping through to &dactyl.host;.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<CR> map_return]]></tags>
    <strut/>
    <spec><![CDATA[<CR>]]></spec>
    <description>
        <p>
            Expand to a line terminator in a key mapping. An Ex command in the <a>rhs</a> of a
            mapping requires a line terminator after it so that it is executed when the
            mapping is expanded. <k name="CR"/> should be used for this purpose.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<Leader> \]]></tags>
    <strut/>
    <spec><![CDATA[<Leader>]]></spec>
    <description>
        <p>
            A pseudo-key which expands to the value of the <o>mapleader</o>
            option. For example, by default,
        </p>
        <code><ex>:map <k name="Leader"/>h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
        <p>works like</p>
        <code><ex>:map \h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
        <p>but after</p>
        <set opt="mapleader"><str>,</str></set>
        <p>it works like</p>
        <code><ex>:map ,h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
    </description>
</item>

<h2 tag="abbreviations">Abbreviations</h2>

<p>
    In addition to basic mappings, &dactyl.appName; can also
    automatically replace whole words after they've been typed.
    These shortcuts are known as abbreviations, and are most often
    useful for correcting spelling of commonly mistyped words, as
    well as shortening the typing of oft-typed but long words or
    phrases. There are three basic types of abbreviations, defined
    by the types of characters they contain,
</p>

<ul>
    <li>‘full-id’ abbreviations consist entirely of keyword characters (e.g., ‘teh’, ‘msoft’).</li>
    <li>‘end-id’ abbreviations end in keyword character but otherwise contains all non-keyword characters (e.g., ‘'i’).</li>
    <li>‘non-id’ abbreviations end in a non-keyword character but otherwise contains any non-whitespace character (e.g., ‘def'’).</li>
    <li>Strings which fit none of the above patterns can not be defined as abbreviations (e.g., ‘a'b’ and ‘a b’).</li>
</ul>

<p>
    For the purposes of abbreviations, keyword characters include
    all non-whitespace characters except for single or double
    quotation marks. Abbreviations are expanded as soon as any
    non-keyword character, or the key <k name="C-]" mode="c"/>, is typed.
</p>

<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> <a>lhs</a></spec>
    <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa></spec>
    <description>
        <p>
            Abbreviate <a>lhs</a> to <a>rhs</a>. If only <a>lhs</a>
            is given, list all abbreviations that start with
            <a>lhs</a>. If no arguments are given, list all
            abbreviations.
        </p>

        <p>
            If the <em>-javascript</em> (short names <em>-js</em>,
            <em>-j</em>) option is given, <a>lhs</a> is expanded to
            the value <em>return</em>ed by the JavaScript code
            <a>rhs</a>. The code is evaluated with the variable
            <em>editor</em> set to the editable element that the
            abbreviation is currently being expanded in. The code
            should <em>not</em> make any changes to the contents of
            the editor.
        </p>

        <p>
            If <a>group</a> is specified then abbreviations are created or
            listed for the given <t>group</t>.
        </p>
    </description>
</item>

<item>
    <tags>:ca :cabbreviate</tags>
    <spec>:ca<oa>bbreviate</oa> <a>lhs</a> <a>rhs</a></spec>
    <spec>:ca<oa>bbreviate</oa> <a>lhs</a></spec>
    <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.
        </p>
    </description>
</item>

<item>
    <tags>:ia :iabbreviate</tags>
    <spec>:ia<oa>bbreviate</oa> <a>lhs</a> <a>rhs</a></spec>
    <spec>:ia<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:ia<oa>bbreviate</oa></spec>
    <description>
        <p>
            Abbreviate a key sequence for Insert mode. Same as
            <ex>:ab<oa>breviate</oa></ex>, but for insert mode only.
        </p>
    </description>
</item>

<item>
    <tags>:una :unabbreviate</tags>
    <spec>:una<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:una<oa>bbreviate</oa>!</spec>
    <description>
        <p>Remove an abbreviation. With <oa>!</oa>, remove all abbreviations.</p>
    </description>
</item>

<item>
    <tags>:cuna :cunabbreviate</tags>
    <spec>:cuna<oa>bbreviate</oa> <a>lhs</a></spec>
    <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.
        </p>
    </description>
</item>

<item>
    <tags>:iuna :iunabbreviate</tags>
    <spec>:iuna<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:iuna<oa>bbreviate</oa>!</spec>
    <description>
        <p>
            Remove abbreviation(s) for Insert mode. Same as
            <ex>:una<oa>bbreviate</oa></ex> but for Insert mode
            only.
        </p>
    </description>
</item>

<h2 tag="user-commands">User-defined commands</h2>

<p>
    Defining new commands is perhaps the most straightforward way of
    repeating commonly used actions. User-defined commands may be
    entered from the command line or scripts exactly like standard
    commands, and may similarly accept arguments, options, counts,
    and <oa>!</oa>s, as well as provide command-line completion.
    These commands may be defined as either ordinary,
    macro-interpolated Ex commands, or otherwise as plain
    JavaScript statements.
</p>

<item>
    <tags>:com :command</tags>
    <spec>:com<oa>mand</oa></spec>
    <description short="true">
        <p>List all user-defined commands.</p>
    </description>
</item>

<item>
    <spec>:com<oa>mand</oa> <oa>cmd</oa></spec>
    <description>
        <p>
            List all user-defined commands that start with <oa>cmd</oa>. Commands
            are partitioned into <t>groups</t>.
        </p>
    </description>
</item>

<item>
    <spec>:com<oa>mand</oa><oa>!</oa> <oa><a>options</a>…</oa> <a>cmd</a> <a>rep</a></spec>
    <description>
        <p>
            Define a new user command. The name of the command is
            <a>cmd</a> and its replacement text is <a>rep</a>. If a
            command with this name already exists, an error is
            reported unless <oa>!</oa> is specified, in which case
            the command is redefined. Unlike Vim, the command may
            start with a lowercase letter. <a>cmd</a> may also be multiple
            alternative command names separated by commas.
        </p>

        <p>
            The new command is usually defined by a string to be
            executed as an Ex command. In this case, before
            execution, strings of the form
            <hl key="HelpKey">&lt;<a>var</a>></hl> are interpolated
            as described below, in order to insert arguments,
            options, and the like. If the <em>-javascript</em> (short
            name <em>-js</em>) flag is present, the command is
            executed as JavaScript, and the arguments are present as
            variables in its scope instead, and no interpolation is
            performed.
        </p>

        <p>
            The command's behavior can be altered by providing
            options when the command is defined.
        </p>

        <h3 tag=":command-group">Grouping</h3>

        <p>
            The <em>-group</em> flag (short name: <em>-g</em>) can be used to
            assign this command to a specific <t>group</t>.
        </p>

        <h3 tag="E175 E176 :command-nargs">Argument handling</h3>

        <p>
            By default, user commands accept no arguments. This can be changed by specifying
            the <tt>-nargs</tt> option.
        </p>

        <p>The valid values are:</p>

        <dl>
            <dt>-nargs=0</dt><dd>No arguments are allowed (default)</dd>
            <dt>-nargs=1</dt><dd>One argument is allowed</dd>
            <dt>-nargs=*</dt><dd>Zero or more arguments are allowed</dd>
            <dt>-nargs=?</dt><dd>Zero or one argument is allowed</dd>
            <dt>-nargs=+</dt><dd>One or more arguments are allowed</dd>
        </dl>

        <h3 tag="E180 E181 :command-complete">Argument completion</h3>

        <p>
            Completion for arguments to user-defined commands is not available by default.
            Completion can be enabled by specifying one of the following arguments to the
            -complete option when defining the command.
        </p>

        <dl tag=":command-complete-arg-list"/>

        <h3 tag="E467 E468 :command-completion-custom">Custom completion</h3>

        <p>
            Custom completion can be provided by specifying the
            <str>custom,<a>thing</a></str> argument to <tt>-complete</tt>. If
            <a>thing</a> evaluates to a function (i.e., it is a variable holding
            a function value, or a string containing the definition itself), it
            is called with two arguments: a completion context, and an object
            describing the command's arguments. It should set the context's
            <tt>completions</tt> property to the list of completion results.
            Other influential properties include <tt>title</tt>, <tt>sort</tt>,
            <tt>anchored</tt>, and <tt>filters</tt>, which are documented in the
            <link topic="resource://dactyl/completion.jsm"
                line="17" dactyl:command="buffer.viewSource">source code</link>.
        </p>

        <p>
            <em>completions</em> is a two-dimensional array of the form:
            <tt>[[arg1, description1], [arg2, description2], …]</tt>
        </p>

        <p>
            Otherwise <a>thing</a> should evaluate to an array of the same form
            as the <tt>completions</tt> property of the context object.
        </p>

        <p>
            Example:
            <code><ex>:command foo -nargs=? -complete custom,<str delim="'">
    \ function (context) context.completions = [["arg1", "description1"], ["arg2", "description2"]]</str>
    \ <ex>:echo</ex> <str>Useless </str> + <em>&lt;q-args></em></ex>

<ex>:command foo -nargs=?
    \ -complete custom,<str delim="'">[["arg1", "description1"], ["arg2, "description2"]]</str>
    \ <ex>:echo</ex> <str>Same as above but simpler </str> + <em>&lt;q-args></em></ex></code>
        </p>

        <h3 tag="E177 E178 :command-count">Count handling</h3>

        <p>
            By default, user commands do not accept a count. Use the -count option if
            you'd like to have a count passed to your user command. This will then be
            available for expansion as &lt;count> in the replacement.
        </p>

        <h3 tag=":command-bang">Special cases</h3>

        <p>
            By default, a user command does not have a special version, i.e. a version
            executed with the ! modifier. Providing the -bang option will enable this
            and &lt;bang> will be available in the replacement.
        </p>

        <h3 tag=":command-description">Command description</h3>

        <p>
            The command's description text can be set with -description. Otherwise it will
            default to "User-defined command".
        </p>

        <h3 tag=":command-replacement-text">Replacement text</h3>

        <p>
            The replacement text <a>rep</a> is scanned for <t>macro-string</t>s and these are
            replaced with values from the user-entered command line. The resulting string
            is then executed as an Ex command.
        </p>

        <p>
            In addition to the standard parameters listed in
            <t>macro-string</t>, the following parameters are available:
        </p>

        <dl>
            <dt>&lt;args></dt> <dd>The command arguments exactly as supplied</dd>
            <dt>&lt;count></dt><dd>Any supplied count, e.g. 5</dd>
            <dt>&lt;bang></dt> <dd>! if the command was executed with the ! modifier</dd>
        </dl>
    </description>
</item>

<item>
    <tags>:delc :delcommand</tags>
    <spec>:delc<oa>ommand</oa> <a>cmd</a></spec>
    <spec>:delc<oa>ommand</oa>!</spec>
    <description>
        <p>Delete the user-defined command <a>cmd</a>. With <oa>!</oa>, delete
            all user commands.</p>
    </description>
</item>

<h2 tag="command-examples">Examples</h2>

<p>Add a :Google command to search via google:</p>
<code><ex>:command -nargs=* Google open google &lt;args></ex></code>

<!-- TODO: add decent examples -->

</document>

<!-- vim:se sts=4 sw=4 et: -->