Import 1.0b7.1 supporting Firefox up to 8.*

[dactyl.git] / pentadactyl / locale / en-US / tutorial.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>

<!DOCTYPE document SYSTEM "dactyl://content/dtd">

<document
    name="tutorial"
    title="&dactyl.appName; Tutorial"
    xmlns="&xmlns.dactyl;"
    xmlns:html="&xmlns.html;">

<!-- Initial revision: Sun Jun  8 10:07:05 UTC 2008 (penryu) -->
<h1 tag="tutorial">Quick-start tutorial</h1>

<note>
    This is a quickstart tutorial to help new users get up and running
    in &dactyl.appName;. It is not intended as a full reference explaining all
    features.
</note>

<p>
    If you've started using &dactyl.appName; from scratch (i.e., without any
    customization), you should be looking at this help page in a relatively
    bare-looking window. The menubar, navigation bar, and bookmark bars are hidden.
    In case you missed the notice in the <t>intro</t>, you can
    regain these by issuing the command
</p>

<set opt="go" op="+="><str delim="">mTB</str><k name="CR"/></set>

<p>
    where <k name="CR"/> represents pressing the <k name="Enter" link="false"/>
    or <k name="Return" link="false"/> key. If you're a veteran Vim user, this
    may look familiar. It should.
</p>

<p>
    However, in this author's opinion, the best way to get familiar with
    &dactyl.appName; is to leave these disabled for now. (The above action can be
    reversed with <se opt="go" op="&amp;"/><k name="CR"/>) You can look at the entry
    for <o>guioptions</o> in <t>options</t> for more information on this.
</p>

<h2 tag="modal">&dactyl.appName;'s modal interface</h2>

<p>
    &dactyl.appName;'s power, like Vim's, comes from its modal interface. Keys have
    different meanings depending on which mode the browser is in. &dactyl.appName; has
    several modes, but the 2 most important are <em>Normal</em> mode and
    <em>Command Line</em> mode.
</p>

<p>
    When &dactyl.appName; starts, it is in Normal mode by default. This is probably where
    you will spend the majority of your time.
</p>

<p>
    The other core mode of &dactyl.appName;, Command Line mode, can be entered from
    Normal mode by typing a <k>:</k> (colon). You will frequently see &dactyl.appName;
    commands start with a <k>:</k>, indicating that what follows is a command.
</p>

<p>
    To return to Normal mode from Command Line mode, type <k name="Esc"/>. Pressing
    <k name="Esc"/> will also return you to Normal mode from most other modes in
    &dactyl.appName;.
</p>

<h2 tag="getting-help">Getting help</h2>

<p>
    Vim is a great editor but it's not much of a web browser. So even seasoned Vim
    users will probably have to look at &dactyl.appName;'s documentation sooner or later.
    Most of the documentation for &dactyl.appName;'s features are easily found using the
    <ex>:help</ex> command. For example, you can find help on the <ex>:help</ex> command
    by typing
</p>

<code><ex>:help :help<k name="CR"/></ex></code>

<p>
    Similarly, help on configurable options is available with
    <ex>:help '<a>option_name</a>'</ex>. (Note the single quotes
    around the option name as in Vim.) Information on all available
    options is, predictably, <ex>:help options</ex>.
</p>

<p>
    And you can find out about the <k>gt</k> and <k>gT</k> mapping with
</p>

<code>
<ex>:help gt<k name="CR"/></ex>
<ex>:help gT<k name="CR"/></ex>
</code>

<p>
    Finally, in addition to the help system itself, <ex>:listcommands</ex>,
    <ex>:listkeys</ex> and <ex>:listoptions</ex> are useful quick-reference
    commands.
</p>

<h2 tag="living-mouseless">Mouseless</h2>

<em>– or how I learned to stop worrying and love the 80+ buttons I already have.</em>

<p>
    The efficiency of &dactyl.appName;, as with the legendary editor it was inspired by,
    relies on the user being able to keep his fingers on the keyboard where they
    can do the most good. While there are some areas where the mouse is clearly
    superior at, such as GUI design or some games, &dactyl.appName; acts on the
    assumption that a web browser doesn't have to be one of those.
</p>

<p>
    Here are some areas where the mouse is typically considered indisposable, and
    how &dactyl.appName; challenges this preconception.
</p>

<h2 tag="keyboard-scrolling">Scrolling</h2>

<p>
    Scrolling the browser window is done with simple keystrokes:
</p>

<dl>
    <dt><k>j</k>/<k>k</k></dt>
    <dd>
        scroll window down/up by one line, respectively
    </dd>
    <dt><k>h</k>/<k>l</k></dt>
    <dd>
        scroll window left/right
    </dd>
    <dt><k name="Space"/>/<k name="C-b"/></dt>
    <dd>
        scroll down/up by one page
    </dd>
    <dt><k name="C-d"/>/<k name="C-u"/></dt>
    <dd>
        scroll down/up by 1/2 page
    </dd>
</dl>

<p>
    Your standard buttons (<k name="Up"/>/<k name="Down"/>/<k name="PageUp"/>/<k name="PageDown"/>) will
    also work as expected.
</p>

<h2 tag="history-navigation tab-navigation">History and tabs</h2>

<p>
    History navigation (e.g., <em>Back</em>, <em>Forward</em>) are done similarly to
    scrolling.
</p>

<dl>
    <dt><k name="C-o"/>/<k name="C-i"/></dt>
    <dd>
        move Back/Forward in the current window/tab's history, respectively
    </dd>
</dl>

<p>
    Move between tabs using these keystrokes which may also be familiar to tabbing
    Vimmers.
</p>

<dl>
    <dt><k>gt</k>/<k name="C-n"/></dt>
    <dd>
        go to the next tab
    </dd>
    <dt><k>gT</k>/<k name="C-p"/></dt>
    <dd>
        go to the previous tab
    </dd>
    <dt><k>g0</k>/<k>g$</k></dt>
    <dd>
        go to the first/last tab
    </dd>
    <dt><k>d</k></dt>
    <dd>
        close the active tab (delete the buffer)
    </dd>
</dl>

<p>
    To open a web page in a new tab, use the <ex>:tabopen <a>url</a></ex>. To open a URL in
    the current tab, use <ex>:open</ex>. The Normal mode mappings <k>t</k> and <k>o</k>,
    respectively, map to these commands, so the following pairs of sequences are
    equivalent:
</p>

<code>
<ex>:open my.webmail.com<k name="CR"/></ex>
<k>o</k>my.webmail.com<k name="CR"/>

<ex>:tabopen google.com<k name="CR"/></ex>
<k>t</k>google.com<k name="CR"/>
</code>

<h2 tag="hints-tutorial">Some hints about surfing…</h2>

<p>
    So now you can navigate around in &dactyl.appName;. But wait… how do you <em>open</em> a
    page or tab linked in a web page? How do you <em>click</em> on all those links
    without your tailed friend?
</p>

<p>
    The answer is <em>hints</em>. Activating hints displays a number next to every link
    &dactyl.appName; can find. To follow the link, simply type the number corresponding
    to the hint.
</p>

<p>
    For text links, there's an additional shortcut; you can type some text
    contained in the link and &dactyl.appName; will search all the links it can find and
    only hint the matching links, further narrowing down the list. If the text you
    type uniquely identifies any given link, &dactyl.appName; will follow that link
    immediately without any further user input.
</p>

<p>
    Whichever way you choose to indicate your target link, once &dactyl.appName; has
    highlighted the link you want, simply hit <k name="CR"/> to open it.
</p>

<p>
    To activate Hints mode, press either <k>f</k> or <k>F</k>. The lower-case
    <k>f</k> will open the resulting link in the current tab, while the
    upper-case <k>F</k> will open it in a new tab.
</p>

<p>
    To test it, try this link: <link topic="&dactyl.apphome;">&dactyl.appName; Homepage</link>.
    Activate Hints mode with <k>f</k> or <k>F</k> to highlight all currently
    visible links. Then start typing the text of the link. The link should be
    uniquely identified soon, and &dactyl.appName; will open it. Once you're
    done, remember to use <k name="C-o"/> (<em>History Back</em>) or <k>d</k>
    (<em>Delete Buffer</em>) to return here, depending on which key you used to
    activate Hints mode.
</p>

<h2 tag="common-issues">Common issues</h2>

<p>
    Say you get half-way done typing in a new URL, only to remember that you've
    already got that page open in the previous tab. Your command line might look
    something like this:
</p>

<code><ex>:open my.partial.url/fooba</ex></code>

<p>
    You can exit the command line and access the already loaded page with the
    following:
</p>

<code><k name="Esc"/></code>

<h2 tag="pentadactylrc">Saving for posterity—<tt>pentadactylrc</tt></h2>

<p>
    Once you get &dactyl.appName; set up with your desired options, maps, and commands,
    you'll probably want them to be available the next time you open &dactyl.appName;.
    Continuing the Vim theme, this is done with a <tt>pentadactylrc</tt> file.
</p>

<p>
    To save your current settings and allow them to be loaded automatically
    next time you start &dactyl.appName;, issue the <ex>:mkp</ex> command.
</p>

<p>
    This will create the file <em>$HOME/.pentadactylrc</em> containing your settings.
    It is a simple text file, just like a vimrc file and can be easily
    edited to suit your preferences.
</p>

<h2 tag="quitting-without-menus">Find the exit nearest you</h2>

<p>
    &dactyl.appName; supports all of Vim's classic methods of exiting.
</p>

<dl>
    <dt><ex>:xall</ex></dt>
    <dd>
        command to quit and save the current browsing session for next time; the default.
    </dd>
    <dt><ex>:qall</ex></dt>
    <dd>
        command to quit <em>without</em> saving the session
    </dd>
    <dt><k>ZZ</k></dt>
    <dd>
        Normal mode mapping equivalent to <ex>:xall</ex>
    </dd>
    <dt><k>ZQ</k></dt>
    <dd>
        Normal mode mapping equivalent to <ex>:qall</ex>
    </dd>
</dl>

<h2 tag="whither-&dactyl.host;">Where did &dactyl.host; go?</h2>

<p>
    You might feel pretty disoriented now. Don't worry. This is still &dactyl.host;
    underneath. Here are some ways &dactyl.appName; allows &dactyl.host; to shine through. See
    the <ex>:help</ex> for these commands and mappings for more information on how to
    make the best use of them.
</p>

<dl>
    <dt><ex>:dialog</ex></dt>
    <dd>
        To access some of &dactyl.host;'s many dialog windows, you can use the
        <ex>:dialog</ex> command. See <ex>:help :dialog</ex>.
    </dd>
    <dt><ex>:bmarks</ex></dt>
    <dd>
        &dactyl.appName; provides a new interface to bookmarks, but they're still your
        standard &dactyl.host; bookmarks under the hood. <ex>:bmark</ex> will add a new
        bookmark, while <ex>:bmarks</ex> will list the bookmarks currently defined.
    </dd>
    <dt><ex>:history</ex></dt>
    <dd>
        It's exactly what it sounds like. This command will display a colorized,
        scrollable and clickable list of the locations in &dactyl.appName;'s history.
    </dd>
    <dt><ex>:emenu</ex></dt>
    <dd>
        Access the &dactyl.host; menus through the &dactyl.appName; command line.
    </dd>
</dl>

<p>
    Feel free to explore at this point. If you use the <ex>:tabopen</ex> command,
    remember to use the <k>gt</k>/<k>gT</k> mappings to get back to this page. If
    using the <ex>:open</ex> command, use the history keys (e.g., <k>H</k>) to return.
    If you get hopelessly lost, just type <ex>:help<k name="CR"/></ex> and click the
    <em>Tutorial</em> link to return.
</p>

<!-- TODO: other sections? -->

<h2 tag="removal">Get me out of here!</h2>

<p>
    If you've given it a fair shot and determined … TODO
</p>

<p>
    The &dactyl.appName; way to do this is with the command <ex>:addons</ex>. Issuing this
    command brings up the &dactyl.host; Add-ons dialog window; you can then remove it as
    normal, selecting &dactyl.appName; from the list and clicking (yes, clicking)
    <em>Uninstall</em>.
</p>

<p>
    Alternatively, you can do this the old-fashioned way: re-enable the menubar,
    as above, with <se opt="go" op="+=">m</se>, and select <em>Add-ons</em> from the <em>Tools</em> menu.
</p>

<h2 tag="support">I'm interested… but lost!</h2>

<p>
    &dactyl.appName; has an energetic and growing user base. If you've run into a problem
    that you can't seem to solve with &dactyl.appName;, or if you think you might have
    found a bug, please let us know! There is support available on the
    <link topic="http://code.google.com/p/dactyl/w/list?q=label%3Aproject-&dactyl.name;">wiki</link>
    or in the <link topic="irc://irc.oftc.net/pentadactyl">#pentadactyl</link> IRC
    channel on <link topic="http://oftc.net/">OFTC</link>.
</p>

<p>
    If you have any feature requests or (even better) offers to help, we'd love to
    hear from you as well. Developers work on &dactyl.appName; whenever possible, but we
    are neither infinite nor omnipotent; please bear with us. If you can't wait for
    us to get around to it, rest assured patches are welcome! See the
    <link topic="developer">developer</link> page for more information.
</p>

</document>

<!-- vim:se sts=4 sw=4 et: -->