--- /dev/null
+.\" vim: ft=groff
+.ad l
+.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
+.B vimb
+.OP OPTIONS
+.RI [ URI "|" file ]
+.SH DESCRIPTION
+Vimb is a WebKit based web browser that behaves like the Vimperator
+plugin for Firefox and has 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
+.PP
+Mandatory arguments to long options are mandatory for short options too.
+.TP
+.BI "\-c, \-\-config " "FILE"
+Use custom configuration given as \fIFILE\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 "\-v, \-\-version"
+Print build and version information.
+.SH MODES
+Vimb is modal and has the 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 the use of a website's configured keybindings, that might otherwise
+be swallowed by Vimb.
+.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
+Open the Web Inspector for the 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 the input box.
+.TP
+.B O
+Start Command Mode and print `:open URI' to the input box.
+.TP
+.B t
+Start Command Mode and print `:tabopen ' to the input box.
+.TP
+.B T
+Start Command Mode and print `:tabopen URI' to the input box.
+.TP
+.B gh
+Open the configured home-page.
+.TP
+.B gH
+Open the configured home-page in a new window.
+.TP
+.B u
+Open the last closed page.
+.TP
+.B U
+Open the last closed page in a new window.
+.TP
+.BI [ \(dqx ]p
+Open the URI out of the register \fIx\fP or, if not given, from the clipboard.
+.TP
+.BI [ \(dqx ]P
+Open the URI out of the register \fIx\fP or, if not given, from the clipboard in a
+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
+.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
+.B 0, ^
+Scroll to the absolute left of the document.
+Unlike in Vim, 0 and ^ work exactly the same way.
+.TP
+.B $
+Scroll to the absolute right of the document.
+.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.
+.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.
+.sp
+Note that these 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
+.TP
+.B <CR>
+Perform a click on element containing the current highlighted search result.
+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 [ \(dqx ]y
+Yank the URI or current page into register \fIx\fP and clipboard.
+.TP
+.BI [ \(dqx ]Y
+.SH COMMAND MODE
+Commands that are listed below are ex-commands like in Vim, that are typed
+into the inputbox (the command line of vimb).
+The commands may vary in their syntax or in the parts they allow,
+but in general they follow a simple syntax.
+.PP
+.BI Syntax: " :[:| ][N]cmd[name][!][ lhs][ rhs]"
+.sp
+Where \fIlhs\fP (left hand side) must not contain any unescaped space.
+The syntax of the rhs (right hand side) if this is available depends on the
+command.
+At the moment the count parts [N] of commands is parsed, but currently there is
+no command that uses the count.
+.sp
+Commands that are typed interactivly are normally recorded into command
+history and register.
+To avoid this, the commands can be prefixed by one or more additional `:' or
+whitespace.
+.PP
+Multiple commands, separated by a `|' can be given in a single command line
+and will be executed consecutively.
+The pipe can be included as an argument to a command by escaping it with a
+backslash.
+.br
+Following commands process the entire command-line string literally.
+These commands will include any `|' as part of their argument string and so
+cannot be followed by another command.
+.PP
+.PD 0
+.IP - 2
+cmap, cnoremap, imap, inoremap, nmap, nnoremap
+.IP -
+eval
+.IP -
+normal
+.IP -
+open, tabopen
+.IP -
+shellcmd
+.PD
+.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 directly behind the prompt `:'.
+.TP
+.B CTRL\-E
+Moves the cursor after the prompt 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 about `:reg[ister]' command.
+.SS Command Line History
+.TP
+.B <Tab>
+Start completion of the content in the inputbox in forward direction.
+.TP
+.B <S-Tab>
+Start completion of the content in the inputbox in backward direction.
+.TP
+.B <Up>
+Step backward in the command history.
+.TP
+.B <Down>
+Step forward in the command history.
+Yank the current selection into register \fIx\fP and clipboard.
+.SS Open
+.TP
+.BI ":o[pen] [" URI ]
+Open the give \fIURI\fP in the current window.
+If \fIURI\fP is empty, the configured 'home-page' is opened.
+.TP
+.BI ":t[abopen] [" URI ]
+Open the give \fIURI\fP in a new window.
+If \fIURI\fP is empty, the configured 'home-page' is opened.
+.SS Key Mapping
+Key mappings allow users to alter the actions of key presses.
+Each key mapping is associated with a mode and only has effect
+when the mode is active.
+The following commands allow the user to substitute one sequence
+of key presses by another.
+.PP
+.BI Syntax: " :{m}map {lhs} {rhs}"
+.PP
+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 `\\', as shown in the examples.
+.sp
+The \fIrhs\fP starts with the first non-space char. If you want a \fIrhs\fP
+that starts with a space, you have to use "<Space>".
+.PP
+Standard key mapping commands are provided for these modes \fIm\fP:
+.PD 0
+.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 Vimb's command line.
+.PD
+.PP
+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.
+.PP
+As special key names have the format \fI<...>\fP.
+The following special keys can be used: <Left>, <Up>, <Right>, <Down>
+for the cursor keys, <Tab>, <Esc>, <CR>, <Space>, <BS>, <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"
+Example which maps two spaces to go to 50% of the page.
+.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 Shortcuts
+Shortcuts allow the opening of an URI built 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.
+.PP
+Shortcuts are convenient to use with search engines where the URI is standardised
+and 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.
+.sp
+To use spaces within the parameters, the parameters can be grouped by
+surrounding them with single-or double quotes-as 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 Misc
+.TP
+.BI ":sh[ellcmd] " cmd
+Runs the given shell \fIcmd\fP syncron and print the output into inputbox.
+The following patterns in \fIcmd\fP are expanded: '~username', '~/', '$VAR'
+and '${VAR}'.
+A '\\' before these patterns disables the expansion.
+.PP
+.RS
+.PP
+.PD 0
+The following environment variables are set for called shell commands.
+.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 Vimb window or of the embedding window if Vimb is
+started with the -e option.
+.PD
+.PP
+Example:
+.EX
+:sh ls -l $HOME
+.EE
+.RE
+.TP
+.BI ":sh[ellcmd]! " cmd
+Like :sh[ellcmd], but asyncron.
+.sp
+Example:
+.EX
+:sh! /bin/sh -c 'echo "`date` $VIMB_URI" >> myhistory.txt'
+.EE
+.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 \(dqa " - " \(dqz
+26 named registers "a to "z.
+Vimb fills these registers only when you say so.
+.TP
+.B \(dq:
+Last executed `ex` command.
+.TP
+.B \(dq"
+Last yanked content.
+.TP
+.B \(dq%
+Curent opened URI.
+.TP
+.B \(dq/
+Last search phrase.
+.PD
+.RE
+.TP
+.BI :e[val] " javascript"
+Runs the given \fIjavascript\fP in the current page and display the evaluated
+value.
+.sp
+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.
+.sp
+\fIcmds\fP cannot start with a space.
+Put a count of 1 (one) before it, "1 " is one space.
+.sp
+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 COMPLETIONS
+The completions are triggered by pressing `<Tab>` or `<S-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 initial chars are passed, the completion will lookup those
+commands that begin 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 every given word in the history URI and titles.
+Only those history items are shown, where the title or URI contains all tags.
+.sp
+Example:
+.RS
+.PD 0
+.IP ":open foo bar<Tab>"
+will complete only URIs that contain the words foo and bar.
+.PD
+.RE
+.TP
+.B search
+The search completion allows 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.
+.SH FILES
+.TP
+.IR $XDG_CONFIG_HOME/vimb[/PROFILE]
+Directory for configuration data.
+If executed with \fB-p \fIPROFILE\fR parameter, configuration is read from
+this subdirectory.
+.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 last closed browser windows.
+.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 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
+There are also some sample scripts installed together with Vimb under
+PREFIX/share/vimb/examples.
+.SH ENVIRONMENT
+.TP
+.B http_proxy
+If this variable is set to an non-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,
+for example "[::1]:443".
+.IP
+Example: "localhost,127.0.0.1,::1,fc00::/7,example.com:8080"
+.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
projects / vimb.git / commitdiff