path: root/doc/vimb.1

.\" vim: ft=groff
.\" Process this file with
.\" groff -man -Tutf8 vimb.1
.TH vimb 1 "DATE" "vimb/VERSION" "Vimb Manual"
.de EX
.nf
.ft CW
..
.de EE
.ft R
.fi
..
.SH NAME
vimb - Vim Browser - A modal web browser based on webkit, inspired by vim the
great editor.
.SH SYNOPSIS
.SY vimb
.OP OPTIONS
.RI [ URI "|" file "|" - ]
.YS
.SH DESCRIPTION
vimb is a webkit based web browser that behaves like the vimperator
plugin for the firefox and usage paradigms from the great editor vim. The goal
of vimb is to build a completely keyboard-driven, efficient and pleasurable
browsing-experience.
.SH OPTIONS
If no \fIURI\fP or \fIfile\fP is given vimb will open the configured
home-page. If \fIURI\fP is '-', vimb reads the html to display from stdin.

Mandatory arguments to long options are mandatory for short options too.
.TP
.BI "\-C, \-\-cmd " "CMD"
Run \fICMD\fP as ex command line right before the first page is loaded.
If the flag is used more than one time, the ordering is preserved when
\fICMD\fP are executed. You could also pass several ex commands in one
\fICMD\fP, if there are separated by "|".

Example: vimb --cmd "set cookie-accept=origin|set header=Referer,DNT=1"
.TP
.BI "\-c, \-\-config " "CONFIG-FILE"
Use custom configuration given as \fICONFIG-FILE\fP. This will also be applied
on new spawned instances.
.TP
.BI "\-e, \-\-embed " "WINID"
.I WINID
of an XEmbed-aware application, that vimb will use as its parent.
.TP
.B "\-h, \-\-help"
Show help options.
.TP
.B \-k, \-\-kiosk
Run vimb in kiosk mode with nearly no keybindings, not inputbox and no context
menu.
.TP
.B \-n, \-\-fifo-name
If given vimb will create a control fifo in vimb's config directory
named 'vimb-fifo-{name}'.
.TP
.B "\-v, \-\-version"
Print build and version information.
.SH MODES
vimb is modal an has following main modes:
.TP
.B Normal Mode
The default mode. Pressing Escape always enter normal mode.
.TP
.B Input Mode
Used for editing text elements in a webpage.
.TP
.B Command Mode
Execute ex-commands from the builtin inputbox (commandline).
.TP
.B Pass-Through Mode
In Pass-Through mode only the `<Esc>` and `<C-[>` keybindings are interpreted
by vimb, all other keystrokes are given to the webview to handle them. This
allows to use websites that uses keybindings itself, that might be swallowed
by vimb else.
.SH NORMAL MODE COMMANDS
Some of the Normal Model Commands can have a numeric count to multiply the
effect of the command. If a command supports the count this is shown as
\fB[N]\fP.
.SS General
.TP
.B :
Start Command Mode and print `:' to the input box.
.TP
.B gi
Set cursor to the first editable element in the page and switch to Input
Mode.
.TP
.B CTRL\-Z
Switch vimb into Pass-Through Mode.
.TP
.B gf
Toggle show html source of current page.
.TP
.B gF
Open the Web Inspector for current page.
.TP
.B CTRL\-V
Pass the next key press directly to gtk.
.TP
.B CTRL\-Q
Quit the browser if there are no running downloads.
.SS Navigation
.TP
.B o
Start Command Mode and print `:open ' to input box.
.TP
.B O
Start Command Mode and print `:open URI' to input box.
.TP
.B t
Start Command Mode and print `:tabopen ' to input box.
.TP
.B T
Start Command Mode and print `:tabopen URI' to input box.
.TP
.B gh
Open the configured home-page.
.TP
.B gH
Open the configured home-page into new window.
.TP
.B u
Open the last closed page.
.TP
.B U
Open the last closed page into a new window.
.TP
.B CTRL\-P
Open the oldest entry from read it later queue in current browser window, if
vimb has been compiled with QUEUE feature.
.TP
.BI [ \[char34]x ]p
Open the URI out of the register \fIx\fP or if not given from clipboard.
.TP
.BI [ \[char34]x ]P
Open the URI out of the register \fIx\fP or if not given from clipboard into
new window.
.TP
.BI [ N ]CTRL\-O
Go back \fIN\fP steps in the browser history.
.TP
.BI [ N ]CTRL\-I
Go forward \fIN\fP steps in the browser history.
.TP
.BI [ N ]gu
Go to the \fIN\fPth descendent directory of the current opened URI.
.TP
.B gU
Go to the domain of the current opened page.
.TP
.BI [ N ]CTRL\-A
Increments the last number in URL by 1, or by \fIN\fP if given.
.TP
.BI [ N ]CTRL\-X
Decrements the last number in URL by 1, or by \fIN\fP if given. Negative
numbers are not supported as trailing numbers in URLs are often preceded by
hyphens.
.TP
.B r
Reload the website.
.TP
.B R
Reload the website without using caches.
.TP
.B CTRL\-C
Stop loading the current page.
.SS Motion
.TP
.BI [ N ]CTRL\-F
Scroll \fIN\fP pages down.
.TP
.BI [ N ]CTRL\-B
Scroll \fIN\fP pages up.
.TP
.BI [ N ]CTRL\-D
Scroll \fIN\fP half pages down.
.TP
.BI [ N ]CTRL\-U
Scroll \fIN\fP half pages up.
.TP
.BI [ N ]gg
Scroll to the top of the current page. Or if \fIN\fP is given to \fIN\fP% of
the page.
.TP
.BI [ N ]G
Scroll to the bottom of the current page. Or if \fIN\fP is given to \fIN\fP%
of the page.
.TP
.BI [ N ]0
Scroll \fIN\fP steps to the left of current page.
.TP
.BI [ N ]$
Scroll \fIN\fP steps to the right of current page.
.TP
.BI [ N ]h
Scroll \fIN\fP steps to the left of page.
.TP
.BI [ N ]l
Scroll \fIN\fP steps to the right of page.
.TP
.BI [ N ]j
Scroll page \fIN\fP steps down.
.TP
.BI [ N ]k
Scroll page \fIN\fP steps up.
.TP
.BI [ N ]]]
Follow the last \fIN\fPth link matching `nextpattern'.
.TP
.BI [ N ][[
Follow the last \fIN\fPth link matching `previouspattern'.
.TP
.BI m{ a-z }
Set a page mark {\fIa-z\fP} at current possition on page. Such set marks are
only available on the current page, if the page is left, all marks will be
removed.
.TP
.BI '{ a-z }
Jump to the mark {\fIa-z\fP} on current page.
.TP
.B ''
Jumps to the position before the latest jump, or where the last "m'" command
was given.
.SS Hinting
The hinting is the way to do what you would do with the mouse in common
mouse-driven browsers. Open URI, yank URI, save page and so on. If the hinting
is started, the relevant elements on the page will be marked by labels
generated from configured `hintkeys'. Hints can be selected by using <Tab>,
<C-I> or <C-Tab>, <C-O>, by typing the chars of the label, or filtering the
elements by some text that is part of the hinted element (like URI, link text,
button label) and any combination of this methods. If <enter> is pressed, the
current active hint will be fired. If only one possible hint remains, this
will be fired automatically.

.BI Syntax: " ;{mode}{hint}"

Start hint mode. Different elements depending on \fImode\fP are highlighted
and `numbered'. Elements can be selected either by typing their label, or by
typing part of their text (\fIhint\fP) to narrow down the result. When an
element has been selected, it is automatically clicked or used (depending on
\fImode\fP) and hint mode ends.

The filtering of hints by text splits the query at ' ' and use the single parts
as separate queries to filter the hints. This is useful for hints that have a
lot of filterable chars in common and it needs many chars to make a distinct
selection. For example ';over tw' will easily select the second hint out of
{'very long link text one', 'very long link text two'}.
.RS 0
.TP
Following keys have special meanings in Hints mode:
.PD 0
.IP \fB<CR>\fP
Selects the first highlighted element, or the current focused.
.IP "\fB<Tab>\fP"
Moves the focus to the next hint element.
.IP "\fB<S-Tab>\fP"
Moves the focus to the previous hint element.
.IP "\fB<Esc>, CTRL\-C, CTRL\-[\fP"
Exits Hints mode without selecting an element
.PD
.RE
.TP
.B Hint modes:
.RS
.PD 0
.TP
.B f
Is an alias for the \fB;o\fP hint mode.
.TP
.B F
Is an alias for the \fB;t\fP hint mode.
.TP
.B ;o
Open hint's location in the current window.
.TP
.B ;t
Open hint's location in a new window.
.TP
.B ;s
Saves the hint's destination under the configured `download-path'.
.TP
.B ;O
Generate an `:open' prompt with hint's URI.
.TP
.B ;T
Generate an `:tabopen' prompt with hint's URI.
.TP
.B ;e
Open the configured editor (`editor-command') with the hinted form element's
content. If the file in editor is saved and the editor is closed, the file
content will be put back in the form field.
.TP
.B ;i
Open hinted image into current window.
.TP
.B ;I
Open hinted image into new window.
.TP
.B ;p
Push the hint's URI to the end of the read it later queue like the `:qpush'
command. This is only available if vimb was compiled with QUEUE feature.
.TP
.B ;P
Push the hint's URI to the beginning of the read it later queue like the
`:qunshift' command. This is only available if vimb was compiled with QUEUE
feature.
.TP
.B ;x
Hints like ;o, but instead of opening the hinted URI, the
`x-hint-command' is run in vimb.
.TP
.BI [ \[char34]x ];y
Yank hint's destination location into primary and secondary clipboard and into
the register \fIx\fP.
.TP
.BI [ \[char34]x ];Y
Yank hint's text description or form text into primary and secondary clipboard
and into the register \fIx\fP.
.PD
.RE
.TP
.BI Syntax: " g;{mode}{hint}"
Start an extended hints mode and stay there until <Esc> is pressed. Like the
normal hinting except that after a hint is selected, hints remain visible so
that another one can be selected with the same action as the first. Note that
the extended hint mode can only be combined with the following hint modes
\fII p P s t y Y\fP.
.SS Searching
.TP
.BI / QUERY ", ?" QUERY
Start searching for \fIQUERY\fP in the current page. \fI/\fP start search
forward, \fI?\fP in backward direction.
.TP
.B *, #
Start searching for the current selected text, or if no text is selected for
the content of the primary or secondary clipboard. \fI*\fP start the search in
forward direction and \fI#\fP in backward direction.

Note that this commands will yank the text selection into the clipboard and
may remove other content from there!
.TP
.BI [ N ]n
Search for \fIN\fPnth next search result depending on current search
direction.
.TP
.BI [ N ]N
Search for \fIN\fPnth previous search result depending on current search
direction.
.SS Zooming
.TP
.BI [ N ]zi
Zoom-In the text of the page by \fIN\fP steps.
.TP
.BI [ N ]zo
Zoom-Out the text of the page by \fIN\fP steps.
.TP
.BI [ N ]zI
Full-Content Zoom-In the page by \fIN\fP steps.
.TP
.BI [ N ]zO
Full-Content Zoom-Out the page by \fIN\fP steps.
.TP
.B zz
Reset Zoom.
.SS Yank
.TP
.BI [ \[char34]x ]y
Yank the URI or current page into register \fIx\fP and clipboard.
.TP
.BI [ \[char34]x ]Y
Yank the current selection into register \fIx\fP and clipboard.
.SH COMMAND MODE
.SS Command Line Editing
.TP
.B <Esc>, CTRL\-[, CTRL-C
Ignore all typed content and switch back to normal mode.
.TP
.B <CR>
Submit the entered ex command or search query to run it.
.TP
.B CTRL\-H
Deletes the char before the cursor.
.TP
.B CTRL\-W
Deletes the last word before the cursor.
.TP
.B CTRL\-U
Remove everything between cursor and prompt.
.TP
.B CTRL\-B
Moves the cursor direct behind the prompt `:'.
.TP
.B CTRL\-E
Moves the cursor after the char in inputbox.
.TP
.B CTRL\-V
Pass the next key press directly to gtk.
.TP
.B CTRL\-R {a-z"%:/;}
Insert the content of given register at cursor position. See also section
REGISTERS.
.SS Command Line History
.TP
.B <Tab>
Start completion of the content in inputbox in forward direction.
.TP
.B <S-Tab>
Start completion of the content in inputbox in backward direction.
.TP
.B <Up>
Step backward in the command history.
.TP
.B <Down>
Step forward in the command history.
.SS Open
.TP
.BI ":o[pen] [" URI ]
Open the give \fIURI\fP into current window. If \fIURI\fP is empty the
configured 'home-page' is opened.
.TP
.BI ":t[abopen] [" URI ]
Open the give \fIURI\fP into a new window. If \fIURI\fP is empty the
configured 'home-page' is opened.
.SS Key Mapping
Key mappings allow to alter actions of key presses. Each key mapping is
associated with a mode and only has effect when the mode is active. Following
commands allow the user to substitute one sequence of key presses by another.

.BI Syntax: " :{m}map {lhs} {rhs}"
Note that the \fIlhs\fP ends with the first found space. If you want to use
space also in the {lhs} you have to escape this with a single `\\' like shown
in the examples.
.RS 0
.TP
.PD 0
Standard key mapping commands are provided for these modes \fIm\fP:
.IP \fBn\fP
Normal mode: When browsing normally.
.IP \fBi\fP
Insert mode: When interacting with text fields on a website.
.IP \fBc\fP
Command Line mode: When typing into the vimbs command line.
.PD
.P
.RE
Most keys in key sequences are represented simply by the character that you
see on the screen when you type them. However, as a number of these characters
have special meanings, and a number of keys have no visual representation, a
special notation is required.

As special key names have the format \fI<...>\fP. Following special keys can
be used <Left>, <Up>, <Right>, <Down> for the cursor keys, <Tab>, <Esc>, <CR>,
<F1>-<F12> and <C-A>-<C-Z>.
.TP
.BI ":nm[ap] {" lhs "} {" rhs }
.TP
.BI ":im[ap] {" lhs "} {" rhs }
.TP
.BI ":cm[ap] {" lhs "} {" rhs }
Map the key sequence \fIlhs\fP to \fIrhs\fP for the modes where the map
command applies. The result, including \fIrhs\fP, is then further scanned for
mappings. This allows for nested and recursive use of mappings.
.RS
.P
Examples:
.PD 0
.IP ":cmap <C-G>h /home/user/downloads/"
Adds a keybind to insert a file path into the input box. This could be useful
for the `:save' command that could be used as ":save ^Gh".
.IP ":nmap <F1> :set scripts=on<CR>:open !glib<Tab><CR>"
This will enable scripts and lookup the first bookmarked URI with the tag
`glib' and open it immediately if F1 key is pressed.
.IP ":nmap \\\\\ \\\\\  50G;o"
Example which mappes two spaces to go to 50% of the page, start hinting mode.
.PD
.RE
.TP
.BI ":nn[oremap] {" lhs "} {" rhs }
.TP
.BI ":ino[remap] {" lhs "} {" rhs }
.TP
.BI ":cno[remap] {" lhs "} {" rhs }
Map the key sequence \fIlhs\fP to \fIrhs\fP for the mode where the map command
applies. Disallow mapping of \fIrhs\fP, to avoid nested and recursive
mappings. Often used to redefine a command.
.TP
.BI ":nu[nmap] {" lhs }
.TP
.BI ":iu[nmap] {" lhs }
.TP
.BI ":cu[nmap] {" lhs }
Remove the mapping of \fIlhs\fP for the applicable mode.
.SS Bookmarks
.TP
.BI ":bma [" tags ]
Save the current opened URI with \fItags\fP to the bookmark file.
.TP
.BI ":bmr [" URI ]
Removes all bookmarks for given \fIURI\fP or if not given the current opened
page.
.SS Handlers
Handlers allow specifying external scripts to handle alternative URI methods.
.TP
.BI ":handler-add " "handler" "=" "cmd"
Adds a handler to direct \fIhandler\fP links to the external \fIcmd\fP.
The \fIcmd\fP can contain one placeholder %s that will be filled by the
full URI given when the command is called.
.RS
.P
Examples:
.PD 0
.IP ":handler-add magnet=xdg-open %s"
to open magnet links with xdg-open.
.IP ":handler-add magnet=transmission-gtk %s"
to open magnet links directly with Transmission.
.IP ":handler-add irc=irc-handler.sh %s"
to direct irc://<host>:<port>/<channel> links to a wrapper for your irc client.
.PD
.RE
.TP
.BI ":handler-remove " "handler"
Remove the handler for the given URI \fIhandler\fP.
.SS Shortcuts
Shortcuts allows to open URI build up from a named template with additional
parameters. If a shortcut named 'dd' is defined, you can use it with `:open dd
list of parameters' to open the generated URI.

Shortcuts are a good to use with search engines where the URI is nearly the
same but a single parameter is user defined.
.TP
.BI ":shortcut-add " "shortcut" "=" "URI"
Adds a shortcut with the \fIshortcut\fP and \fIURI\fP template. The \fIURI\fP
can contain multiple placeholders $0-$9 that will be filled by the parameters
given when the shortcut is called. The parameters given when the shortcut is
called will be split into as many parameters like the highest used
placeholder.

To use spaces within the parameters, the parameters can be grouped by
surrounding them with single- or double quotes like shown in example shortcut
`map'.
.RS
.P
Examples:
.PD 0
.IP ":shortcut-add dl=https://duckduckgo.com/lite/?q=$0"
to setup a search engine. Can be called by `:open dl my search phrase'.
.IP ":shortcut-add gh=https://github.com/$0/$1"
to build URIs from given parameters. Can be called `:open gh fanglingsu vimb'.
.IP ":shortcut-add map=https://maps.google.com/maps?saddr=$0&daddr=$1"
to search for a route, all but the last parameter must be quoted if they
contain spaces like `:open map "city hall, London" railway station, London'
.PD
.RE
.TP
.BI ":shortcut-remove " "shortcut"
Remove the search engine to the given \fIshortcut\fP.
.TP
.BI ":shortcut-default " "shortcut"
Set the shortcut for given \fIshortcut\fP as the default. It doesn't matter if
the \fIshortcut\fP is already in use or not to be able to set it.
.SS Settings
.TP
.BI ":se[t] " var = value
Set configuration values named by \fIvar\fP. To set boolean variable you
should use 'on', 'off' or 'true' and 'false'. Colors are given as hexadecimal
value like '#f57700'.
.TP
.BI ":se[t] " var += value
Add the \fIvalue\fP to a number option, or append the \fIvalue\fP to a string
option. When the option is a comma separated list, a comma is added, unless
the value was empty.
.TP
.BI ":se[t] " var ^= value
Multiply the \fIvalue\fP to a number option, or prepend the \fIvalue\fP to a
string option. When the option is a comma separated list, a comma is added,
unless the value was empty.
.TP
.BI ":se[t] " var -= value
Subtract the \fIvalue\fP from a number option, or remove the \fIvalue\fP from
a string option, if it is there. When the option is a comma separated list, a
comma is deleted, unless the option becomes empty.
.TP
.BI ":se[t] " var ?
Show the current set value of variable
.IR VAR .
.TP
.BI ":se[t] " var !
Toggle the value of boolean variable \fIvar\fP and display the new set value.
.SS Queue
The queue allows to mark URIs for later reading (something like a read it later
list). This list is shared between the single instances of vimb. Only
available if vimb has been compiled with QUEUE feature.
.TP
.BI ":qpu[sh] [" URI ]
Push \fIURI\fP or if not given current URI to the end of the queue.
.TP
.BI ":qun[shift] [" URI ]
Push \fIURI\fP or if not given current URI to the beginning of the queue.
.TP
.B :qp[op]
Open the oldest queue entry in current browser window and remove it from the
queue.
.TP
.B :qc[lear]
Removes all entries from queue.
.SS Automatic commands
An autocommand is a command that is executed automatically in response to some
event, such as a URI being opened. Autocommands are very powerful. Use them
with care and they will help you avoid typing many commands.
.PP
Note: The ":autocmd" command cannot be followed by another command, since
any '|' is considered part of the command.
.RS 0
.TP
Autocommands are built with following properties.
.TP
.I group
When the [\fIgroup\fP] argument is not given, Vimb uses the current group as
defined with ':augroup', otherwise, vimb uses the group defined with
[\fIgroup\fP]. Groups are useful to remove multiple grouped autocommands.
.TP
.I event
You can specify a comma separated list of event names. No white space can be
used in this list.
.RS
.PP
.PD 0
Events:
.TP
.B LoadProvisional
Fired if a new page is going to opened. No data has been received yet, the load
may still fail for transport issues.
.TP
.B LoadCommited
Fired if first data chunk has arrived, meaning that the necessary transport
requirements are established, and the load is being performed. This is the
right event to toggle content related setting like 'scripts', 'plugins' and
such things.
.TP
.B LoadFirstLayout
fired if the first layout with actual visible content is shown.
.TP
.B LoadFinished
Fires when everything that was required to display on the page has been loaded.
.TP
.B LoadFailed
Fired when some error occurred during the page load that prevented it from
being completed.
.TP
.B DownloadStart
Fired right before a download is started. This is fired for vimb downloads as
well as external downloads if 'download-use-external' is enabled.
.TP
.B DownloadFinished
Fired if a vimb managed download is finished. For external download this event
is not available.
.TP
.B DownloadFailed
Fired if a vimb managed download failed. For external download this event
is not available.
.PD
.RE
.TP
.I pat
Comma separated list of patterns, matches in order to check if a autocommand
applies to the URI associated to an event. To use ',' within the single
patterns this must be escaped as '\[char92],'.
.RS
.PP
.PD 0
Patterns:
.IP "\fB*\fP"
Matches any sequence of characters. This includes also '/' in contrast to
shell patterns.
.IP "\fB?\fP"
Matches any single character except of '/'.
.IP "\fB{one,two}\fP"
Matches 'one' or 'two'. Any '{', ',' and '}' within this pattern must be
escaped by a '\\'. '*' and '?' have no special meaning within the curly braces.
.IP "\fB\[char92]\fP"
Use backslash to escape the special meaning of '?*{},' in the pattern or
pattern list.
.PD
.RE
.TP
.I cmd
Any ex command vimb understands. The leading ':' is not required. Multiple
commands can be separated by '|'.
.TP
.BI ":au[tocmd] [" group "] {" event "} {" pat "} {" cmd "}"
Add \fIcmd\fP to the list of commands that vimb will execute automatically on
\fIevent\fP for a URI matching \fIpat\fP autocmd-patterns. Vimb always adds
the \fIcmd\fP after existing autocommands, so that the autocommands are
executed in the order in which they were given.
.TP
.BI ":au[tocmd]! [" group "] {" event "} {" pat "} {" cmd "}"
Remove all autocommands associated with \fIevent\fP and which pattern match
\fIpat\fP, and add the command \fIcmd\fP. Note that the pattern is not matches
literally to find autocommands to remove, like vim does. Vimb matches the
autocommand pattern with \fIpat\fP. If [\fIgroup\fP] is not given, deletes
autocommands in current group, as noted above.
.TP
.BI ":au[tocmd]! [" group "] {" event "} {" pat "}"
Remove all autocommands associated with \fIevent\fP and which pattern matches
\fIpat\fP in given group (current group by default).
.TP
.BI ":au[tocmd]! [" group "] * {" pat "}"
Remove all autocommands with patterns matching \fIpat\fP for all events
in given group (current group by default).
.TP
.BI ":au[tocmd]! [" group "] {" event "}"
Remove all autocommands for \fIevent\fP in given group (current group
by default).
.TP
.BI ":au[tocmd]! [" group "]"
Remove all autocommands in given group (current group by default).
.TP
.BI ":aug[roup] {" name "}"
Define the autocmd group \fIname\fP for the following ":autocmd" commands. The name
"end" selects the default group.
.TP
.BI ":aug[roup]! {" name "}"
Delete the autocmd group \fIname\fP.
.PP
Example
.EX
:aug github
:  au LoadCommited * set scripts=off|set cookie-accept=never
:  au LoadCommited http{s,}://github.com/* set scripts=on
:aug end
.EE
.SS Misc
.TP
.BI ":sh[ellcmd] " cmd
Runs given shell \fIcmd\fP syncron and print the output into inputbox.
Following pattern in \fIcmd\fP are expanded, '~username', '~/', '$VAR'
and '${VAR}'. A '\\' before these patterns disables the expansion.

Example: :sh ls -l $HOME
.TP
.BI ":sh[ellcmd]! " cmd
Like :shellcmd, but asyncron.

Example: :sh! /bin/sh -c 'echo "`date` $VIMB_URI" >> myhistory.txt'
.TP
.BI ":s[ave] [" path "]"
Download current opened page into configured download directory. If \fIpath\fP
is given, download under this file name or path. \fIpath\fP is expanded and
can therefore contain '~/', '${ENV}' and '~user' pattern.
.TP
.B :q[uit]
Close the browser. This will be refused if there are running downloads.
.TP
.B :q[uit]!
Close the browser independent from an running download.
.TP
.B :reg[ister]
Display the contents of all registers.
.RS
.PP
.PD 0
Registers:
.TP
.BR \[char34]a " - " \[char34]z
26 named registers "a to "z. Vimb fills these registers only when you say so.
.TP
.B \[char34]:
Last executed ex command.
.TP
.B \[char34]"
Last yanked content.
.TP
.B \[char34]%
Curent opened URI.
.TP
.B \[char34]/
Last search phrase.
.TP
.B \[char34];
Contains the last hinted URL. This can be used in `x-hint-command' to get the
URL of the hint.
.PD
.RE
.TP
.BI :e[val] " javascript"
Runs the given \fIjavascript\fP in the current page and display the evaluated
value.

This comman cannot be followed by antoher command, since any '|' is considered
part of the command.

Example: :eval document.cookie
.TP
.BI :e[val]! " javascript"
Like :eval, but there is nothing print to the input box.
.TP
.BI ":no[rmal] [" cmds ]
Execute normal mode commands \fIcmds\fP. This makes it possible to execute
normal mode commands typed on the input box.

\fIcmds\fP cannot start with a space. Put a count of 1 (one) before it, "1 "
is one space.
This comman cannot be followed by antoher command, since any '|' is considered
part of the command.

Example: :set scripts!|no! R
.TP
.BI ":no[rmal]! [" cmds ]
Like :normal, but no mapping is applied to \fIcmds\fP.
.TP
.B :ha[rdcopy]
Print current document. Open a GUI dialog where you can select the printer,
number of copies, orientation, etc.
.SH INPUT MODE
.TP
.B <Esc>, CTRL\-[
Switch back to normal mode.
.TP
.B CTRL\-O
Executes the next command as normal mode command and return to input mode.
.TP
.B CTRL\-T
Open configured editor with content of current form field.
.TP
.B CTRL\-V
Pass the next key press directly to gtk.
.TP
.B CTRL\-Z
Enter the pass-through mode.
.SH COMPLETIONS
The completions are triggered by pressing `<Tab>` or `<shift-tab>` in the
activated inputbox. Depending of the current inserted content different
completions are started. The completion takes additional typed chars to filter
the completion list that is shown.
.TP
.B commands
The completion for commands are started when at least `:` is shown in the
inputbox. If there are given some sore chars the completion will lookup those
commands that starts with the given chars.
.TP
.B settings
The setting name completion is started if at least `:set ` is shown in
inputbox and does also match settings that begins with already typed setting
prefix.
.TP
.B history
The history of URIs is shown for the `:open ` and `:tabopen ` commands. This
completion looks up for every given word in the history URI and titles. Only
those history items are shown, where the title or URI contains all tags.

Example
.RS
.PD 0
.IP ":open foo bar<Tab>"
will complete only URIs that contain the words foo and bar.
.PD
.RE
.TP
.B bookmarks
The bookmark completion is similar to the history completion, but does match
only the tags of the bookmarks. The bookmark completion ist started by `:open
\fB!\fP` or `:tabopen \fB!\fP` and does a prefix search for all given words in
the bookmark tags.

Example
.RS
.PD 0
.IP ":open \fB!\fPfoo ba"
will match all bookmark that have the tags "foo" or "foot" and tags starting
with "ba" like "ball".
.PD
.RE
.TP
.B boomark tags
The boomark tag completion allows to insert already used bookmarks for the
`:bma ` commands.
.TP
.B search
The search completion allow to get a filtered list of already done searches.
This completion starts by `/` or `?` in inputbox and performs a prefix
comparison for further typed chars.
.SH SETTINGS
All settings listed below can be set with the `:set' command.
.SS Webkit-Settings
.TP
.B accelerated-compositing (bool)
Enable or disable support for accelerated compositing on pages. Accelerated
compositing uses the GPU to render animations on pages smoothly and also
allows proper rendering of 3D CSS transforms.
.TP
.B auto-load-images (bool)
Load images automatically.
.TP
.B auto-resize-window (bool)
Indicates if vimb will honor size and position changes of the window by various
DOM methods.
.TP
.B auto-shrink-images (bool)
Automatically shrink standalone images to fit.
.TP
.B caret (bool)
Whether to enable accessibility enhanced keyboard navigation.
.TP
.B cursivfont (string)
The font family used as the default for content using cursive font.
.TP
.B defaultencoding (string)
The default text charset used when interpreting content with an unspecified
charset.
.TP
.B defaultfont (string)
The font family to use as the default for content that does not specify a
font.
.TP
.B dns-prefetching (bool)
Indicates if vimb prefetches domain names.
.TP
.B dom-paste (bool)
Whether to enable DOM paste. If set to TRUE, document.execCommand("Paste")
will correctly execute and paste content of the clipboard.
.TP
.B file-access-from-file-uris (bool)
Boolean property to control file access for file:// URIs. If this option is
enabled every file:// will have its own security unique domain.
.TP
.B fontsize (int)
The default font size used to display text.
.TP
.B frame-flattening (bool)
Whether to enable the Frame Flattening. With this setting each subframe is
expanded to its contents, which will flatten all the frames to become one
scrollable page.
.TP
.B html5-database (bool)
Whether to enable HTML5 client-side SQL database support. Client-side SQL
database allows web pages to store structured data and be able to use SQL to
manipulate that data asynchronously.
.TP
.B html5-local-storage (bool)
Whether to enable HTML5 localStorage support. localStorage provides simple
synchronous storage access.
.TP
.B hyperlink-auditing (bool)
Enable or disable support for <a ping>.
.TP
.B images (bool)
Determines whether images should be automatically loaded or not.
.TP
.B insecure-content-show (bool)
Whether pages loaded via HTTPS should load subresources such as images and
frames from non-HTTPS URIs. Only for webkit>=2.0.
.TP
.B insecure-content-run (bool)
Whether pages loaded via HTTPS should run subresources such as CSS, scripts,
and plugins from non-HTTPS URIs. Only for webkit>=2.0.
.TP
.B java-applet (bool)
Enable or disable support for the Java <applet> tag. Keep in mind that Java
content can be still shown in the page through <object> or <embed>, which are
the preferred tags for this task.
.TP
.B javascript-can-access-clipboard (bool)
Whether JavaScript can access Clipboard.
.TP
.B javascript-can-open-windows-automatically (bool)
Whether JavaScript can open popup windows automatically without user
intervention.
.TP
.B media-playback-allows-inline (bool)
Whether media playback is full-screen only or inline playback is allowed.
Setting it to false allows specifying that media playback should be always
fullscreen.
.TP
.B media-playback-requires-user-gesture (bool)
Whether a user gesture (such as clicking the play button) would be required to
start media playback or load media. Setting it on requires a gesture by the
user to start playback, or to load the media.
.TP
.B media-stream (bool)
Enable or disable support for MediaSource on pages. MediaSource is an
experimental proposal which extends HTMLMediaElement to allow JavaScript to
generate media streams for playback.
.TP
.B mediasource (bool)
Enable or disable support for MediaSource on pages. MediaSource is an
experimental proposal which extends HTMLMediaElement to allow JavaScript to
generate media streams for playback.
.TP
.B minimumfontsize (int)
The minimum font size used to display text.
.TP
.B monofont (string)
The font family used as the default for content using monospace font.
.TP
.B monofontsize (int)
Default font size for the monospace font.
.TP
.B offlinecache (bool)
Whether to enable HTML5 offline web application cache support. Offline web
application cache allows web applications to run even when the user is not
connected to the network.
.TP
.B pagecache (bool)
Enable or disable the page cache. Disabling the page cache is generally only
useful for special circumstances like low-memory scenarios or special purpose
applications like static HTML viewers.
.TP
.B print-backgrounds (bool)
Whether background images should be printed.
.TP
.B private-browsing (bool)
Whether to enable private browsing mode. This suppresses  printing of messages
into JavaScript Console. At the time this is the only way to force webkit to
not allow a page to store data in the windows sessionStorage.
.TP
.B plugins (bool)
Determines whether or not plugins on the page are enabled.
.TP
.B print-backgrounds (bool)
Whether background images should be drawn during printing.
.TP
.B resizable-text-areas (bool)
Whether text areas are resizable.
.TP
.B respect-image-orientation (bool)
Whether vimb should respect image orientation.
.TP
.B sansfont (string)
The font family used as the default for content using sans-serif font.
.TP
.B scripts (bool)
Determines whether or not JavaScript executes within a page.
.TP
.B seriffont (string)
The font family used as the default for content using serif font.
.TP
.B site-specific-quirks (bool)
Enables the site-specific compatibility workarounds.
.TP
.B smooth-scrolling (bool)
Enable or disable support for smooth scrolling.
.TP
.B spacial-navigation (bool)
Whether to enable the Spatial Navigation. This feature consists in the ability
to navigate between focusable elements in a Web page, such as hyperlinks and
form controls, by using Left, Right, Up and Down arrow keys. For example, if
an user presses the Right key, heuristics determine whether there is an
element he might be trying to reach towards the right, and if there are
multiple elements, which element he probably wants.
.TP
.B spell-checking (bool)
Whether to enable spell checking while typing.
.TP
.B spell-checking-languages (string)
The languages to be used for spell checking, separated by commas.

The locale string typically is in the form lang_COUNTRY, where lang is an
ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance,
sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in
Brazil.

If no value is specified the default value for gtk is used.
.TP
.B tab-key-cycles-through-elements (bool)
Whether the tab key cycles through elements on the page.

If true, pressing the tab key will focus the next element in the web view.
Else the wen view will interpret tab key presses as normal key presses. If the
selected element is editable, the tab key will cause the insertion of a tab
character.
.TP
.B universal-access-from-file-uris (bool)
Whether to allow files loaded through file:// URIs universal access to all
pages.
.TP
.B useragent (string)
The user-agent string used by WebKit.
.TP
.B webaudio (bool)
Enable or disable support for WebAudio on pages. WebAudio is an experimental
proposal for allowing web pages to generate Audio WAVE data from JavaScript.
.TP
.B webgl (bool)
Enable or disable support for WebGL on pages.
.TP
.B webinspector (bool)
Determines whether or not developer tools, such as the Web Inspector, are
enabled.
.TP
.B xssauditor (bool)
Whether to enable the XSS auditor. This feature filters some kinds of
reflective XSS attacks on vulnerable web sites.
.SS Vimb-Settings
.TP
.B ca-bundle (string)
The path to the crt file for the certificate validation. The given path is
expanded with standard file expansion.
.TP
.B completion-bg-active (color)
Background color for selected completion item.
.TP
.B completion-bg-normal (color)
Background color for none selected completion items.
.TP
.B completion-fg-active (color)
Foreground color for the selected completion item.
.TP
.B completion-fg-normal (color)
Foreground color for the none selected completion items.
.TP
.B completion-font (string)
Font used for the completion items.
.TP
.B cookie-accept (string)
Cookie accept policy {`always', `never', `origin' (accept all non-third-party
cookies)}.
.TP
.B cookie-timeout (int)
Cookie timeout in seconds.
.TP
.B cookie-expire-time (int)
Enforce expire-time on cookies. The default value `-1' keep expire-time as
defined by server side. The value `0' convert all cookies as session-only
cookies (`cookie-timeout' setting is used as for any other session-cookie). Any
other value enforce the expire-time (the expire-time value will be the lower
between server-side request and time defined with `cookie-expire-time').
.TP
.B download-command (string)
A command with placeholder '%s' that will be invoked to download a uri.
.RS
.TP
Following additional environment variable are available:
.PD 0
.TP
.B $VIMB_URI
The URI of the current opened page, normally the page where the download was
started from, also known as referer.
.TP
.B $VIMB_FILE
The target file that is calculated by vimb according to the `download-path'.
Note that this file might already exists, so it's strongly recommended to
check the path in this variable before usage.
.TP
.B $VIMB_COOKIES
Path to the cookie file vimb uses. This is only available if vimb is compiled
with COOKIE feature.
.TP
.B $VIMB_USER_AGENT
Holds the user agent string that vimb uses.
.TP
.B $VIMB_MIME_TYPE
The mime-type of the download. This variable is only available when der server
sent the mime-type header with the response and only if the download was not
start by the `:save' command or the `;s' hinting.
.TP
.B $VIMB_USE_PROXY
Indicates if the proxy is enabled in vimb. If enable this variable is `1',
otherwise `0'. Note that this variable gives no hint if the proxy settings
apply to the URL to be downloaded, only if proxy is enabled in general.

.PP
Example
.IP ":set download-command=/bin/sh -c \[char34]wget -c %s -O $VIMB_FILE --load-cookies $VIMB_COOKIES\[char34]"
.PD
.RE
.TP
.B download-path (string)
Path to the default download directory. If the directory is not set download
will be written into current directory. Following pattern will be expanded if
the download is started '~/', '~user', '$VAR' and '${VAR}'.
.TP
.B download-use-external (bool)
Indicates if the external download tool set as `download-command' should be
used to handle downloads. If this is disabled vimb will handle the download.
.TP
.B editor-command (string)
Command with placeholder '%s' called if form filed is opened with editor to
spawn the editor like `x-terminal-emulator -e vi %s'. To use gvim as editor,
it's necessary to call it with `-f' to run it in foreground.
.TP
.B fullscreen (bool)
Show the current window full-screen.
.TP
.B header (list)
Comma separated list of headers that replaces default header sent by webkit or
new headers. The format for the header list elements is `name[=[value]]'.

Note that these headers will replace already existing headers. If there is
no '=' after the header name, then the complete header will be removed from
the request, if the '=' is present means that the header value is set to empty
value.

To use '=' within a header value the value must be quoted like shown in
Example for the Cookie header.
.RS
.PP
Example:
.PD 0
.IP ":set header=DNT=1,User-Agent,Cookie='name=value'"
Send the 'Do Not Track' header with each request and remove the User-Agent
Header completely from request.
.PD
.RE
.TP
.B auto-response-header (list)
Prepend HTTP-Header to responses received from server, based on pattern
matching. The purpose of this setting is to enforce some security setting in
the client. For example, you could set Content-Security-Policy (see
`http://www.w3.org/TR/CSP/') for implement a whitelist policy, or set
Strict-Transport-Security for server that don't provide this header whereas
they propose https website.

Note that this setting will not remplace existing headers, but add a new one.
If multiple patterns match a request uri, the last matched rule will be
applied. You could also specified differents headers for same pattern.

The format is a list of `pattern header-list`. If `header-list` has not than
one element, enclosing with QUOTE is mandatory: `"pattern header-list"`. The
header-list format is the same as `header` setting.
.RS
.PP
Example:
.PD 0
.IP ":set auto-response-header=* Content-security-policy=default-src 'self' 'unsafe-inline' 'unsafe-eval'; script-src 'none'"
.IP ":set auto-response-header+=https://example.com/* Content-security-policy=default-src 'self' https://*.example.com/"
.IP ":set auto-response-header+=https://example.com/* Strict-Transport-Security=max-age=31536000"
.IP ":set auto-response-header+=""https://*.example.org/sub/* Content-security-policy,X-Test=ok"""
.PD
.RE
.TP
.B hint-timeout (int)
Timeout before automatically following a non-unique numerical hint. To disable
auto fire of hints, set this value to 0.
.TP
.B hintkeys (string)
The keys used to label and select hints. With its default value, each hint has
a unique number which can be typed to select it, while all other characters
are used to filter hints based on their text. With a value such as asdfg;lkjh,
each hint is `numbered' based on the characters of the home row.
Note that the hint matching by label built of hintkeys is case sensitive. In
this vimb differs from some other browsers that show hint labels in upper
case, but match them lowercase.
.RS
To have upper case hint labels, it's possible to add following css to the
`style.css' file in vimb's configuration directory.
.IP "._hintLabel {text-transform: uppercase !important;}"
.RE
.TP
.B history-max-items (int)
Maximum number of unique items stored in search-, command or URI history. If
history-max-items is set to 0, the history file will not be changed.
.TP
.B home-page (string)
Homepage that vimb opens if started without a URI.
.TP
.B hsts (bool)
Enable or disables the HSTS (HTTP Strict Transport Security) feature.
.TP
.B input-autohide (bool)
If enabled the inputbox will be hidden whenever it contains no text.
.TP
.B input-bg-error (color)
Background color for the inputbox if error is shown.
.TP
.B input-bg-normal (color)
Background color of the inputbox.
.TP
.B input-fg-error (color)
Foreground color of inputbox if error is shown.
.TP
.B input-fg-normal (color)
Foreground color of inputbox.
.TP
.B input-font-error (string)
Font user in inputbox if error is shown.
.TP
.B input-font-normal (string)
Font used for inputbox.
.TP
.B nextpattern (list)
Patterns to use when guessing the next page in a document. Each pattern is
successively tested against each link in the page beginning from the last
link. Default
"/\\bnext\\b/i,/^(>|>>|»)$/,/^(>|>>|»)/,/(>|>>|»)$/,/\\bmore\\b/i". Note that
you have to escape the '|' as '\\|' else the '|' will terminate the :set
command and start a new command.
.TP
.B maximum-cache-size (int)
Size in kB used to cache various page data. This caching is independent from
`pagecache' or `offlinecache'. To disable caching, the size could be set to '0'.
.TP
.B previouspattern (list)
Patterns to use when guessing the previous page in a document. Each pattern is
successively tested against each link in the page beginning from the last
link. Default "/\\bnext\\b/i,/^(>|>>|»)$/,/^(>|>>|»)/,/(>|>>|»)$/,/\\bmore\\b/i"
.TP
.B proxy (bool)
Indicates if the environment variable `http_proxy' is evaluated.
.TP
.B scrollstep (int)
Number of pixel vimb scrolls if 'j' or 'k' is used.
.TP
.B statusbar (bool)
Indicates if the statusbar should be shown.
.TP
.B status-color-bg (color)
Background color of the statusbar.
.TP
.B status-color-fg (color)
Foreground color of the statusbar.
.TP
.B status-font (string)
Font used in statusbar.
.TP
.B status-ssl-color-bg (color)
Background color of statusbar if current page uses trusted https certificate.
.TP
.B status-ssl-color-fg (color)
Foreground color for statusbar for https pages.
.TP
.B status-ssl-font (string)
Statusbar font for https pages.
.TP
.B status-sslinvalid-color-bg (color)
Background color of the statusbar if the certificate if the https page isn't
trusted.
.TP
.B status-sslinvalid-color-fg (color)
Foreground of statusbar for untrusted https pages.
.TP
.B status-sslinvalid-font (string)
Statusbar font for untrusted https pages.
.TP
.B strict-focus (bool)
Indicates if vimb follows the instruction of the page to focus a form field
without user interaction. If set the true, vimb will no switch to input mode
if the pages say so and vimb will remove the focus from the form field.
.TP
.B strict-ssl (bool)
If 'on', vimb will not load a untrusted https site.
.TP
.B stylesheet (bool)
If 'on' the user defined styles-sheet is used.
.TP
.B timeoutlen (int)
The time in milliseconds that is waited for a key code or mapped key sequence
to complete.
.TP
.B x-hint-command (string)
Command used if hint mode ;x is fired. The command can be any vimb command
string. Note that the command is run through the mapping mechanism of vimb so
it might change the behaviour by adding or changing mappings.
.RS
.P
.PD 0
.IP ":set x-hint-command=50G"
Not really useful. If the hint is fired, scroll to the middle of the page.
.IP ":set x-hint-command=:sh! curl -e <C-R>% <C-R>;"
This fills the inputbox with the prefilled download command and replaces
`<C-R>%' with the current URI and `<C-R>;' with the URI of the hinted element.
.PD
.RE
.SH FILES
.TP
.I $XDG_CONFIG_HOME/vimb/
Default directory for configuration data.
.PP
.RS
.PD 0
.TP
.I config
Configuration file to set webkit setting, some GUI styles and keybindings.
.TP
.I cookies
Cookie store file.
.TP
.I closed
Holds the URI of the last closed browser window.
.TP
.I history
This file holds the history of unique opened URIs.
.TP
.I command
This file holds the history of commands and search queries performed via input
box.
.TP
.I search
This file holds the history of search queries.
.TP
.I bookmark
Holds the bookmarks saved with command `bma'.
.TP
.I queue
Holds the read it later queue filled by `qpush' if
vimb has been compiled with QUEUE feature.
.TP
.I hsts
Holds the known hsts hosts if vimb is compiled with HTTP strict transport
security feature.
.TP
.I scripts.js
This file can be used to run user scripts, that are injected into every paged
that is opened.
.TP
.I style.css
File for userdefined css styles. These file is used if the config variable
`stylesheet' is enabled.
.PD
.RE
.TP
.I $XDG_CACHE_HOME/vimb/
Default directory for cache data.
.SH ENVIRONMENT
.TP
.B VIMB_URI
This variable is set by vimb everytime a new page is opened to the URI of the
page.
.TP
.B VIMB_TITLE
Contains the title of the current opened page.
.TP
.B VIMB_PID
Contains the pid of the running vimb instance.
.TP
.B VIMB_XID
Holds the X-Window id of the vim window or of the embedding window if vimb is
started with -e option.
.TP
.B VIMB_FILE
Holds the full path to the control fifo, if vimb is compiled with FIFO feature
and started with `--fifo-name' option.
.TP
.B http_proxy
If this variable is set to an none empty value, and the configuration option
`proxy' is enabled, this will be used as http proxy. If the proxy URL has no
scheme set, http is assumed.
.TP
.B no_proxy
A comma separated list of domains and/or ips which should not be proxied. Note
that an IPv6 address must appear in brackets if used with a port "[::1]:443".
.IP
Example: "localhost,127.0.0.1,::1,fc00::/7,example.com:8080"
.IP
.SH "REPORTING BUGS"
Report bugs to the main project page on https://github.com/fanglingsu/vimb/issues
.br
or on the mailing list https://lists.sourceforge.net/lists/listinfo/vimb-users.
.SH AUTHOR
Daniel Carl