path: root/common/locale/en-US/cmdline.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="cmdline"
    title="&dactyl.appName; Command-line"
    xmlns="&xmlns.dactyl;"
    xmlns:html="&xmlns.html;">

<h1 tag="command-line-mode command-line mode-cmdline">Command Line mode</h1>
<toc start="2"/>

<p>
    &dactyl.appName;'s Command Line mode is perhaps its most
    powerful interface. In this mode, the command input bar at the
    bottom of the window is given the keyboard focus for any of a
    variety of required inputs. In addition to access to almost
    every aspect of &dactyl.appName; and &dactyl.host;, the command
    line provides power and comprehensive completion for all of its
    commands, along with concise descriptions for each command and
    all of its arguments. Couple this with persistent, searchable
    command history, and you have a very efficient interface for
    easily performing simple and complex tasks.
</p>

<p>
    Included among the several command-line modes are Ex command
    mode (the standard mode for entering commands), Find mode (for
    searching the current page), Prompt mode (for selecting files,
    confirming actions), and Hints mode (for selecting links and
    other items on a page).
</p>

<item>
    <tags>:</tags>
    <strut/>
    <spec>:</spec>
    <description>
        <p>
            Opens the command line in Ex mode. This is the mode used
            for entering the various commands listed in
            <t>ex-cmd-index</t>.
        </p>
    </description>
</item>

<h2 tag="cmdline-editing">Command-line editing</h2>

<item>
    <tags><![CDATA[c_<C-i>]]></tags>
    <spec>&lt;C-i></spec>
    <description short="true">
        <p>Launch the external editor. See the <o>editor</o> option.</p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<C-c>]]></tags>
    <spec>&lt;C-c></spec>
    <description short="true">
        <p>Quit Command Line mode without executing.</p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<C-]>]]></tags>
    <spec>&lt;C-]></spec>
    <description short="true">
        <p>Expand a command-line abbreviation.</p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<A-p> c_<Up> c_<cmd-prev-match>]]></tags>
    <strut/>
    <spec>&lt;Up></spec>
    <description>
        <p>
            Recall from command history the previous command line
            which begins with the current input value.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<A-n> c_<Down> c_<cmd-next-match>]]></tags>
    <strut/>
    <spec>&lt;Down></spec>
    <description>
        <p>
            Recall from command history the next command line
            which begins with the current input value.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<C-p> c_<S-Up> c_<cmd-prev>]]></tags>
    <spec>&lt;S-Up></spec>
    <strut/>
    <spec>&lt;PageUp></spec>
    <description>
        <p>Recall the previous command line from the history list.</p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<C-n> c_<S-Down> c_<cmd-next>]]></tags>
    <spec>&lt;S-Down></spec>
    <spec>&lt;PageDown></spec>
    <description>
        <p>Recall the next command line from the history list.</p>
    </description>
</item>

<h2 tag="cmdline-completion">Command-line completion</h2>

<item>
    <tags><![CDATA[c_<Tab> c_<compl-next>]]></tags>
    <strut/>
    <spec>&lt;Tab></spec>
    <description>
        <p>
            Complete the word in front of the cursor according to the behavior
            specified in <o>wildmode</o>. If <o>wildmode</o> contains
            <str>list</str> and there are multiple matches then the completion
            menu window is opened.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<S-Tab> c_<compl-prev>]]></tags>
    <strut/>
    <spec>&lt;S-Tab></spec>
    <description>
        <p>Complete the previous full match when <o>wildmode</o> contains <str>full</str>.</p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<A-Tab> c_<A-compl-next>]]></tags>
    <strut/>
    <spec>&lt;A-Tab></spec>
    <description>
        <p>
            Similar to <k name="Tab" mode="c"/>, but the completion behavior is
            specified by the <o>altwildmode</o> option.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<A-S-Tab> c_<A-compl-prev>]]></tags>
    <strut/>
    <spec>&lt;A-S-Tab></spec>
    <description>
        <p>The <k name="S-Tab" mode="c"/> equivalent for <o>altwildmode</o>.</p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<A-f> c_<C-Tab> c_<compl-next-group>]]></tags>
    <spec>&lt;C-Tab></spec>
    <description>
        <p>Select the next matching completion group.</p>
    </description>
</item>

<item>
    <tags><![CDATA[c_<A-S-F> c_<C-S-Tab> c_<compl-prev-group>]]></tags>
    <spec>&lt;C-S-Tab></spec>
    <description>
        <p>Select the previous matching completion group.</p>
    </description>
</item>


<h2 tag="cmdline-lines">Ex command lines</h2>

<item>
    <tags>:bar</tags>
    <strut/>
    <description>
        <p>
            Multiple commands, separated by a <em>|</em> can be
            given in a single command line and will be executed consecutively.
            <em>|</em> can be included as an argument to a command by escaping
            it with a backslash. E.g.
            <code><ex>:map \|</ex> <ex>:echo <str>bar</str></ex><k name="CR"/></code>

            Several commands process the entire command-line string literally.
            These commands will include any <em>|</em> as part of their
            argument string and so cannot be followed by another command. The
            list of these commands is:
            <ul>
                <li><ex>:abbreviate</ex></li>
                <li><ex>:autocmd</ex></li>
                <li><ex>:cabbreviate</ex></li>
                <li><ex>:cmap</ex></li>
                <li><ex>:cnoremap</ex></li>
                <li><ex>:command</ex></li>
                <li><ex>:delmacros</ex></li>
                <li><ex>:delmarks</ex></li>
                <li><ex>:delqmarks</ex></li>
                <li><ex>:delstyle</ex></li>
                <li><ex>:echo</ex></li>
                <li><ex>:echoerr</ex></li>
                <li><ex>:echomsg</ex></li>
                <li><ex>:elseif</ex></li>
                <li><ex>:execute</ex></li>
                <li><ex>:highlight</ex></li>
                <li><ex>:iabbreviate</ex></li>
                <li><ex>:if</ex></li>
                <li><ex>:imap</ex></li>
                <li><ex>:inoremap</ex></li>
                <li><ex>:javascript</ex></li>
                <li><ex>:let</ex></li>
                <li><ex>:map</ex></li>
                <li><ex>:marks</ex></li>
                <li><ex>:nmap</ex></li>
                <li><ex>:nnoremap</ex></li>
                <li><ex>:noremap</ex></li>
                <li><ex>:open</ex></li>
                <li><ex>:qmarks</ex></li>
                <li><ex>:silent</ex></li>
                <li><ex>:style</ex></li>
                <li><ex>:styledisable</ex></li>
                <li><ex>:styleenable</ex></li>
                <li><ex>:styletoggle</ex></li>
                <li><ex>:tabopen</ex></li>
                <li><ex>:toolbarhide</ex></li>
                <li><ex>:toolbarshow</ex></li>
                <li><ex>:toolbartoggle</ex></li>
                <li><ex>:vmap</ex></li>
                <li><ex>:vnoremap</ex></li>
                <li><ex>:winopen</ex></li>
                <li><ex>:yank</ex></li>
            </ul>
        </p>
    </description>
</item>

<h3 tag="cmdline-arguments">Ex command-line arguments</h3>

<p>
    Most Ex commands accept a number of options and arguments. Arguments and
    options are generally separated by spaces, and treat a number of
    characters, including <em>\</em>, <em>'</em>, <em>"</em>, and <em>|</em>,
    specially.  Moreover, certain arguments have their own special characters.
    For instance, when using <ex>:set</ex> to change a <t>stringlist</t>
    option, the comma character is used to separate elements of said list. Or
    when calling <ex>:autocmd</ex>, the pattern given may be negated by
    prefixing it with a <em>!</em>. In order to use these characters in
    command arguments, stripped of their special meaning, they must be quoted.
</p>

<p tag="cmdline-quoting quoting">
    &dactyl.appName; offers four distinct quoting styles, each with its own
    distinct advantages and disadvantages. The first, and most basic, is the
    automatic quoting applied to the commands listed in <ex>:bar</ex>. When
    any of these commands is invoked, their final argument is always
    interpreted literally. No characters have special meaning whatsoever, and
    no care need be taken to quote anything. Additionally, the following three
    optional quoting characters are available:
</p>

<dl dt="width: 8em;">
    <dt>\</dt>
    <dd>
        This is the most basic quoting character. When it is encountered
        outside of single or double quotes, it forces the next character to be
        interpreted literally. So, for instance, <tt>\\</tt> ⇒ <tt>\</tt>,
        <tt>\'</tt> ⇒ <tt>'</tt>, <tt>\a</tt> ⇒ <tt>a</tt>, and
        <tt>\␣</tt> ⇒ <tt>␣</tt>.
    </dd>
    <dt>'</dt>
    <dd>
        Any character inside single quotes aside from the ' character itself
        is interpreted literally. To include a literal single quote, it must
        be doubled. So, <code>'foo\ ''bar\\ baz\' ⇒ foo\ 'bar\\ baz\</code>
    </dd>
    <dt>"</dt>
    <dd>
        Any character inside of double quotes except for <em>"</em> and
        <em>\</em> is interpreted literally. A literal double quote may be
        included by preceding it with a backslash. Any other occurrence of a
        backslash starts an escape sequence as in JSON strings.
        Among the available escape sequences are:
        <dl dt="width: 8em;">
            <dt>\n</dt> <dd>A newline character.</dd>
            <dt>\t</dt> <dd>A tab character.</dd>
            <dt>\uxxxx</dt> <dd>Where each <em>x</em> is a digit between 0 and F, a Unicode character at code-point <em>xxxx</em>.</dd>
        </dl>
    </dd>
</dl>

<p tag="cmdline-options">
    Many Ex commands accept option arguments in addition to regular arguments.
    Option arguments begin with a hyphen (<em>-</em>), and often have a short
    form and a long form, such as <em>-name</em> and <em>-n</em>. Most options
    accept arguments, which come after the option separated by either a space
    or an equal sign. For instance, the following three forms,
    <em>-name=<str>foo</str></em>, <em>-name <str>foo</str></em>, and
    <em>-n <str>foo</str></em>, are all acceptable and entirely equivalent.
</p>

</document>

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