path: root/doc/vimb.1.txt

.\" Process this file with
.\" groff -man -Tascii vimb.1
.TH PROJECT 1 "23/03/2013" "PROJECT/VERSION" "Vimb Manual"
.SH NAME
PROJECT \- Vim Browser - A modal web browser based on webkit thats inspired by
vim the great editor.
.SH SYNOPSIS
.BI "PROJECT [" "OPTION" "] [" "URI" "]"
.SH DESCRIPTION
PROJECT 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 PROJECT is to build a completely keyboard-driven, efficient and pleasurable
browsing-experience.
.SH OPTIONS
Mandatory arguments to long options are mandatory for short options too.
.TP
.BI "-c, --config " "CONFIG-FILE"
Use custom configuration given as \fICONFIG-FILE\fP.
.TP
.BI "-e, --embed " "WINID"
.I WINID
of an XEmbed-aware application, that PROJECT will use as its parent.
.TP
.B "-h, --help"
Show help options.
.TP
.B "-d, --dump-config"
Dump out the whole default configurations to stdout. This can be used to
create a own config file in
.I $XDG_CONFIG_HOME/PROJECT/config
.TP
.B "-v, --version"
Print build and version information.
.SH MODES
PROJECT is modal an has following main modes:
.TP
.B Normal Mode
The default mode. Pressing Escape always enter normal mode.
.TP
.B Insert Mode
Used for editing text elements in a webpage.
.TP
.B Hint Mode
Follow links, form fields and frames via hints.
.TP
.B Command Mode
Execute PROJECT commands from the builtin inputbox (commandline).
.TP
.B Search Mode
Search for strings within the current displayed page.
.TP
.B Insert Mode
Used for editing text elements in a webpage.
.SH COMMANDS
Commands are a central part in PROJECT. They are used for nearly all things
that could be done with this browser. Commands allow to set config variables,
to assign keybindings and much more. Also the keybindings are only shortcut
for the commands itself.

Commands can be called in Insert Mode from the inputbox in the way like
":[count]command[ param[=value]]". But some commands are not available in
Command Mode and therefore not callable directly. To use them too, they must be
bound to the keybinding.

For example the command "hint-focus-next" is only available in hinting mode.
To call it, it has to be bound to a key like "hmap <tab>=hint-focus-next" to
be used.

.SS Open
.TP
.BI "open [" URI ]
Open the give \fIURI\fP into current window. If \fIURI\fP is empty the
configured 'home-page' is opened.
.TP
.BI "tabopen [" URI ]
Open the give \fIURI\fP into a new window. If \fIURI\fP is empty the
configured 'home-page' is opened.
.TP
.B (tab)open-closed
Open the last closed page.
.TP
.B (tab)open-clipboard
Open the url from clipboard.
.SS Input
Switches the browser into Command Mode and prefill the inputbox on th bottom of
the browser with various prefilled content.
.TP
.BI "input [" "TEXT" "]"
Writes
.I TEXT
into to inputbox and switch to command mode. If no
.I TEXT
is given, print ':' into the inputbox.
.TP
.BI "inputuri [" "TEXT" "]"
Writes
.I TEXT\fR{URI}
into to inputbox where {URL} is the current used url. This can be used to add
keybindings to generate the tabopen command with current uri prefilled. If
.I TEXT
is not given use ':' instead.
.SS Navigate
Following commands are used to navigate within the browser history.
.TP
.BI [ N "]back"
Move
. I N
steps back in browser history.
.TP
.BI [ N "]forward"
Move \fIN\fP steps back in browser history.
.TP
.B reload
Reload the current viewed url.
.TP
.B reload!
Discard any caches and reload the current viewed url.
.TP
.B stop
Stop loading the current url.
.SS Scroll
Following commands are used to scroll ad jump within the current view.
.TP
.BI [ N "]jumpleft"
Scrolls the current view \fIN\fP steps to the left.
.br
If \fIN\fP is given jump to \fIN\fR% of the page from the left.
.TP
.BI [ N "]jumpright"
Scrolls the current view to the right.
.br
If \fIN\fP is given jump to \fIN\fP% of the page from the left.
.TP
.BI [ N "]jumptop"
Scrolls the current view to the top of page.
.br
If \fIN\fP is given, scroll to \fIN\fR% of the page.
.TP
.BI [ N "]jumpbottom"
Scrolls the current view to the end of page.
.br
If \fIN\fP is given, scroll to \fIN\fR% of the page.
.TP
.BI [ N "]pageup"
Scroll up the page \fIN\fP screens.
.TP
.BI [ N "]pagedown"
Scroll down the page \fIN\fP screens.
.TP
.BI [ N "]halfpageup"
Scroll up the page \fIN\fP half screens.
.TP
.BI [ N "]halfpagedown"
Scroll down the page \fIN\fP half screens.
.TP
.BI [ N "]scrollleft"
Scroll the page \fIN\fP times the "scrollstep" to the left.
.TP
.BI [ N "]scrollright"
Scroll the page \fIN\fP times the "scrollstep" to the right.
.TP
.BI [ N "]scrollup"
Scroll the page \fIN\fP times the "scrollstep" to the top.
.TP
.BI [ N "]scrolldown"
Scroll the page \fIN\fP times the "scrollstep" to the end.
.SS Keybinding
To bind a command to a key sequence use the {n,i,c,h}map command. To map a
keysequence to a command, use this format "nmap {[modkey]key}={command}[ params]".

The modkey is a single simple char like "g". The key can also contain
special keys and modifiers and is given in format like "<ctrl-o>", "<tab>",
"<shift-tab>", "<up>", "<right>" or also a simple char like "G".

Example:
.br
"hmap <shift-tab>=hint-focus-prev" to add focus next in in Hinting Mode.
.br
"nmap <shift-?>=input :foo" to write :foo into input box and switch to Command Mode.
.br
"hunmap <shift-tab>" To remove this keybinding use.

If a keybinding is added, for the same key-sequence like another keybinding,
the later added have precedence. If a keybinding is removed only that with the
highest precedence will be removed and all other will still be active.
.TP
.B nmap
Add a keybinding used in Normal Mode.
.TP
.B imap
Add a keybinding used in Input Mode.
.TP
.B cmap
Add a keybinding used in Command Mode.
.TP
.B hmap
Add a keybinding used in Hint Mode.
.TP
.B smap
Add keybinding used in Search Mode.
.TP
.B nunmap
Remove a Normal Mode keybinding.
.TP
.B iunmap
Remove a Input Mode keybinding.
.TP
.B cunmap
Remove a Command Mode keybinding.
.TP
.B hunmap
Remove a Hint Mode keybinding.
.TP
.B sunmap
Remove a Search Mode keybinding.
.SS Complete
.TP
.B complete
Start a completion according to the current first chars in the inputbox. If
complation is already started, switch to the next completion item.
.TP
.B complete-back
If complation is already started, switch to the previous completion item.
.SS Hints
.TP
.BI "hint-link [" PREFIX "], hint-link-new [" PREFIX ]
Start hinting to open link into current or new window. If \fIPREFIX\fP is given,
print this into the inputbox, default '.' and ','.
.TP
.BI "hint-input-open [" PREFIX "], hint-input-tabopen [" PREFIX ]
Start hinting to fill the inputbox with ":open {hintedLinkUrl}" or ":tabopen
{hintedLinkUrl}". If \fIPREFIX\fP is given, print this into the inputbox,
default ';o' and ';t'.
.TP
.BI "hint-yank [" PREFIX ]
Start hinting to yank the hinted link url into the primary and secondary
clipboard. If \fIPREFIX\fP is given, print this into the inputbox, default ';y'.
.TP
.BI "hint-image-open [" PREFIX "], hint-image-tabopen [" PREFIX ]
Start hinting to open images into current or new window. If \fIPREFIX\fP is
given, print this into the inputbox, default ';i' and ';I'.
.TP
.B hint-focus-nex, hint-focus-prevt
Focus next or previous hint.
.SS Yank
.TP
.B yank-uri
Yank the current url to the primary and secondary clipboard.
.TP
.B yank-selection
Yank the selected text into the primary and secondary clipboard.
.SS Searchengines
Searchengines allows to query a searchengine instead of typing a full url. If
a searchengine with shortcut 'dd' is defined you can use 'dd search terms' to
perform a search query.
.TP
.BI "searchengine-add " "SHORTCUT" "=" "URI"
Adds a searchengine with the \fISHORTCUT\fP and search \fIURI\fP. The uri must
not contain more than one '%s' placeholder.

Example: searchengine-add dl=https://duckduckgo.com/lite/?q=%s
.TP
.BI "searchengine-remove " "SHORTCUT"
Remove the search engine to the given \fISHORTCUT\fP.
.TP
.BI "searchengine-default " "SHORTCUT"
Set the search engine for given \fISHORTCUT\fP as the default search engine.
It doesn't metter if the \fISHORTCUT\fP is already in use or not to be able to
set the default search engine.
.SS Configuration
.TP
.BI "set " VAR = VALUE
Set configuration values named by
.IR VAR .
To set boolean variable you should use 'on', 'off' or 'true'
and 'false'. Colors are given as hexadecimal value like '#f57700'.
.TP
.BI "set " VAR ?
Show the current set value of variable
.IR VAR .
.TP
.BI "set " VAR !
Toggle the value of boolean variable \fIVAR\fP and display the new set value.
.SS Zoom
.TP
.BI [ N "]zoomin, [" N "]zoomout"
Zoom \fIN\fP steps in or out of the current page \- effects only the text.
.TP
.BI [ N "]zoominfullt, [" N "]zoomoutfull"
Zoom \fIN\fP steps in or out of the current page \- effecting all elements.
.TP
.B zoomreset
Reset the zoomlevel to the default value.
.SS History
.TP
.B hist-prev, hist-next"
Prints the previous or next cammand or search query from history into
inputbox. If there is already text in the input box this will be used to get
history items. A command is not a internal command, but every string entered
into inputbox that begins with \fI[:/?]\fP. So the history contains real
commands and search queries.
.SS Bookmark
.TP
.BI "bookmark-add [" TAGS "]"
Save the current opened uri with \fITAGS\fP to the bookmark file.
.SS Misc
.TP
.BI run " [COMMAND LIST]"
Run is a command, that was introduced to have the ability to run multiple
other commands with a single call. Everything after the `run' is interpreted
as a `|' seperated list of commands and parameters.
":run [count]command[ param[=value]]|[count]command[ param[=value]]|..."

The run command allows to use fancy keybindings that set several config
settings with only on keypress.

Example:

:run set input-bg-normal=#ff0 | set input-fg-normal=#f0f | 5pagedown

.TP
.BI [ N "]search-forward, [" N "]search-backward"
Search in current page forward or backward.
.TP
.B inspect
Toggles the webinspector for current page. This is only available if the config
"webinspector" is enabled.
.TP
.B quit
Close the browser.
.TP
.B source
Toggle between normal view and source view for the current page.
.SH FILES
.I $XDG_CONFIG_HOME/PROJECT/config
.RS
Configuration file to set webkit setting, some gui styles and keybindings.
.RE
.I $XDG_CONFIG_HOME/PROJECT/cookies
.RS
Cookie store file.
.RE
.I $XDG_CONFIG_HOME/PROJECT/closed
.RS
Holds the URI of the last closed browser window.
.RE
.I $XDG_CONFIG_HOME/PROJECT/history
.RS
This file holds the history of unique opened URIs.
.RE
.I $XDG_CONFIG_HOME/PROJECT/command
.RS
This file holds the history of commands and search queries performed via input
box.
.RE
.I $XDG_CONFIG_HOME/PROJECT/search
.RS
This file holds the history of search queries.
box.
.RE
.I $XDG_CONFIG_HOME/PROJECT/bookmark
.RS
Holds the bookmarks saved with command `bookmark-add'.
.RE
.I $XDG_CONFIG_HOME/PROJECT/scripts.js
.RS
This file can be used to run user scripts, that are injected into every paged
that is opened.
.RE
.I $XDG_CONFIG_HOME/PROJECT/style.css
.RS
File for userdefined css styles. These file is used if the config variable
'stylesheet' is enabled.
.RE
.SH "REPORTING BUGS"
Report bugs to the main project page on
.IR https://github.com/fanglingsu/vimb/issues .
.SH AUTHOR
Daniel Carl