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