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