pentadactyl-pm/vimperator/locale/en-US/tutorial.txt

HEADER

// Initial revision: Sun Jun  8 10:07:05 UTC 2008 (penryu)

+++<div style="text-align: center;">+++
*This is a quickstart tutorial to help get new users up and running in
Vimperator. It is not intended as a full reference explaining all features.*
+++</div>+++

section:Quick-start{nbsp}tutorial[tutorial]

If you've started using Vimperator 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 help:Introduction[intro.html], you can
regain these by issuing the command

  :set go+=mTb<CR>

where [m]<CR>[m] represents pressing the <Enter> or <Return> key.
If you're a veteran Vim user, this may look familiar. It should.

However, in this author's opinion, the best way to get familiar with
Vimperator is to leave these disabled for now. (The above action can be
reversed with [c]:set go=<CR>[c])  You can look at the entry for
[o]guioptions[o] in help:options[options.html] for more information on this.

section:Vimperator's{nbsp}modal{nbsp}interface[modal]

Vimperator's power, like Vim's, comes from it's modal interface. Keys have
different meanings depending on which mode the browser is in. Vimperator has
several modes, but the 2 most important are ``normal'' mode and
``command-line'' mode.

When Vimperator starts, it is in normal mode by default. This is probably where
you will spend the majority of your time.

The other core mode of Vimperator, command-line mode, can be entered from
normal mode by typing a \':' (colon). You will frequently see Vimperator
commands start with a \':', indicating that what follows is a command.

To return to normal mode command-line mode, type [m]<Esc>[m]. Pressing
[m]<Esc>[m] will also return you to normal mode from most other modes in
Vimperator.

section:Getting{nbsp}help[getting-help]

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 Vimperator documentation sooner or later.
Most of the documentation for Vimperator's features are easily found using the
[c]:help[c] command. For example, you can find help on the [c]:help[c] command
by typing

  :help :help<CR>

Similarly, help on configurable options is available with [c]:help
'{option_name}'[c]. (Note the single quotes around the option name as in Vim.)
Information on all available options is, predictably, [c]:help options[c].

and you can find out about the [m]gt[m] and [m]gT[m] mapping with

  :help gt<CR>
  :help gT<CR>

Finally, in addition to the help system itself, [c]:exusage[c], [c]:viusage[c]
and [c]:optionusage[c] are useful quick-reference commands.

section:Mouseless[living-mouseless]

*-- or how I learned to stop worrying and love the 80+ buttons I already have.*

The efficiency of Vimperator, 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, Vimperator acts on the
assumption that the web browser doesn't have to be one of those.

Here are some areas where the mouse is typically considered indisposable, and
how Vimperator challenges this preconception.

section:Scrolling[keyboard-scrolling]

Scrolling the browser window is done with simple keystrokes:

  * [m]j[m]/[m]k[m] --
    scroll window down/up by one line, respectively
  * [m]h[m]/[m]l[m] --
    scroll window left/right
  * [m]<Space>[m]/[m]<C-b>[m] --
    scroll down/up by one page
  * [m]<C-d>[m]/[m]<C-u>[m] --
    scroll down/up by 1/2 page

Your standard buttons ([m]<Up>[m]/[m]<Down>[m]/[m]<PgUp>[m]/[m]<PgDn>[m]) will
also work as expected.

section:History{nbsp}and{nbsp}tabs[history-navigation,tab-navigation]

History navigation (e.g., ``Back'', ``Forward'') are done similarly to
scrolling.

  * [m]<C-o>[m]/[m]<C-i>[m] --
    move Back/Forward in the current window/tab's history, respectively

Move between tabs using these keystrokes which may also be familiar to tabbing
Vimmers.

  * [m]gt[m]/[m]<C-n>[m] --
    go to the next tab
  * [m]gT[m]/[m]<C-p>[m] --
    go to the previous tab
  * [m]g0[m]/[m]g$[m] --
    go to the first/last tab
  * [m]d[m] --
    close the active tab (delete the buffer)

To open a web page in a new tab, use the [c]:tabopen {url}[c]. To open a URL in
the current tab, use [c]:open[c]. The normal mode mappings [m]t[m] and [m]o[m],
respectively, map to these commands, so the following pairs sequences are
equivalent:

  :open my.webmail.com<CR>
  omy.webmail.com<CR>

  :tabopen vimperator.org<CR>
  tvimperator.org<CR>

section:Some{nbsp}hints{nbsp}about{nbsp}surfing...[hints-tutorial]

So now you can navigate around in Vimperator. But wait... how do you *open* a
page or tab linked in a web page?  How do you ``click'' on all those links
without your tailed friend?

The answer is ``hints''. Activating hints displays a number next to every link
Vimperator can find. To follow the link, simply type the number corresponding
to the hint, a white number inside a red square by default.

For text links, there's an additional shortcut; you can type some text
contained in the link and Vimperator 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, Vimperator will follow that link
immediately without any further user input.

Whichever way you choose to indicate your target link, once Vimperator has
highlighted the link you want, simply hit [m]<Enter>[m] to open it.

The most common hint mode is called help:QuickHint{nbsp}mode[various.html,f].
To activate QuickHint mode, press either [m]f[m] or [m]F[m]. The lower-case
[m]f[m] will open the resulting link in the current tab, while the upper-case
[m]F[m] will open it in a new tab.

To test it, try this link: http://vimperator.org/[Vimperator Homepage].
Activate QuickHint mode with [m]f[m] or [m]F[m] to highlight all currently
visible links. Then start typing the text of the link. The link should be
uniquely identified soon, and Vimperator will open it. Once you're done,
remember to use [m]<C-o>[m] (``History Back'') or [m]d[m] (``Delete Buffer'')
to return here, depending on which key you used to activate QuickHint mode.

section:Common{nbsp}issues[common-issues]

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:

  :open my.partial.url/fooba

You can exit the command line and access the already loaded page with the
following:

  <Esc>gT

section:Saving{nbsp}for{nbsp}posterity{nbsp}-{nbsp}vimperatorrc[vimperatorrc]

Once you get Vimperator set up with your desired options, maps, and commands,
you'll probably want them to be available the next time you open Vimperator.
Continuing the Vim theme, this is done with a vimperatorrc file.

To save your current settings and allow them to be loaded automatically
next time you start Vimperator, issue the [c]:mkv[c] command.

This will create the file *_$HOME_/.vimperatorrc* containing your settings.
It is a simple text file, just like a vimrc file and can be easily
edited to suit your preferences.

section:Find{nbsp}the{nbsp}exit{nbsp}nearest{nbsp}you[quitting-without-menus]

Vimperator supports all of Vim's classic methods of exiting.

  * [c]:xall[c] -- command to quit and save the current browsing
    session for next time; the default.
  * [c]:qall[c] -- command to quit _without_ saving the session
  * [m]ZZ[m] -- normal mode mapping equivalent to [c]:xall[c]
  * [m]ZQ[m] -- normal mode mapping equivalent to [c]:qall[c]

section:Where{nbsp}did{nbsp}Firefox{nbsp}go?[whither-firefox]

You might feel pretty disoriented now. Don't worry. This is still Firefox
underneath. Here are some ways Vimperator allows Firefox to shine through. See
the [c]:help[c] for these commands and mappings for more information on how to
make the best use of them.

  * [c]:dialog[c] --
    To access some of Firefox's many dialog windows, you can use the
    [c]:dialog[c] command. See [c]:help :dialog[c].
  * [c]:bmarks[c] --
    Vimperator provides a new interface to bookmarks, but they're still your
    standard Firefox bookmarks under the hood. [c]:bmark[c] will add a new
    bookmark, while [c]:bmarks[c] will list the bookmarks currently defined.
  * [c]:history[c] --
    It's exactly what it sounds like. This command will display a colorized,
    scrollable and clickable list of the locations in Vimperator's history.
  * [c]:emenu[c] --
    Access the Firefox menus through the Vimperator command line.


Feel free to explore at this point. If you use the [c]:tabopen[c] command,
remember to use the [m]gt[m]/[m]gT[m] mappings to get back to this page. If
using the [c]:open[c] command, use the history keys (e.g., [m]H[m]) to return.
If you get hopelessly lost, just type [c]:help<CR>[c] and click the
``Tutorial'' link to return.


// TODO: other sections?


section:Get{nbsp}me{nbsp}out{nbsp}of{nbsp}here![removal]

If you've given it a fair shot and determined ... TODO

The Vimperator way to do this is with the command [c]:addons[c]. Issuing this
command brings up the Firefox Add-ons dialog window; you can then remove it as
normal, selecting Vimperator from the list and clicking (yes, clicking)
*Uninstall*.

Alternatively, you can do this the old-fashioned way: re-enable the menubar,
as above, with [c]:set go+=m[c], and select *Add-ons* from the *Tools* menu.


section:I'm{nbsp}interested...but{nbsp}lost![support]

Vimperator has an energetic and growing user base. If you've run into a problem
that you can't seem to solve with Vimperator, or if you think you might have
found a bug, please let us know!  There is support available on the
http://vimperator.cutup.org/index.php?title=Main_Page[wiki], or in the
#vimperator IRC channel on http://freenode.net/[freenode].

If you have any feature requests or (even better) offers to help, we'd love to
hear from you as well. Developers work on Vimperator 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
help:Developer[developer.html] page for more information.

// vim: set filetype=asciidoc: