path: root/common/locale/en-US/browsing.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="browsing"
    title="&dactyl.appName; Browsing"
    xmlns="&xmlns.dactyl;"
    xmlns:html="&xmlns.html;">

<h1 tag="surfing browsing">Browsing</h1>
<toc start="2"/>

<h2 tag="bypassing-&dactyl.name;">Bypassing &dactyl.appName;</h2>

&dactyl.appName; overrides nearly all &dactyl.host; keys in order to
make browsing more pleasant for Vim users. On the occasions when you
want to bypass &dactyl.appName;'s key handling and pass keys directly to
&dactyl.host; or to a web page, you have two options:

<item>
    <tags><![CDATA[pass-through <pass-all-keys> <C-z> CTRL-Z]]></tags>
    <spec>&lt;C-z></spec>
    <description>
        <p>
            Pass all keys except for <k name="Esc"/> directly to
            &dactyl.host;. When <k name="Esc"/> is pressed,
            resume normal key handling. This is especially useful
            for web sites which make heavy use of key bindings.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[send-key <pass-next-key> <C-v> CTRL-V]]></tags>
    <spec>&lt;C-v></spec>
    <description>
        <p>
            Pass the next key press directly to &dactyl.host;.
        </p>
    </description>
</item>

<h2 tag="opening">Opening web pages</h2>

<item>
    <tags>o :o :open</tags>
    <spec>:o<oa>pen</oa> <oa>args</oa></spec>
    <spec>o</spec>
    <description>
        <p>
            Open a single URL in the current tab, or multiple URLs
            in the current tab and background tabs. URLs may be
            separated with <o>urlseparator</o>, in which case the
            first URL is opened in the current tab and the rest are
            opened in new background tabs.
        </p>

        <p>
            Each URL may be one of the following:
        </p>

        <ol>
            <li>
                A local filename, if it begins with <em>/</em>,
                <em>./</em>, or <em>~/</em> and the specified file
                exists.
            </li>
            <li>
                <p>
                    A search or bookmark keyword, or a search engine
                    name, followed by search arguments.
                </p>
                <example><ex>:open wikipedia Linus Torvalds</ex></example>
                <p>
                    Search engines can be edited via
                    <ex>:dialog searchengines</ex> and search
                    keywords may be added by right clicking any
                    search box and selecting <str>Add a Keyword for
                    this Search</str>.
                </p>
            </li>
            <li>
                <p>
                    Any search string which does not look like a URL or
                    hostname, which will be passed to the default
                    search engine (see <o>defsearch</o>).
                </p>
                <example><ex>:open Linus Torvalds</ex></example>
           </li>
           <li>
               Any other value is passed directly &dactyl.host; and
               must be a valid URL or hostname.
           </li>
        </ol>

        <p>
            <ex>:open</ex> provides powerful URL completion from
            several possible sources, which can be adjusted via the
            <o>complete</o> option.
        </p>
    </description>
</item>

<item>
    <tags>t :t :tabopen :tabnew</tags>
    <spec>:tabopen<oa>!</oa> <oa>args</oa></spec>
    <spec>t</spec>
    <description>
        <p>
            Like <ex>:open</ex>, but all arguments are opened in new
            tabs. The first new tab is activated if <o>activate</o>
            contains <str>tabopen</str> or <oa>!</oa> is provided.
        </p>
    </description>
</item>

<item>
    <tags>T</tags>
    <spec>T</spec>
    <description short="true">
        <p>
            Open a <ex>:tabopen</ex> prompt followed by the current URL.
        </p>
    </description>
</item>

<item>
    <tags>:tabdu :tabduplicate</tags>
    <spec>:<oa>count</oa>tabdu<oa>plicate</oa><oa>!</oa></spec>
    <description>
        <p>
            Duplicates current tab <oa>count</oa> times. The first
            new tab is activated if <o>activate</o> contains
            <str>tabopen</str> or <oa>!</oa> is provided.
        </p>
    </description>
</item>

<item>
    <tags>O</tags>
    <spec>O</spec>
    <description short="true">
        <p>
            Open an <ex>:open</ex> prompt followed by the current URL.
        </p>
    </description>
</item>

<item>
    <tags>w :winopen :wopen</tags>
    <spec>:wino<oa>pen</oa><oa>!</oa> <oa>args</oa></spec>
    <spec>w</spec>
    <description>
        <p>
            Like <ex>:tabopen</ex>, but all arguments are opened in
            a single new window.
        </p>
    </description>
</item>

<item>
    <tags>W</tags>
    <spec>W</spec>
    <description short="true">
        <p>
            Open a <ex>:winopen</ex> prompt followed by the current URL.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<open-clipboard-url> <MiddleMouse> p]]></tags>
    <strut/>
    <spec>p</spec>
    <description>
        <p>
            Open (put) a URL based on the current clipboard
            contents, or, on X11 systems, the currently selected
            text. All white space is stripped from the selection and
            it is opened in the same manner as <ex>:open</ex>.
        </p>
    </description>
</item>

<item>
    <tags>&lt;tab-open-clipboard-url> P</tags>
    <strut/>
    <spec>P</spec>
    <description>
        <p>
            Open (put) a URL based on the current clipboard contents
            in a new buffer. Works like <k>p</k> but opens a new
            tab. The new tab is activated if <o>activate</o>
            contains <str>paste</str>.
        </p>
    </description>
</item>

<item>
    <tags>gP</tags>
    <strut/>
    <spec>gP</spec>
    <description>
        <p>
            Open (put) a URL based on the current clipboard contents
            in a new buffer. The new tab is activated if <o>activate</o>
            does <em>not</em> contain <str>paste</str>.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<C-x>]]></tags>
    <strut/>
    <spec><oa>count</oa>&lt;C-x></spec>
    <description>
        <p>
            Decrements the last number in URL by 1, or by
            <oa>count</oa> if given. Negative numbers are not
            supported as trailing numbers in URLs are often preceded
            by hyphens.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<C-a>]]></tags>
    <strut/>
    <spec><oa>count</oa>&lt;C-a></spec>
    <description>
        <p>
            Increments the last number in URL by 1, or by
            <oa>count</oa> if given.
        </p>
    </description>
</item>

<item>
    <tags>~</tags>
    <spec>~</spec>
    <description short="true">
        <p>Open home directory. Equivalent to <ex>:open ~/</ex></p>
    </description>
</item>

<h2 tag="navigating">Navigating</h2>

<item>
    <tags><![CDATA[H <C-o> CTRL-O :ba :back]]></tags>
    <spec>:<oa>count</oa>ba<oa>ck</oa> <oa>url</oa></spec>
    <spec>:ba<oa>ck</oa>!</spec>
    <spec><oa>count</oa>&lt;C-o></spec>
    <description>
        <p>
            Go <oa>count</oa> pages back in the browser history. If
            <oa>url</oa> is specified go back to the first matching
            URL. The special version <ex>:back!</ex> goes to the
            beginning of the browser history.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[L <C-i> CTRL-I :fo :fw :forward]]></tags>
    <spec>:<oa>count</oa>fo<oa>rward</oa> <oa>url</oa></spec>
    <spec>:fo<oa>rward</oa>!</spec>
    <spec><oa>count</oa>&lt;C-i></spec>
    <description>
        <p>
            Go <oa>count</oa> pages forward in the browser history.
            If <oa>url</oa> is specified go forward to the first
            matching URL. The special version <ex>:forward!</ex>
            goes to the end of the browser history.
        </p>
    </description>
</item>

<item>
    <tags>:ju :jumps</tags>
    <spec>:ju<oa>mps</oa></spec>
    <description>
        <p>List all jumps, i.e., the current tab's session history.</p>

        <p>
            Current history position is marked with <em>></em>.
            Jump numbers may be used as counts for with
            <ex>:back</ex> or <ex>:forward</ex>.
        </p>
    </description>
</item>

<item>
    <tags>gh</tags>
    <spec>gh</spec>
    <description short="true">
        <p>Go home. Opens the homepage in the current tab.</p>
    </description>
</item>

<item>
    <tags>gH</tags>
    <strut/>
    <spec>gH</spec>
    <description>
        <p>
            Go home in a new tab. Opens the homepage in a new tab.
            The new tab is activated if <o>activate</o> contains
            <str>homepage</str>.
        </p>
    </description>
</item>

<item>
    <tags>gu</tags>
    <spec><oa>count</oa>gu</spec>
    <description short="true">
        <p>Go to <oa>count</oa>th parent directory.</p>

        <p>
            For example, at the URL
            <tt>http://www.example.com/dir1/dir2/file.htm</tt>,
            2<k>gu</k> opens <tt>http://www.example.com/dir1/</tt>.
        </p>
    </description>
</item>

<item>
    <tags>gU</tags>
    <spec>gU</spec>
    <description short="true">
        <p>Go to the root of the web site.</p>

        <p>
            For example, at the URL
            <tt>http://www.example.com/dir1/dir2/file.htm</tt>,
            <k>gU</k> opens <tt>http://www.example.com/</tt>.
        </p>
    </description>
</item>

<h2 tag="reloading">Reloading</h2>

<item>
    <tags>&lt;reload> r</tags>
    <spec>r</spec>
    <description short="true">
        <p>Reload the current web page.</p>
    </description>
</item>

<item>
    <tags>&lt;full-reload> R</tags>
    <spec>R</spec>
    <description short="true">
        <p>Reload the current web page without using the cache.</p>
    </description>
</item>

<item>
    <tags>:reh :rehash</tags>
    <spec>:reh<oa>ash</oa> <oa>arg</oa> …</spec>
    <description>
        <p>
            Reload the &dactyl.appName; add-on, including all code, plugins,
            and configuration. For users running directly from the development
            repository, this is a good way to update to the latest version or
            to test your changes.
        </p>
        <p>
            Any arguments supplied are parsed as command-line arguments as
            specified in <t>startup-options</t>.
        </p>
        <warning>
            Not all plugins are designed to cleanly un-apply during a rehash.
            While official plugins are safe, beware of possible instability
            if you rehash while running third-party plugins.
        </warning>
    </description>
</item>

<item>
    <tags>:re :reload</tags>
    <spec>:re<oa>load</oa><oa>!</oa></spec>
    <description>
        <p>
            Reload current web page. If <oa>!</oa> is given, reload
            without using the cache.
        </p>
    </description>
</item>

<item>
    <tags>:reloada :reloadall</tags>
    <spec>:reloada<oa>ll</oa><oa>!</oa></spec>
    <description>
        <p>
            Reload all tabs. If <oa>!</oa> is given, reload without
            using the cache.
        </p>
    </description>
</item>

<h2 tag="stopping">Stopping</h2>

<item>
    <tags><![CDATA[<C-c> :st :stop]]></tags>
    <spec>&lt;C-c></spec>
    <strut/>
    <spec>:st<oa>op</oa></spec>
    <description short="true">
        <p>Stop loading the current web page.</p>
    </description>
</item>

<item>
    <tags>:stopa :stopall</tags>
    <spec>:stopa<oa>ll</oa></spec>
    <description short="true">
        <p>Stop loading all web pages.</p>
    </description>
</item>

<h2 tag="writing save-file">Writing</h2>

<item>
    <tags>:w :write :sav :saveas</tags>
    <spec>:sav<oa>eas</oa><oa>!</oa> <oa>file</oa></spec>
    <description>
        <p>
            Save current web page to disk. If <oa>file</oa> is omitted, save to
            the page's default filename. If <oa>file</oa> is a directory or ends
            with your platform's path separator, save to the page's default
            filename in that directory. Existing documents will only be
            overwritten if <oa>!</oa> is given.
        </p>
    </description>
</item>

<item>
    <spec>:write >> <a>file</a></spec>
    <description>
        <p>
            Appends the current web page to the file <a>file</a>. The given
            file must already exist.
        </p>
    </description>
</item>

<item>
    <spec>:write !<a>cmd</a></spec>
    <description>
        <p>
            Writes the current web page to <a>cmd</a> and prints the command's
            output.
        </p>
    </description>
</item>

<h2 tag="quitting save-session">Quitting</h2>

<item>
    <tags>:q :quit</tags>
    <strut/>
    <spec>:q<oa>uit</oa></spec>
    <description>
        <p>
            Quit current tab. If this is the last tab in the window,
            close the window.
        </p>
    </description>
</item>

<item>
    <tags>:qa :qall :quita :quitall</tags>
    <strut/>
    <spec>:quita<oa>ll</oa></spec>
    <description>
        <p>
            Quit &dactyl.appName;, no matter how many tabs/windows
            are open. The session is not stored.
        </p>
    </description>
</item>

<item>
    <tags>:wc :wclose :winc :winclose</tags>
    <spec>:winc<oa>lose</oa></spec>
    <description short="true">
        <p>Close the current window.</p>
    </description>
</item>

<item>
    <tags>:winon :winonly</tags>
    <spec>:winon<oa>ly</oa></spec>
    <description short="true">
        <p>Close all windows but the current.</p>
    </description>
</item>

<item>
    <tags>:xa :xall :wq :wqa :wqall</tags>
    <spec>:wqa<oa>ll</oa></spec>
    <strut/>
    <spec>:xa<oa>ll</oa></spec>
    <description short="true">
        <p>Save the current session and quit.</p>
        <note>
            Unlike Vim, <ex>:wq</ex> closes the entire window rather
            than just the current tab.
        </note>
    </description>
</item>

<item>
    <tags>ZQ</tags>
    <spec>ZQ</spec>
    <description short="true">
        <p>Quit and don't save the session. Works like <ex>:qall</ex>.</p>
    </description>
</item>

<item>
    <tags>ZZ</tags>
    <spec>ZZ</spec>
    <description short="true">
        <p>
            Quit &dactyl.appName; and save the session. Works like
            <ex>:xall</ex>.
        </p>
    </description>
</item>

<h2 tag="current-directory">The current directory</h2>

<item>
    <tags>:chd :chdir :cd</tags>
    <strut/>
    <spec>:cd <oa>path</oa></spec>
    <description>
        <p>
            Change the current directory. If <oa>path</oa> is
            <em>-</em>, change to the previous directory. If it is
            omitted, change to the home directory.
        </p>
    </description>
</item>

<item>
    <tags>:pw :pwd</tags>
    <spec>:pw<oa>d</oa></spec>
    <description short="true">
        <p>Print the current directory name.</p>
    </description>
</item>

</document>

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