common/locale/en-US/starting.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/dtd">
   5
   6 <document
   7     name="starting"
   8     title="&dactyl.appName; Starting"
   9     xmlns="&xmlns.dactyl;"
  10     xmlns:html="&xmlns.html;">
  11
  12 <h1 tag="starting">Starting &dactyl.appName;</h1>
  13 <toc start="2"/>
  14
  15 <h2 tag="startup-options">Command-line options</h2>
  16
  17 <p>
  18     Command-line options can be passed to &dactyl.appName; via the -&dactyl.name; &dactyl.host;
  19     option. These are passed as single string argument.
  20     E.g., <tt>&dactyl.hostbin; -&dactyl.name; <str><t>++cmd</t> 'set exrc' <t>+u</t> 'tempRcFile' <t>++noplugin</t></str></tt>
  21 </p>
  22
  23 <item>
  24     <tags>+c</tags>
  25     <strut/>
  26     <spec>+c <a>command</a></spec>
  27     <description>
  28         <p>
  29             Execute a single Ex command after all initialization has been performed. See
  30             <t>initialization</t>.
  31         </p>
  32
  33         <p>This option can be specified multiple times.</p>
  34     </description>
  35 </item>
  36
  37 <item>
  38     <tags>++cmd</tags>
  39     <strut/>
  40     <spec>++cmd <a>command</a></spec>
  41     <description>
  42         <p>
  43             Execute a single Ex command before any initialization has been performed. See
  44             <t>initialization</t>.
  45         </p>
  46
  47         <p>This option can be specified multiple times.</p>
  48     </description>
  49 </item>
  50
  51 <item>
  52     <tags>+u</tags>
  53     <strut/>
  54     <spec>+u <a>rcfile</a></spec>
  55     <description>
  56         <p>
  57             The file <a>rcfile</a> is used for user initialization commands. If <a>rcfile</a> is
  58             <str>NORC</str> then no startup initialization is performed except for the loading of
  59             plugins, i.e., steps 1. and 2. in <t>initialization</t> are skipped. If <a>rcfile</a>
  60             is <str>NONE</str> then plugin loading is also skipped.
  61         </p>
  62     </description>
  63 </item>
  64
  65 <item>
  66     <tags>++noplugin</tags>
  67     <strut/>
  68     <spec>++noplugin</spec>
  69     <description>
  70         <p>Prevents plugin scripts from being loaded at startup. See <o>loadplugins</o>.</p>
  71     </description>
  72 </item>
  73
  74 <h2 tag="initialization startup">Initialization</h2>
  75
  76 <p>At startup, &dactyl.appName; completes the following tasks in order. </p>
  77
  78 <ol>
  79     <li>
  80         <p>
  81             &dactyl.appName; first searches for user initialization commands in
  82             the following locations. The first of these to be found is executed,
  83             after which no further locations are searched.
  84         </p>
  85
  86         <ol>
  87             <li tag="$&dactyl.idName;_INIT">
  88                 <em>$&dactyl.idName;_INIT</em>
  89                 <strut/>
  90                 May contain a single Ex command (e.g., "<ex>:source <a>file</a></ex>").
  91             </li>
  92             <li tag="$MY_&dactyl.idName;RC">
  93                 <em>~/_&dactyl.name;rc</em>
  94                 <strut/>
  95                 Windows only. If this file exists, its contents
  96                 are executed and <tt>$MY_&dactyl.idName;RC</tt> set to its path.
  97             </li>
  98             <li tag="&dactyl.name;rc ">
  99                 <em>~/.&dactyl.name;rc</em>
 100                 <strut/>
 101                 If this file exists, its contents are executed.
 102             </li>
 103         </ol>
 104     </li>
 105     <li>
 106         <p>
 107             If <o>exrc</o> is set and the <t>+u</t> command-line option was not
 108             specified, then any RC file in the current directory is also
 109             sourced.
 110         </p>
 111     </li>
 112     <li>
 113         <p>
 114             All directories in <o>runtimepath</o> are searched for a
 115             ‘plugins’ subdirectory and all yet unloaded plugins are loaded.
 116             For each plugins directory, all <tt>*.{js,&dactyl.fileExt;}</tt>
 117             files (including those in further subdirectories) are sourced
 118             alphabetically. No plugins will be sourced if,
 119         </p>
 120
 121         <ul>
 122             <li><o>loadplugins</o> is unset,</li>
 123             <li>the <t>++noplugin</t> command-line option was specified, or</li>
 124             <li>the <tt><t>+u</t>=NONE</tt> command-line option was specified.</li>
 125         </ul>
 126
 127         <p>
 128             Any plugin which was already loaded (e.g., by an earlier
 129             invocation of the <ex>:loadplugins</ex> command) will be skipped.
 130         </p>
 131     </li>
 132 </ol>
 133
 134 <p>
 135     The user's home directory is determined as follows:
 136 </p>
 137
 138 <ul>
 139     <li>On Unix and Mac, the environment variable <tt>$HOME</tt> is used.</li>
 140     <li>
 141         On Windows, &dactyl.appName; checks for the existence of
 142         <tt>%HOME%</tt>, then <tt>%USERPROFILE%</tt>, and then
 143         <tt>%HOMEDRIVE%%HOMEPATH%</tt>. It uses the first one it
 144         finds.
 145     </li>
 146 </ul>
 147
 148 <h2 tag="save-settings">Saving settings</h2>
 149
 150 <item>
 151     <tags>:mkp :mk&dactyl.name;rc</tags>
 152     <spec>:mkp<oa>entadactylrc</oa><oa>!</oa> <oa>file</oa></spec>
 153     <description>
 154         <p>
 155             Write current key mappings and changed options to <oa>file</oa>. If no
 156             <oa>file</oa> is specified then <em>~/.&dactyl.name;rc</em> is written unless this file
 157             already exists. The special version <ex>:mk&dactyl.name;rc!</ex> will overwrite
 158             <oa>file</oa> if it exists.
 159         </p>
 160
 161         <warning>
 162             This behavior differs differs from that of Vim, which defaults to
 163             writing the file in the current directory.
 164         </warning>
 165     </description>
 166 </item>
 167
 168 <h2 tag="restarting">Restarting</h2>
 169
 170 <item>
 171     <tags>:reh :rehash</tags>
 172     <spec>:reh<oa>ash</oa> <oa>arg</oa> …</spec>
 173     <description>
 174         <p>
 175             Reload the &dactyl.appName; add-on, including all code, plugins,
 176             and configuration. For users running directly from the development
 177             repository, this is a good way to update to the latest version or
 178             to test your changes.
 179         </p>
 180         <p>
 181             Any arguments supplied are parsed as command-line arguments as
 182             specified in <t>startup-options</t>.
 183         </p>
 184         <warning>
 185             Not all plugins are designed to cleanly un-apply during a rehash.
 186             While official plugins are safe, beware of possible instability
 187             if you rehash while running third-party plugins.
 188         </warning>
 189     </description>
 190 </item>
 191
 192 <item>
 193     <tags>:res :restart</tags>
 194     <spec>:res<oa>tart</oa></spec>
 195     <description short="true">
 196         <p>Force &dactyl.host; to restart. Useful when installing extensions.</p>
 197     </description>
 198 </item>
 199
 200 </document>
 201
 202 <!-- vim:se sts=4 sw=4 et: -->