common/locale/en-US/map.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
   3
   4 <!DOCTYPE document SYSTEM "dactyl://content/modes.dtd">
   5
   6 <document
   7     name="map"
   8     title="&dactyl.appName; Key Mappings"
   9     xmlns="&xmlns.dactyl;"
  10     xmlns:dactyl="&xmlns.dactyl;"
  11     xmlns:html="&xmlns.html;">
  12
  13 <h1 tag="keyboard-shortcuts">Keyboard shortcuts and commands</h1>
  14 <toc start="2"/>
  15
  16 <p>
  17     &dactyl.appName; provides a number of commands to change the
  18     behavior of key presses. This can mean anything from
  19     automatically substituting one key for another or automatically
  20     replacing one typed word for another, to launching a dialog or
  21     running a command.
  22 </p>
  23
  24 <h2 tag="key-mapping mapping map macro">Key mapping</h2>
  25
  26 <p>
  27     Key mappings are the most basic means &dactyl.appName; provides
  28     for altering the actions of key presses. Each key mapping is
  29     associated with a mode, such as <link topic="insert-mode">Insert</link>,
  30     <link>Normal</link>, or
  31     <link topic="command-line-mode">Command Line</link>, and only
  32     has effect when that mode is active. Although each mode has a
  33     full suite of internal mappings, they may be easily augmented,
  34     altered, or removed with the <ex>:map</ex> command and its
  35     variants. These commands, in essence, allow the user to quickly
  36     substitute one sequence of key presses for another.
  37     For instance,
  38 </p>
  39
  40 <code><ex>:map <k name="F2" link="false"/></ex> <ex>:echo Date()<k name="CR"/></ex></code>
  41
  42 <p>
  43     causes “<ex>:echo Date()<k name="CR"/></ex>” to be typed out
  44     whenever <k name="F2" link="false"/> is pressed, thus echoing the full date
  45     to the command line.
  46 </p>
  47
  48 <p tag=":map-modes">
  49     Standard key mapping commands are provided for the five most
  50     common modes,
  51 </p>
  52
  53 <dl dt="width: 8em;">
  54     <dt>n</dt> <dd>Normal mode: When browsing normally</dd>
  55     <dt>v</dt> <dd>Visual mode: When selecting text with the cursor keys</dd>
  56     <dt>i</dt> <dd>Insert mode: When interacting with text fields on a website</dd>
  57     <dt>t</dt> <dd>Text Edit mode: When editing text fields in Vim-like Normal mode</dd>
  58     <dt>c</dt> <dd>Command Line mode: When typing into the &dactyl.appName; command line</dd>
  59 </dl>
  60
  61 <p>
  62     The ordinary <ex>:map</ex> and <ex>:noremap</ex> commands
  63     add mappings for Normal and Visual mode. In order to map key
  64     bindings in a different mode, any of the mapping commands may be
  65     prefixed with one of the above letters. For instance,
  66     <ex>:imap</ex> creates a new key mapping in Insert mode, while
  67     <ex>:cunmap</ex> removes a key mapping from Command Line mode.
  68     Other modes can be specified using the -modes option described below.
  69 </p>
  70
  71 <warning>
  72     It is important to note that mappings are <em>not</em>
  73     automatically saved between sessions. In order to preserve them,
  74     they must either be added to your <tt><t>&dactyl.name;rc</t></tt> or
  75     saved via the <ex>:mk&dactyl.name;rc</ex> command.
  76 </warning>
  77
  78 <p tag="modes">
  79     The following tree represents all of the modes understood by
  80     dactyl. Mappings for a mode also apply to its children and
  81     descendants. So a mapping in the Base mode, for instance, is
  82     also active in Normal and Ex mode.
  83 </p>
  84
  85 &modes.tree;
  86
  87 <h3 tag=":map-commands">Map commands</h3>
  88
  89 <item>
  90     <tags>:map</tags>
  91     <spec>:map <a>lhs</a> <a>rhs</a></spec>
  92     <tags>:nm :nmap</tags>
  93     <spec>:nm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
  94     <tags>:vm :vmap</tags>
  95     <spec>:vm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
  96     <tags>:im :imap</tags>
  97     <spec>:im<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
  98     <tags>:tm :tmap</tags>
  99     <spec>:tm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
 100     <tags>:cm :cmap</tags>
 101     <spec>:cm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
 102     <description>
 103         <p>
 104             Map the <t>key-sequence</t> <a>lhs</a> to <a>rhs</a> for
 105             the applicable mode(s). The keys of <a>rhs</a> respect
 106             user-defined mappings, so the following will result in
 107             an infinite loop,
 108         </p>
 109         <code><ex>:map a b</ex>
 110 <ex>:map b a</ex></code>
 111         <p>
 112             In order to avoid this shortcoming, the <ex>:noremap</ex> command
 113             or the <em>-builtin</em> option may be used.
 114         </p>
 115     </description>
 116 </item>
 117
 118 <p tag=":map-overview">
 119     Below is an overview of which modes each map command applies to:
 120 </p>
 121
 122 <dl dt="width: 20em;">
 123     <dt>:map   :noremap   :unmap</dt>  <dd>Normal and Visual modes</dd>
 124     <dt>:nmap  :nnoremap  :nunmap</dt> <dd>Normal mode</dd>
 125     <dt>:vmap  :vnoremap  :vunmap</dt> <dd>Visual mode</dd>
 126     <dt>:imap  :inoremap  :iunmap</dt> <dd>Insert mode</dd>
 127     <dt>:tmap  :tnoremap  :tunmap</dt> <dd>Text Edit mode</dd>
 128     <dt>:cmap  :cnoremap  :cunmap</dt> <dd>Command Line mode</dd>
 129 </dl>
 130
 131 <note>
 132     The <em>-modes</em> option, described below, provides a more flexible way
 133     to specify the applicable modes.
 134 </note>
 135
 136 <h3 tag=":map-options">Map options</h3>
 137 <p>
 138     Any of the map commands may be given the following options:
 139 </p>
 140
 141 <dl dt="width: 12em;">
 142     <dt></dt> <dd></dd>
 143
 144     <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>
 145     <dt>-builtin</dt> <dd>Execute this mapping as if there were no user-defined mappings (short name <em>-b</em>)</dd>
 146     <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>
 147     <dt>-description</dt> <dd>A description of this mapping (short name <em>-d</em>)</dd>
 148     <dt>-ex</dt> <dd>Execute <a>rhs</a> as an Ex command rather than keys (short name <em>-e</em>)</dd>
 149     <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>
 150     <dt>-javascript</dt> <dd>Execute <a>rhs</a> as JavaScript rather than keys (short names <em>-js</em>, <em>-j</em>)</dd>
 151     <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>
 152     <dt>-modes=<a>modes</a></dt> <dd>Create this mapping in the given modes (short names <em>-mode</em>, <em>-m</em>)</dd>
 153     <dt>-nopersist</dt> <dd>Do not save this mapping to an auto-generated rc file (short name <em>-n</em>)</dd>
 154     <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>
 155 </dl>
 156
 157 <item>
 158     <tags>:no :noremap</tags>
 159     <spec>:no<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
 160     <tags>:nno :nnoremap</tags>
 161     <spec>:nno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
 162     <tags>:vno :vnoremap</tags>
 163     <spec>:vno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
 164     <tags>:ino :inoremap</tags>
 165     <spec>:ino<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
 166     <tags>:tno :tnoremap</tags>
 167     <spec>:tno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
 168     <tags>:cno :cnoremap</tags>
 169     <spec>:cno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
 170     <description>
 171         <p>
 172             Map the <t>key-sequence</t> <a>lhs</a> to <a>rhs</a> for
 173             the applicable mode(s). The keys in <a>rhs</a> do not
 174             respect user-defined key mappings, so the following
 175             effectively reverses the default meanings of the keys
 176             <k>d</k> and <k>D</k>
 177         </p>
 178         <code><ex>:noremap d D</ex>
 179 <ex>:noremap D d</ex></code>
 180     </description>
 181 </item>
 182
 183 <item>
 184     <spec>:unmap <a>lhs</a></spec>
 185     <tags>:unm :unmap</tags>
 186     <spec>:unmap!</spec>
 187     <spec>:nun<oa>map</oa> <a>lhs</a></spec>
 188     <tags>:nun :nunmap</tags>
 189     <spec>:nun<oa>map</oa>!</spec>
 190     <spec>:vun<oa>map</oa> <a>lhs</a></spec>
 191     <tags>:vun :vunmap</tags>
 192     <spec>:vun<oa>map</oa>!</spec>
 193     <spec>:iu<oa>nmap</oa> <a>lhs</a></spec>
 194     <tags>:iu :iunmap</tags>
 195     <spec>:iu<oa>nmap</oa>!</spec>
 196     <spec>:tu<oa>nmap</oa> <a>lhs</a></spec>
 197     <tags>:tu :tunmap</tags>
 198     <spec>:tu<oa>nmap</oa>!</spec>
 199     <spec>:cu<oa>nmap</oa> <a>lhs</a></spec>
 200     <tags>:cu :cunmap</tags>
 201     <spec>:cu<oa>nmap</oa>!</spec>
 202     <description>
 203         <p>Remove the mapping of <a>lhs</a> (or all mappings if <oa>!</oa> is
 204             given) for the applicable mode(s).</p>
 205     </description>
 206 </item>
 207
 208 <item>
 209     <spec>:map</spec>
 210     <spec>:nm<oa>ap</oa></spec>
 211     <spec>:vm<oa>ap</oa></spec>
 212     <spec>:im<oa>ap</oa></spec>
 213     <spec>:tm<oa>ap</oa></spec>
 214     <spec>:cm<oa>ap</oa></spec>
 215     <description>
 216         <p>
 217             List all mappings for the applicable mode(s). Mappings are
 218             partitioned into <t>groups</t>.
 219         </p>
 220     </description>
 221 </item>
 222
 223 <item>
 224     <tags>:map_l</tags>
 225     <spec>:map <a>lhs</a></spec>
 226     <tags>:nmap_l</tags>
 227     <spec>:nm<oa>ap</oa> <a>lhs</a></spec>
 228     <tags>:vmap_l</tags>
 229     <spec>:vm<oa>ap</oa> <a>lhs</a></spec>
 230     <tags>:imap_l</tags>
 231     <spec>:im<oa>ap</oa> <a>lhs</a></spec>
 232     <tags>:tmap_l</tags>
 233     <spec>:tm<oa>ap</oa> <a>lhs</a></spec>
 234     <tags>:cmap_l</tags>
 235     <spec>:cm<oa>ap</oa> <a>lhs</a></spec>
 236     <description>
 237         <p>List all mappings starting with <a>lhs</a> for the applicable mode(s).</p>
 238     </description>
 239 </item>
 240
 241 <h3 tag=":map-timeout map-timeout">Mapping timeout</h3>
 242 <p>
 243     When &dactyl.appName; receives a key event that has a separate binding and
 244     at the same time is part of a key chain, values of the <o>timeout</o> and
 245     <o>timeoutlen</o> options are used to decide what to do. See the
 246     documentation of those options for more information.
 247 </p>
 248
 249 <h3 tag="key-notation key-sequence">Key sequences</h3>
 250
 251 <p>
 252     Most keys in key sequences are represented simply by the
 253     character that you see on the screen when you type them.
 254     However, as a number of these characters have special meanings,
 255     and a number of keys have no visual representation, a special
 256     notation is required.
 257 </p>
 258
 259 <ul>
 260     <li>
 261         The first argument to the <ex>:map</ex> commands must be
 262         <link topic="quoting">quoted</link> if it contains spaces,
 263         quotation marks or back-slashes. A space may additionally be
 264         typed as <k name="Space"/>.
 265     </li>
 266     <li key="&lt;lt>">
 267         As special key names start with the <em>&lt;</em> character,
 268         a literal &lt; must be typed as <k name="lt" link="false"/>.
 269     </li>
 270     <li>
 271         <k name="Left"/>, <k name="Right"/>, <k name="Up"/>,
 272         and <k name="Down"/> represent the standard arrow keys.
 273     </li>
 274     <li>
 275         <k name="CapsLock" link="false"/>, <k name="NumLock" link="false"/>, <k name="Insert"/>
 276         <k name="Del" link="false"/>, <k name="Tab"/>, <k name="PageUp"/>,
 277         <k name="PageDown"/>, and <k name="Esc"/> work as
 278         expected.
 279    </li>
 280     <li>
 281         <k name="Return" link="false"/> or <k name="CR"/> represent the carriage
 282         return key.
 283     </li>
 284     <li><k name="BS" link="false"/> represents the backspace key.</li>
 285     <li><k name="F1"/> through <k name="F12" link="false"/> work as expected.</li>
 286     <li>
 287         <k name="K0" link="false"/> through <k name="K9" link="false"/> represent keys on the
 288         numeric keypad.
 289     </li>
 290     <li>
 291         <k name="Uxxxx" link="false"/>, where <em>xxxx</em> is any 4 hexadecimal
 292         digits, represents the character at that Unicode codepoint.
 293         For instance, <k name="U263a" link="false"/> represents ☺.
 294     </li>
 295 </ul>
 296
 297 <p>
 298     In order to represent key presses using the Control, Alt, Meta,
 299     or Shift keys, the following prefixes may be used,
 300 </p>
 301
 302 <ol>
 303     <li><k name="C-␣" link="false"/>: The control or ctrl key.</li>
 304     <li><k name="A-␣" link="false"/>: The alt key.</li>
 305     <li><k name="M-␣" link="false"/>: The meta key, windows key, or command key.</li>
 306     <li><k name="⌘-␣" link="false"/>: Same as <k name="M-␣" link="false"/>.</li>
 307     <li><k name="S-␣" link="false"/>: The shift key.</li>
 308 </ol>
 309
 310 <p>
 311     These prefixes can be combined however you see fit.
 312 </p>
 313
 314 <note>
 315     Within angle brackets all alphabetic characters are read as lowercase.
 316     Uppercase characters can only be specified with the <em>S-</em> modifier.
 317 </note>
 318
 319 <p>
 320     The following key sequences are interpreted as described:
 321 </p>
 322
 323 <dl dt="width: 10em;">
 324     <dt><k link="false">xc</k></dt>
 325     <dd>Press the ‘X’ key followed by the ‘C’ key.</dd>
 326
 327     <dt><k name="C-x" link="false">c</k></dt>
 328     <dd>
 329         Press the ‘X’ key while holding the ‘Control’ key, followed
 330         by the ‘C’ key.
 331     </dd>
 332
 333     <dt><k name="C-2" link="false"/></dt>
 334     <dd>Type ‘2’ while holding the ‘Control’ key.</dd>
 335
 336     <dt><k name="C-@" link="false"/></dt>
 337     <dd>Press the ‘@’ key while holding the ‘Control’ key.</dd>
 338
 339     <dt><k name="S-Space" link="false"/></dt>
 340     <dd>Press the space bar while holding the ‘Shift’ key.</dd>
 341
 342     <dt><k name="C-A-j" link="false"/></dt>
 343     <dd>Press the ‘J’ key while holding both the ‘Control’ and ‘Alt’ keys.</dd>
 344
 345     <dt><k name="C-A-J" link="false"/></dt>
 346     <dd>Exactly the same as above.</dd>
 347
 348     <dt><k name="C-A-S-j" link="false"/></dt>
 349     <dd>Press the ‘J’ key while holding all of ‘Control’, ‘Alt’, and ‘Shift’ keys.</dd>
 350 </dl>
 351
 352 <h3 tag=":map-special-chars">Special characters</h3>
 353
 354 <item>
 355     <tags><![CDATA[<Nop>]]></tags>
 356     <strut/>
 357     <spec><![CDATA[<Nop>]]></spec>
 358     <description>
 359         <p>
 360             Do nothing. This pseudo-key is useful for disabling a
 361             specific builtin mapping. For example,
 362             <ex>:map <k name="C-n"/> <k name="Nop"/></ex> will prevent <k name="C-n"/>
 363             from doing anything.
 364         </p>
 365     </description>
 366 </item>
 367
 368 <item>
 369     <tags><![CDATA[<Pass>]]></tags>
 370     <spec><![CDATA[<Pass>]]></spec>
 371     <description short="true">
 372         <p>
 373             Pass the events consumed by the last executed mapping through to &dactyl.host;.
 374         </p>
 375     </description>
 376 </item>
 377
 378 <item>
 379     <tags><![CDATA[<CR> map_return]]></tags>
 380     <strut/>
 381     <spec><![CDATA[<CR>]]></spec>
 382     <description>
 383         <p>
 384             Expand to a line terminator in a key mapping. An Ex command in the <a>rhs</a> of a
 385             mapping requires a line terminator after it so that it is executed when the
 386             mapping is expanded. <k name="CR"/> should be used for this purpose.
 387         </p>
 388     </description>
 389 </item>
 390
 391 <item>
 392     <tags><![CDATA[<Leader> \]]></tags>
 393     <strut/>
 394     <spec><![CDATA[<Leader>]]></spec>
 395     <description>
 396         <p>
 397             A pseudo-key which expands to the value of the <o>mapleader</o>
 398             option. For example, by default,
 399         </p>
 400         <code><ex>:map <k name="Leader"/>h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
 401         <p>works like</p>
 402         <code><ex>:map \h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
 403         <p>but after</p>
 404         <set opt="mapleader"><str>,</str></set>
 405         <p>it works like</p>
 406         <code><ex>:map ,h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
 407     </description>
 408 </item>
 409
 410 <h2 tag="abbreviations">Abbreviations</h2>
 411
 412 <p>
 413     In addition to basic mappings, &dactyl.appName; can also
 414     automatically replace whole words after they've been typed.
 415     These shortcuts are known as abbreviations, and are most often
 416     useful for correcting spelling of commonly mistyped words, as
 417     well as shortening the typing of oft-typed but long words or
 418     phrases. There are three basic types of abbreviations, defined
 419     by the types of characters they contain,
 420 </p>
 421
 422 <ul>
 423     <li>‘full-id’ abbreviations consist entirely of keyword characters (e.g., ‘teh’, ‘msoft’).</li>
 424     <li>‘end-id’ abbreviations end in keyword character but otherwise contains all non-keyword characters (e.g., ‘'i’).</li>
 425     <li>‘non-id’ abbreviations end in a non-keyword character but otherwise contains any non-whitespace character (e.g., ‘def'’).</li>
 426     <li>Strings which fit none of the above patterns can not be defined as abbreviations (e.g., ‘a'b’ and ‘a b’).</li>
 427 </ul>
 428
 429 <p>
 430     For the purposes of abbreviations, keyword characters include
 431     all non-whitespace characters except for single or double
 432     quotation marks. Abbreviations are expanded as soon as any
 433     non-keyword character, or the key <k name="C-]" mode="c"/>, is typed.
 434 </p>
 435
 436 <item>
 437     <tags>:ab :abbreviate</tags>
 438     <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa> <oa>-js</oa> <a>lhs</a> <a>rhs</a></spec>
 439     <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa> <a>lhs</a></spec>
 440     <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa></spec>
 441     <description>
 442         <p>
 443             Abbreviate <a>lhs</a> to <a>rhs</a>. If only <a>lhs</a>
 444             is given, list all abbreviations that start with
 445             <a>lhs</a>. If no arguments are given, list all
 446             abbreviations.
 447         </p>
 448
 449         <p>
 450             If the <em>-javascript</em> (short names <em>-js</em>,
 451             <em>-j</em>) option is given, <a>lhs</a> is expanded to
 452             the value <em>return</em>ed by the JavaScript code
 453             <a>rhs</a>. The code is evaluated with the variable
 454             <em>editor</em> set to the editable element that the
 455             abbreviation is currently being expanded in. The code
 456             should <em>not</em> make any changes to the contents of
 457             the editor.
 458         </p>
 459
 460         <p>
 461             If <a>group</a> is specified then abbreviations are created or
 462             listed for the given <t>group</t>.
 463         </p>
 464     </description>
 465 </item>
 466
 467 <item>
 468     <tags>:ca :cabbreviate</tags>
 469     <spec>:ca<oa>bbreviate</oa> <a>lhs</a> <a>rhs</a></spec>
 470     <spec>:ca<oa>bbreviate</oa> <a>lhs</a></spec>
 471     <spec>:ca<oa>bbreviate</oa></spec>
 472     <description>
 473         <p>
 474             Abbreviate a key sequence for Command Line mode. Same as
 475             <ex>:ab<oa>breviate</oa></ex>, but for &mode.command-line; mode
 476             only.
 477         </p>
 478     </description>
 479 </item>
 480
 481 <item>
 482     <tags>:ia :iabbreviate</tags>
 483     <spec>:ia<oa>bbreviate</oa> <a>lhs</a> <a>rhs</a></spec>
 484     <spec>:ia<oa>bbreviate</oa> <a>lhs</a></spec>
 485     <spec>:ia<oa>bbreviate</oa></spec>
 486     <description>
 487         <p>
 488             Abbreviate a key sequence for Insert mode. Same as
 489             <ex>:ab<oa>breviate</oa></ex>, but for Insert mode only.
 490         </p>
 491     </description>
 492 </item>
 493
 494 <item>
 495     <tags>:una :unabbreviate</tags>
 496     <spec>:una<oa>bbreviate</oa> <a>lhs</a></spec>
 497     <spec>:una<oa>bbreviate</oa>!</spec>
 498     <description>
 499         <p>Remove an abbreviation. With <oa>!</oa>, remove all abbreviations.</p>
 500     </description>
 501 </item>
 502
 503 <item>
 504     <tags>:cuna :cunabbreviate</tags>
 505     <spec>:cuna<oa>bbreviate</oa> <a>lhs</a></spec>
 506     <spec>:cuna<oa>bbreviate</oa>!</spec>
 507     <description>
 508         <p>
 509             Remove abbreviation(s) for Command Line mode. Same as
 510             <ex>:una<oa>bbreviate</oa></ex>, but for &mode.command-line; mode
 511             only.
 512         </p>
 513     </description>
 514 </item>
 515
 516 <item>
 517     <tags>:iuna :iunabbreviate</tags>
 518     <spec>:iuna<oa>bbreviate</oa> <a>lhs</a></spec>
 519     <spec>:iuna<oa>bbreviate</oa>!</spec>
 520     <description>
 521         <p>
 522             Remove abbreviation(s) for Insert mode. Same as
 523             <ex>:una<oa>bbreviate</oa></ex> but for Insert mode
 524             only.
 525         </p>
 526     </description>
 527 </item>
 528
 529 <h2 tag="user-commands">User-defined commands</h2>
 530
 531 <p>
 532     Defining new commands is perhaps the most straightforward way of
 533     repeating commonly used actions. User-defined commands may be
 534     entered from the command line or scripts exactly like standard
 535     commands, and may similarly accept arguments, options, counts,
 536     and <oa>!</oa>s, as well as provide command-line completion.
 537     These commands may be defined as either ordinary,
 538     macro-interpolated Ex commands, or otherwise as plain
 539     JavaScript statements.
 540 </p>
 541
 542 <item>
 543     <tags>:com :command</tags>
 544     <spec>:com<oa>mand</oa></spec>
 545     <description short="true">
 546         <p>List all user-defined commands.</p>
 547     </description>
 548 </item>
 549
 550 <item>
 551     <spec>:com<oa>mand</oa> <oa>cmd</oa></spec>
 552     <description>
 553         <p>
 554             List all user-defined commands that start with <oa>cmd</oa>. Commands
 555             are partitioned into <t>groups</t>.
 556         </p>
 557     </description>
 558 </item>
 559
 560 <item>
 561     <spec>:com<oa>mand</oa><oa>!</oa> <oa><a>options</a>…</oa> <a>cmd</a> <a>rep</a></spec>
 562     <description>
 563         <p>
 564             Define a new user command. The name of the command is
 565             <a>cmd</a> and its replacement text is <a>rep</a>. If a
 566             command with this name already exists, an error is
 567             reported unless <oa>!</oa> is specified, in which case
 568             the command is redefined. Unlike Vim, the command may
 569             start with a lowercase letter. <a>cmd</a> may also be multiple
 570             alternative command names separated by commas.
 571         </p>
 572
 573         <p>
 574             The new command is usually defined by a string to be
 575             executed as an Ex command. In this case, before
 576             execution, strings of the form
 577             <hl key="HelpKey">&lt;<a>var</a>></hl> are interpolated
 578             as described below, in order to insert arguments,
 579             options, and the like. If the <em>-javascript</em> (short
 580             name <em>-js</em>) flag is present, the command is
 581             executed as JavaScript, and the arguments are present as
 582             variables in its scope instead, and no interpolation is
 583             performed.
 584         </p>
 585
 586         <p>
 587             The command's behavior can be altered by providing
 588             options when the command is defined.
 589         </p>
 590
 591         <h3 tag=":command-group">Grouping</h3>
 592
 593         <p>
 594             The <em>-group</em> flag (short name: <em>-g</em>) can be used to
 595             assign this command to a specific <t>group</t>.  When listing
 596             commands this limits the output to the specified group.
 597         </p>
 598
 599         <h3 tag="E175 E176 :command-nargs">Argument handling</h3>
 600
 601         <p>
 602             By default, user commands accept no arguments. This can be changed by specifying
 603             the <tt>-nargs</tt> option.
 604         </p>
 605
 606         <p>The valid values are:</p>
 607
 608         <dl>
 609             <dt>-nargs=0</dt><dd>No arguments are allowed (default)</dd>
 610             <dt>-nargs=1</dt><dd>One argument is allowed</dd>
 611             <dt>-nargs=*</dt><dd>Zero or more arguments are allowed</dd>
 612             <dt>-nargs=?</dt><dd>Zero or one argument is allowed</dd>
 613             <dt>-nargs=+</dt><dd>One or more arguments are allowed</dd>
 614         </dl>
 615
 616         <h3 tag="E180 E181 :command-complete">Argument completion</h3>
 617
 618         <p>
 619             Completion for arguments to user-defined commands is not available by default.
 620             Completion can be enabled by specifying one of the following arguments to the
 621             -complete option when defining the command.
 622         </p>
 623
 624         <dl tag=":command-complete-arg-list"/>
 625
 626         <h3 tag="E467 E468 :command-completion-custom">Custom completion</h3>
 627
 628         <p>
 629             Custom completion can be provided by specifying the
 630             <str>custom,<a>thing</a></str> argument to <tt>-complete</tt>. If
 631             <a>thing</a> evaluates to a function (i.e., it is a variable holding
 632             a function value, or a string containing the definition itself), it
 633             is called with two arguments: a completion context, and an object
 634             describing the command's arguments. It should set the context's
 635             <tt>completions</tt> property to the list of completion results.
 636             Other influential properties include <tt>title</tt>, <tt>sort</tt>,
 637             <tt>anchored</tt>, and <tt>filters</tt>, which are documented in the
 638             <link topic="resource://dactyl/completion.jsm"
 639                 line="17" dactyl:command="buffer.viewSource">source code</link>.
 640         </p>
 641
 642         <p>
 643             <em>completions</em> is a two-dimensional array of the form:
 644             <tt>[[val1, description1], [val2, description2], …]</tt>
 645         </p>
 646
 647         <p>
 648             Otherwise <a>thing</a> should evaluate to an array of the same form
 649             as the <tt>completions</tt> property of the context object.
 650         </p>
 651
 652         <p>
 653             Example:
 654             <code><ex>:command foo -nargs=? -complete custom,<str delim="'">
 655     \ function (context) context.completions = [["val1", "description1"], ["val2", "description2"]]</str>
 656     \ <ex>:echo</ex> <str>Useless </str> + <em>&lt;q-args></em></ex>
 657
 658 <ex>:command foo -nargs=?
 659     \ -complete custom,<str delim="'">[["val1", "description1"], ["val2", "description2"]]</str>
 660     \ <ex>:echo</ex> <str>Same as above but simpler </str> + <em>&lt;q-args></em></ex></code>
 661         </p>
 662
 663         <h3 tag="E177 E178 :command-count">Count handling</h3>
 664
 665         <p>
 666             By default, user commands do not accept a count. Use the -count option if
 667             you'd like to have a count passed to your user command. This will then be
 668             available for expansion as &lt;count> in the replacement.
 669         </p>
 670
 671         <h3 tag=":command-bang">Special cases</h3>
 672
 673         <p>
 674             By default, a user command does not have a special version, i.e. a version
 675             executed with the ! modifier. Providing the -bang option will enable this
 676             and &lt;bang> will be available in the replacement.
 677         </p>
 678
 679         <h3 tag=":command-description">Command description</h3>
 680
 681         <p>
 682             The command's description text can be set with -description. Otherwise it will
 683             default to "User-defined command".
 684         </p>
 685
 686         <h3 tag=":command-replacement-text">Replacement text</h3>
 687
 688         <p>
 689             The replacement text <a>rep</a> is scanned for <t>macro-string</t>s and these are
 690             replaced with values from the user-entered command line. The resulting string
 691             is then executed as an Ex command.
 692         </p>
 693
 694         <p>
 695             In addition to the standard parameters listed in
 696             <t>macro-string</t>, the following parameters are available:
 697         </p>
 698
 699         <dl>
 700             <dt>&lt;args></dt> <dd>The command arguments exactly as supplied</dd>
 701             <dt>&lt;count></dt><dd>Any supplied count, e.g. 5</dd>
 702             <dt>&lt;bang></dt> <dd>! if the command was executed with the ! modifier</dd>
 703         </dl>
 704     </description>
 705 </item>
 706
 707 <item>
 708     <tags>:delc :delcommand</tags>
 709     <spec>:delc<oa>ommand</oa> <a>cmd</a></spec>
 710     <spec>:delc<oa>ommand</oa>!</spec>
 711     <description>
 712         <p>Delete the user-defined command <a>cmd</a>. With <oa>!</oa>, delete
 713             all user commands.</p>
 714     </description>
 715 </item>
 716
 717 <h2 tag="command-examples">Examples</h2>
 718
 719 <p>Add a :Google command to search via google:</p>
 720 <code><ex>:command -nargs=* Google open google &lt;args></ex></code>
 721
 722 <!-- TODO: add decent examples -->
 723
 724 </document>
 725
 726 <!-- vim:se sts=4 sw=4 et: -->