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 <!-- Initial revision: Sun Jun 8 10:07:05 UTC 2008 (penryu) -->
13 <h1 tag="tutorial">Quick-start tutorial</h1>
16 This is a quickstart tutorial to help new users get up and running
17 in &dactyl.appName;. It is not intended as a full reference explaining all
22 If you've started using &dactyl.appName; from scratch (i.e., without any
23 customization), you should be looking at this help page in a relatively
24 bare-looking window. The menubar, navigation bar, and bookmark bars are hidden.
25 In case you missed the notice in the <t>intro</t>, you can
26 regain these by issuing the command
29 <set opt="go" op="+="><str delim="">mTB</str><k name="CR"/></set>
32 where <k name="CR"/> represents pressing the <k name="Enter" link="false"/>
33 or <k name="Return" link="false"/> key. If you're a veteran Vim user, this
34 may look familiar. It should.
38 However, in this author's opinion, the best way to get familiar with
39 &dactyl.appName; is to leave these disabled for now. (The above action can be
40 reversed with <se opt="go" op="&"/><k name="CR"/>) You can look at the entry
41 for <o>guioptions</o> in <t>options</t> for more information on this.
44 <h2 tag="modal">&dactyl.appName;'s modal interface</h2>
47 &dactyl.appName;'s power, like Vim's, comes from its modal interface. Keys have
48 different meanings depending on which mode the browser is in. &dactyl.appName; has
49 several modes, but the 2 most important are <em>Normal</em> mode and
50 <em>Command Line</em> mode.
54 When &dactyl.appName; starts, it is in Normal mode by default. This is probably where
55 you will spend the majority of your time.
59 The other core mode of &dactyl.appName;, Command Line mode, can be entered from
60 Normal mode by typing a <k>:</k> (colon). You will frequently see &dactyl.appName;
61 commands start with a <k>:</k>, indicating that what follows is a command.
65 To return to Normal mode from Command Line mode, type <k name="Esc"/>. Pressing
66 <k name="Esc"/> will also return you to Normal mode from most other modes in
70 <h2 tag="getting-help">Getting help</h2>
73 Vim is a great editor but it's not much of a web browser. So even seasoned Vim
74 users will probably have to look at &dactyl.appName;'s documentation sooner or later.
75 Most of the documentation for &dactyl.appName;'s features are easily found using the
76 <ex>:help</ex> command. For example, you can find help on the <ex>:help</ex> command
80 <code><ex>:help :help<k name="CR"/></ex></code>
83 Similarly, help on configurable options is available with
84 <ex>:help '<a>option_name</a>'</ex>. (Note the single quotes
85 around the option name as in Vim.) Information on all available
86 options is, predictably, <ex>:help options</ex>.
90 And you can find out about the <k>gt</k> and <k>gT</k> mapping with
94 <ex>:help gt<k name="CR"/></ex>
95 <ex>:help gT<k name="CR"/></ex>
99 Finally, in addition to the help system itself, <ex>:listcommands</ex>,
100 <ex>:listkeys</ex> and <ex>:listoptions</ex> are useful quick-reference
104 <h2 tag="living-mouseless">Mouseless</h2>
106 <em>– or how I learned to stop worrying and love the 80+ buttons I already have.</em>
109 The efficiency of &dactyl.appName;, as with the legendary editor it was inspired by,
110 relies on the user being able to keep his fingers on the keyboard where they
111 can do the most good. While there are some areas where the mouse is clearly
112 superior at, such as GUI design or some games, &dactyl.appName; acts on the
113 assumption that a web browser doesn't have to be one of those.
117 Here are some areas where the mouse is typically considered indisposable, and
118 how &dactyl.appName; challenges this preconception.
121 <h2 tag="keyboard-scrolling">Scrolling</h2>
124 Scrolling the browser window is done with simple keystrokes:
128 <dt><k>j</k>/<k>k</k></dt>
130 scroll window down/up by one line, respectively
132 <dt><k>h</k>/<k>l</k></dt>
134 scroll window left/right
136 <dt><k name="Space"/>/<k name="C-b"/></dt>
138 scroll down/up by one page
140 <dt><k name="C-d"/>/<k name="C-u"/></dt>
142 scroll down/up by 1/2 page
147 Your standard buttons (<k name="Up"/>/<k name="Down"/>/<k name="PageUp"/>/<k name="PageDown"/>) will
148 also work as expected.
151 <h2 tag="history-navigation tab-navigation">History and tabs</h2>
154 History navigation (e.g., <em>Back</em>, <em>Forward</em>) are done similarly to
159 <dt><k name="C-o"/>/<k name="C-i"/></dt>
161 move Back/Forward in the current window/tab's history, respectively
166 Move between tabs using these keystrokes which may also be familiar to tabbing
171 <dt><k>gt</k>/<k name="C-n"/></dt>
175 <dt><k>gT</k>/<k name="C-p"/></dt>
177 go to the previous tab
179 <dt><k>g0</k>/<k>g$</k></dt>
181 go to the first/last tab
185 close the active tab (delete the buffer)
190 To open a web page in a new tab, use the <ex>:tabopen <a>url</a></ex>. To open a URL in
191 the current tab, use <ex>:open</ex>. The Normal mode mappings <k>t</k> and <k>o</k>,
192 respectively, map to these commands, so the following pairs of sequences are
197 <ex>:open my.webmail.com<k name="CR"/></ex>
198 <k>o</k>my.webmail.com<k name="CR"/>
200 <ex>:tabopen google.com<k name="CR"/></ex>
201 <k>t</k>google.com<k name="CR"/>
204 <h2 tag="hints-tutorial">Some hints about surfing…</h2>
207 So now you can navigate around in &dactyl.appName;. But wait… how do you <em>open</em> a
208 page or tab linked in a web page? How do you <em>click</em> on all those links
209 without your tailed friend?
213 The answer is <em>hints</em>. Activating hints displays a number next to every link
214 &dactyl.appName; can find. To follow the link, simply type the number corresponding
219 For text links, there's an additional shortcut; you can type some text
220 contained in the link and &dactyl.appName; will search all the links it can find and
221 only hint the matching links, further narrowing down the list. If the text you
222 type uniquely identifies any given link, &dactyl.appName; will follow that link
223 immediately without any further user input.
227 Whichever way you choose to indicate your target link, once &dactyl.appName; has
228 highlighted the link you want, simply hit <k name="CR"/> to open it.
232 To activate Hints mode, press either <k>f</k> or <k>F</k>. The lower-case
233 <k>f</k> will open the resulting link in the current tab, while the
234 upper-case <k>F</k> will open it in a new tab.
238 To test it, try this link: <link topic="&dactyl.apphome;">&dactyl.appName; Homepage</link>.
239 Activate Hints mode with <k>f</k> or <k>F</k> to highlight all currently
240 visible links. Then start typing the text of the link. The link should be
241 uniquely identified soon, and &dactyl.appName; will open it. Once you're
242 done, remember to use <k name="C-o"/> (<em>History Back</em>) or <k>d</k>
243 (<em>Delete Buffer</em>) to return here, depending on which key you used to
247 <h2 tag="common-issues">Common issues</h2>
250 Say you get half-way done typing in a new URL, only to remember that you've
251 already got that page open in the previous tab. Your command line might look
255 <code><ex>:open my.partial.url/fooba</ex></code>
258 You can exit the command line and access the already loaded page with the
262 <code><k name="Esc"/></code>
264 <h2 tag="pentadactylrc">Saving for posterity—<tt>pentadactylrc</tt></h2>
267 Once you get &dactyl.appName; set up with your desired options, maps, and commands,
268 you'll probably want them to be available the next time you open &dactyl.appName;.
269 Continuing the Vim theme, this is done with a <tt>pentadactylrc</tt> file.
273 To save your current settings and allow them to be loaded automatically
274 next time you start &dactyl.appName;, issue the <ex>:mkp</ex> command.
278 This will create the file <em>$HOME/.pentadactylrc</em> containing your settings.
279 It is a simple text file, just like a vimrc file and can be easily
280 edited to suit your preferences.
283 <h2 tag="quitting-without-menus">Find the exit nearest you</h2>
286 &dactyl.appName; supports all of Vim's classic methods of exiting.
290 <dt><ex>:xall</ex></dt>
292 command to quit and save the current browsing session for next time; the default.
294 <dt><ex>:qall</ex></dt>
296 command to quit <em>without</em> saving the session
300 Normal mode mapping equivalent to <ex>:xall</ex>
304 Normal mode mapping equivalent to <ex>:qall</ex>
308 <h2 tag="whither-&dactyl.host;">Where did &dactyl.host; go?</h2>
311 You might feel pretty disoriented now. Don't worry. This is still &dactyl.host;
312 underneath. Here are some ways &dactyl.appName; allows &dactyl.host; to shine through. See
313 the <ex>:help</ex> for these commands and mappings for more information on how to
314 make the best use of them.
318 <dt><ex>:dialog</ex></dt>
320 To access some of &dactyl.host;'s many dialog windows, you can use the
321 <ex>:dialog</ex> command. See <ex>:help :dialog</ex>.
323 <dt><ex>:bmarks</ex></dt>
325 &dactyl.appName; provides a new interface to bookmarks, but they're still your
326 standard &dactyl.host; bookmarks under the hood. <ex>:bmark</ex> will add a new
327 bookmark, while <ex>:bmarks</ex> will list the bookmarks currently defined.
329 <dt><ex>:history</ex></dt>
331 It's exactly what it sounds like. This command will display a colorized,
332 scrollable and clickable list of the locations in &dactyl.appName;'s history.
334 <dt><ex>:emenu</ex></dt>
336 Access the &dactyl.host; menus through the &dactyl.appName; command line.
341 Feel free to explore at this point. If you use the <ex>:tabopen</ex> command,
342 remember to use the <k>gt</k>/<k>gT</k> mappings to get back to this page. If
343 using the <ex>:open</ex> command, use the history keys (e.g., <k>H</k>) to return.
344 If you get hopelessly lost, just type <ex>:help<k name="CR"/></ex> and click the
345 <em>Tutorial</em> link to return.
348 <!-- TODO: other sections? -->
350 <h2 tag="removal">Get me out of here!</h2>
353 If you've given it a fair shot and determined … TODO
357 The &dactyl.appName; way to do this is with the command <ex>:addons</ex>. Issuing this
358 command brings up the &dactyl.host; Add-ons dialog window; you can then remove it as
359 normal, selecting &dactyl.appName; from the list and clicking (yes, clicking)
364 Alternatively, you can do this the old-fashioned way: re-enable the menubar,
365 as above, with <se opt="go" op="+=">m</se>, and select <em>Add-ons</em> from the <em>Tools</em> menu.
368 <h2 tag="support">I'm interested… but lost!</h2>
371 &dactyl.appName; has an energetic and growing user base. If you've run into a problem
372 that you can't seem to solve with &dactyl.appName;, or if you think you might have
373 found a bug, please let us know! There is support available on the
374 <link topic="http://code.google.com/p/dactyl/w/list?q=label%3Aproject-&dactyl.name;">wiki</link>
375 or in the <link topic="irc://irc.oftc.net/pentadactyl">#pentadactyl</link> IRC
376 channel on <link topic="http://oftc.net/">OFTC</link>.
380 If you have any feature requests or (even better) offers to help, we'd love to
381 hear from you as well. Developers work on &dactyl.appName; whenever possible, but we
382 are neither infinite nor omnipotent; please bear with us. If you can't wait for
383 us to get around to it, rest assured patches are welcome! See the
384 <link topic="developer">developer</link> page for more information.
389 <!-- vim:se sts=4 sw=4 et: -->