1 <?xml version="1.0" encoding="UTF-8"?>
2 <?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
4 <!DOCTYPE document SYSTEM "dactyl://content/dtd">
8 title="&dactyl.appName; Tutorial"
10 xmlns:html="&xmlns.html;">
12 <h1 tag="tutorial">Quick-start tutorial</h1>
15 This is a quick-start tutorial to help new users get up and running
16 in &dactyl.appName;. It is not intended as a full reference explaining all
21 If you've started using &dactyl.appName; from scratch (i.e., without any
22 customization), you should be looking at this help page in a relatively
23 bare-looking window. The menubar, navigation bar, and bookmark bars are hidden.
24 In case you missed the notice in the <t>intro</t>, you can
25 regain these by issuing the command
28 <set opt="go" op="+="><str delim="">mTB</str><k name="CR"/></set>
31 where <k name="CR"/> represents pressing the <k name="Enter" link="false"/>
32 or <k name="Return" link="false"/> key. If you're a veteran Vim user, this
37 However, in this author's opinion, the best way to get familiar with
38 &dactyl.appName; is to leave these disabled for now. (The above action can
39 be reversed with <se opt="go" op="&"/><k name="CR"/>) You can have a
40 look at the <o>guioptions</o> help entry for more information on this.
43 <h2 tag="modal">&dactyl.appName;'s modal interface</h2>
46 &dactyl.appName;'s power, like Vim's, comes from its modal interface. Keys have
47 different meanings depending on which mode the browser is in. &dactyl.appName; has
48 several modes, but the 2 most important are <em>Normal</em> mode and
49 <em>Command Line</em> mode (see <t>modes</t> for the full picture).
53 When &dactyl.appName; starts, it is in Normal mode by default. This is probably where
54 you will spend the majority of your time.
58 The other core mode of &dactyl.appName;, Command Line mode, can be entered from
59 Normal mode by typing a <k>:</k> (colon). You will frequently see &dactyl.appName;
60 commands start with a <k>:</k>, indicating that what follows is a command.
64 To return to Normal mode from Command Line mode, type <k name="Esc"/>.
65 Pressing <k name="Esc"/> will also return you to Normal mode from most
66 other &dactyl.appName; modes.
69 <h2 tag="getting-help">Getting help</h2>
72 Vim is a great editor but it's not much of a web browser. So even seasoned Vim
73 users will probably have to look at &dactyl.appName;'s documentation sooner or later.
74 Most of the documentation for &dactyl.appName;'s features are easily found using the
75 <ex>:help</ex> command. For example, you can find help on the <ex>:help</ex> command
79 <code><ex>:help :help<k name="CR"/></ex></code>
82 Similarly, help on configurable options is available with
83 <ex>:help '<a>option_name</a>'</ex>. (Note the single quotes
84 around the option name as in Vim.) Information on all available
85 options is, predictably, <ex>:help options</ex>.
89 And you can find out about the <k>gt</k> and <k>gT</k> mapping with
93 <ex>:help gt<k name="CR"/></ex>
94 <ex>:help gT<k name="CR"/></ex>
98 Finally, in addition to the help system itself, <ex>:listcommands</ex>,
99 <ex>:listkeys</ex> and <ex>:listoptions</ex> are useful quick-reference
103 <h2 tag="living-mouseless">Mouseless</h2>
105 <em>— or how I learned to stop worrying and love the 80+ buttons I already have.</em>
108 The efficiency of &dactyl.appName;, as with the legendary editor it was inspired by,
109 relies on the user being able to keep his fingers on the keyboard where they
110 can do the most good. While there are some areas where the mouse is clearly
111 superior at, such as GUI design or some games, &dactyl.appName; acts on the
112 assumption that a web browser doesn't have to be one of those.
116 Here are some areas where the mouse is typically considered indisposable, and
117 how &dactyl.appName; challenges this preconception.
120 <h2 tag="keyboard-scrolling">Scrolling</h2>
123 Scrolling the browser window is done with simple keystrokes:
127 <dt><k>j</k>/<k>k</k></dt>
129 scroll window down/up by one line, respectively
131 <dt><k>h</k>/<k>l</k></dt>
133 scroll window left/right
135 <dt><k name="C-f"/>/<k name="C-b"/></dt>
137 scroll down/up by one page
139 <dt><k name="C-d"/>/<k name="C-u"/></dt>
141 scroll down/up by 1/2 page
146 Your standard buttons (<k name="Up"/>/<k name="Down"/>/<k name="PageUp"/>/<k name="PageDown"/>) will
147 also work as expected.
150 <h2 tag="history-navigation tab-navigation">History and tabs</h2>
153 History navigation (e.g., <em>Back</em>, <em>Forward</em>) is done similarly to
158 <dt><k>H</k>/<k>L</k></dt>
160 move back/forward in the current tab's history
162 <dt><k name="C-o"/>/<k name="C-i"/></dt>
164 move back/forward in the current tab's jump list
169 Move between tabs using these keystrokes which may also be familiar to
174 <dt><k>gt</k>/<k name="C-n"/></dt>
178 <dt><k>gT</k>/<k name="C-p"/></dt>
180 go to the previous tab
182 <dt><k>g0</k>/<k>g$</k></dt>
184 go to the first/last tab
188 close the active tab (delete the buffer)
193 To open a web page in a new tab, use <ex>:tabopen <a>url</a></ex>. To open a URL in
194 the current tab, use <ex>:open</ex>. The Normal mode mappings <k>t</k> and <k>o</k>,
195 respectively, map to these commands, so the following pairs of sequences are
200 <ex>:open my.webmail.com<k name="CR"/></ex>
201 <k>o</k>my.webmail.com<k name="CR"/>
203 <ex>:tabopen google.com<k name="CR"/></ex>
204 <k>t</k>google.com<k name="CR"/>
207 <h2 tag="hints-tutorial">Some hints about surfing…</h2>
210 So now you can navigate around in &dactyl.appName;. But wait… how do you <em>open</em> a
211 page or tab linked in a web page? How do you <em>click</em> on all those links
212 without your tailed friend?
216 The answer is <t>hints</t>. Activating hints displays a number next to
217 every link (or other element, depending on the mode) &dactyl.appName; can
218 find. To act on the element (e.g., follow or save a link), simply type
219 the number corresponding to the hint.
223 For text links, there's an additional shortcut; you can type some text
224 contained in the link and &dactyl.appName; will search all the links it can find and
225 only hint the matching links, further narrowing down the list. If the text you
226 type uniquely identifies any given link, &dactyl.appName; will follow that link
227 immediately without any further user input.
231 Whichever way you choose to indicate your target link, once &dactyl.appName; has
232 highlighted the link you want, simply hit <k name="CR" link="false"/> to open it.
236 To activate Hints mode, press either <k>f</k> or <k>F</k>. The lower-case
237 <k>f</k> will open the resulting link in the current tab, while the
238 upper-case <k>F</k> will open it in a new tab.
242 Extended hint modes, started by <k>;</k> or <k>g;</k>, provide a richer way
243 to interact with various elements, not limited to following links.
247 To test it, try this link: <link topic="&dactyl.apphome;">&dactyl.appName; Homepage</link>.
248 Activate Hints mode with <k>f</k> or <k>F</k> to highlight all currently
249 visible links. Then start typing the text of the link. The link should be
250 uniquely identified soon, and &dactyl.appName; will open it. Once you're
251 done, remember to use <k>H</k> (<em>History Back</em>) or <k>d</k>
252 (<em>Delete Buffer</em>) to return here, depending on which key you used to
256 <h2 tag="saving-customization">Saving for posterity—<tt>pentadactylrc</tt></h2>
259 Once you get &dactyl.appName; set up with your desired options, maps, and commands,
260 you'll probably want them to be available the next time you open &dactyl.appName;.
261 Continuing the Vim theme, this is done with a <tt><t>pentadactylrc</t></tt> file.
265 To save your current settings and allow them to be loaded automatically
266 next time you start &dactyl.appName;, issue the <ex>:mkp</ex> command.
270 This will create the file <em>$HOME/.pentadactylrc</em> containing your settings.
271 It is a simple text file, just like a vimrc file and can be easily
272 edited to suit your preferences.
275 <h2 tag="quitting-without-menus">Find the exit nearest you</h2>
278 &dactyl.appName; supports all of Vim's classic methods of exiting.
282 <dt><ex>:xall</ex></dt>
284 quit and save the current browsing session for next time; the default
286 <dt><ex>:exit</ex></dt>
288 quit <em>without</em> saving the session
292 Normal mode mapping equivalent to <ex>:xall</ex>
296 Normal mode mapping equivalent to <ex>:exit</ex>
300 <h2 tag="whither-&dactyl.host;">Where did &dactyl.host; go?</h2>
303 You might feel pretty disoriented now. Don't worry. This is still
304 &dactyl.host; underneath. Here are some ways &dactyl.appName; allows
305 &dactyl.host; to shine through (see the <ex>:help</ex> for these commands
306 and mappings for more information on how to make the best use of them):
310 <dt><ex>:dialog</ex></dt>
312 To access some of &dactyl.host;'s many dialog windows, you can use the
313 <ex>:dialog</ex> command. See <ex>:help :dialog</ex>.
315 <dt><ex>:bmarks</ex></dt>
317 &dactyl.appName; provides a new interface to bookmarks, but they're still your
318 standard &dactyl.host; bookmarks under the hood. <ex>:bmark</ex> will add a new
319 bookmark, while <ex>:bmarks</ex> will list the bookmarks currently defined.
321 <dt><ex>:history</ex></dt>
323 It's exactly what it sounds like. This command will display a colorized,
324 scrollable and clickable list of the locations in &dactyl.appName;'s history.
326 <dt><ex>:emenu</ex></dt>
328 Access the &dactyl.host; menus through the &dactyl.appName; command line.
333 Feel free to explore at this point. If you get hopelessly lost, just type
334 <ex>:help<k name="CR"/></ex> and click the <em>Quick-start tutorial</em>
338 <!-- TODO: other sections? -->
340 <h2 tag="removal">Get me out of here!</h2>
343 If you've given it a fair shot and determined that &dactyl.appName; is not
344 for you after all, you might want to disable it.
348 The &dactyl.appName; way to do this is with the command <ex>:addons</ex>,
349 which displays a list of all installed extensions. You can use hints or
350 mouse to click on <em>Off</em> or <em>Del</em> to disable or remove
351 &dactyl.appName;, respectively.
355 Alternatively, you can do this the old-fashioned way: re-enable the menubar,
356 as above, with <se opt="go" op="+=">m</se>, and select <em>Add-ons</em>
357 from the <em>Tools</em> menu. You can also use <ex>:dialog addons</ex> to
358 get to the interface.
361 <h2 tag="support">I'm interested… but lost!</h2>
364 &dactyl.appName; has an energetic and growing user base. If you've run into
365 a problem that you can't seem to solve with &dactyl.appName;, or if you
366 think you might have found a bug, please let us know! There is support
367 available on the <link topic="&dactyl.list.href;">mailing list</link>
368 (mirrored on <link topic="http://dir.gmane.org/gmane.comp.mozilla.firefox.pentadactyl">Gmane</link>)
369 or in the <link topic="irc://irc.oftc.net/pentadactyl">#pentadactyl</link> IRC
370 channel on <link topic="http://oftc.net/">OFTC</link>. See also
375 If you have any feature requests or (even better) offers to help, we'd love to
376 hear from you as well. Developers work on &dactyl.appName; whenever possible, but we
377 are neither infinite nor omnipotent; please bear with us. If you can't wait for
378 us to get around to it, rest assured patches are welcome! See the
379 <t>developer</t> page for more information.
384 <!-- vim:se sts=4 sw=4 et: -->