From 2cbadab4ceb262a0d0f741ce994e337f3a95fa99 Mon Sep 17 00:00:00 2001 From: Daniel Carl Date: Wed, 19 Oct 2016 22:07:19 +0200 Subject: [PATCH] Added manual page. --- Makefile | 6 +- doc/vimb.1 | 672 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 675 insertions(+), 3 deletions(-) create mode 100644 doc/vimb.1 diff --git a/Makefile b/Makefile index 912bf66..9cb1bf0 100644 --- a/Makefile +++ b/Makefile @@ -26,9 +26,9 @@ install: vimb install -m 644 $(SRCDIR)/webextension/$(EXTTARGET) $(EXTPREFIX)/$(EXTTARGET) @# man page install -d $(MANPREFIX)/man1 - # @sed -e "s!VERSION!$(VERSION)!g" \ - # -e "s!PREFIX!$(PREFIX)!g" \ - # -e "s!DATE!`date +'%m %Y'`!g" $(DOCDIR)/vimb.1 > $(MANPREFIX)/man1/vimb.1 + @sed -e "s!VERSION!$(VERSION)!g" \ + -e "s!PREFIX!$(PREFIX)!g" \ + -e "s!DATE!`date +'%m %Y'`!g" $(DOCDIR)/vimb.1 > $(MANPREFIX)/man1/vimb.1 @# .desktop file install -d $(DOTDESKTOPPREFIX) install -m 644 vimb.desktop $(DOTDESKTOPPREFIX)/vimb.desktop diff --git a/doc/vimb.1 b/doc/vimb.1 new file mode 100644 index 0000000..bf780c6 --- /dev/null +++ b/doc/vimb.1 @@ -0,0 +1,672 @@ +.\" 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 `` and `` 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 +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 , CTRL\-[, CTRL-C +Ignore all typed content and switch back to normal mode. +.TP +.B +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 +Start completion of the content in the inputbox in forward direction. +.TP +.B +Start completion of the content in the inputbox in backward direction. +.TP +.B +Step backward in the command history. +.TP +.B +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 "". +.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: , , , +for the cursor keys, , , , , , - and -. +.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 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 :set scripts=on:open !glib" +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 `` or `` 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" +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 -- 2.20.1