From: Daniel Carl Date: Thu, 10 Oct 2019 00:05:04 +0000 (+0200) Subject: Simplified the man page a little. X-Git-Url: https://git.owens.tech///git?a=commitdiff_plain;h=ab0bfe9ca4e8de29ae3b5c1ea157763d8bccbb97;p=vimb.git Simplified the man page a little. --- diff --git a/doc/vimb.1 b/doc/vimb.1 index 3fb827d..d349f72 100644 --- a/doc/vimb.1 +++ b/doc/vimb.1 @@ -1,32 +1,28 @@ .\" vim: ft=groff -.ss 12 0 -.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 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. -.PP +.P Mandatory arguments to long options are mandatory for short options too. .TP .BI "\-c, \-\-config " "FILE" @@ -56,28 +52,29 @@ Do no attempt to maximize window. .TP .B "\-\-bug-info" Prints information about used libraries for bug reports and then quit. +. +. .SH MODES Vimb is modal and has the following main modes: -.TP -.B Normal Mode +.IP "Normal Mode" The default mode. Pressing Escape always enter normal mode. -.TP -.B Input Mode +.IP "Input Mode" Used for editing text elements in a webpage. -.TP -.B Command Mode +.IP "Command Mode" Execute `ex` commands from the builtin inputbox (commandline). -.TP -.B Pass-Through Mode +.IP "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. +If a command supports the count this is shown as [\fBN\fP]. +. .SS General .TP .B : @@ -101,6 +98,7 @@ 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 @@ -158,6 +156,7 @@ Reload the website without using caches. .TP .B CTRL\-C Stop loading the current page. +. .SS Motion .TP .BI [ N ]CTRL\-F @@ -210,6 +209,7 @@ Jump to the mark {\fIa-z\fP} on the current page. .B '' Jumps to the position before the latest jump, or where the last "m'" command was given. +. .SS Hinting Hinting in Vimb is how you accomplish the tasks that you would do with the mouse in common mouse-driven browsers: open a URI, yank a URI, save a page and @@ -221,32 +221,36 @@ that is part of the hinted element (like URI, link text, button label) or any combination of these methods. If is pressed, the current active hint will be fired. If only one possible hint remains, this will be fired automatically. -.PP -.BI Syntax: " ;{mode}{hint}" -.PP +.P +.BR Syntax: " ;{mode}{hint}" +.P Start Hints 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. -.PP +.P 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 many chars are required 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'}. -.PP +.P The following keys have special meanings in Hints modes: .PD 0 -.IP \fB\fP +.TP +.B Selects the first highlighted element, or the current focused. -.IP "\fB\fP" +.TP +.B Moves the focus to the next hint element. -.IP "\fB\fP" +.TP +.B Moves the focus to the previous hint element. -.IP "\fB, CTRL\-C, CTRL\-[\fP" +.TP +.B , CTRL\-C, CTRL\-[ Exits Hints mode without selecting an element. .PD .TP @@ -311,13 +315,14 @@ and into the register \fIx\fP. .PD .RE .TP -.BI Syntax: " g;{mode}{hint}" +.BR Syntax: " g;{mode}{hint}" Start an extended hints mode and stay there until is pressed. Like 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 o p P s t y Y\fP. +hint modes +.IR "I o p P s t y Y" . .PD .TP .B Motion @@ -325,7 +330,7 @@ hint modes \fII o p P s t y Y\fP. Motions commands are like those for normal mode except that CTRL is used as modifier. But they can not be used together with a count. -.PP +.P .PD 0 .TP .B CTRL-F @@ -347,13 +352,14 @@ Scroll one step down. Scroll one step up. .PD .RE +. .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 *, # +.BR * , " #" 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 @@ -372,6 +378,7 @@ Search for \fIN\fPnth previous search result depending on current search .B Perform a click on element containing the current highlighted search result. direction. +. .SS Zooming .TP .BI [ N ]zi @@ -388,6 +395,7 @@ Full-Content Zoom-Out the page by \fIN\fP steps. .TP .B zz Reset Zoom. +. .SS Yank .TP .BI [ \(dqx ]y @@ -395,13 +403,15 @@ Yank the URI or current page into register \fIx\fP and clipboard. .TP .BI [ \(dqx ]Y Yank the current selection into register x and clipboard. +. +. .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]" +.P +.BR 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 @@ -413,7 +423,7 @@ 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 +.P 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 @@ -422,7 +432,7 @@ backslash. Following commands process the entire command-line string literally. These commands will include any `|' as part of their argument string and so can not be followed by another command. -.PP +.P .PD 0 .IP - 2 autocmd @@ -437,6 +447,7 @@ open, tabopen .IP - shellcmd .PD +. .SS Command Line Editing .TP .B , CTRL\-[, CTRL-C @@ -466,6 +477,7 @@ Pass the next key press directly to GTK. .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 @@ -480,6 +492,7 @@ Step backward in the command history. .B Step forward in the command history. Yank the current selection into register \fIx\fP and clipboard. +. .SS Open .TP .BI ":o[pen] [" URI ] @@ -489,41 +502,46 @@ If \fIURI\fP is empty, the configured 'home-page' is opened. .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 +.P +.BR Syntax: " :{m}map {lhs} {rhs}" +.P 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 +.P Standard key mapping commands are provided for these modes \fIm\fP: .PD 0 -.IP \fBn\fP +.TP +.B n Normal mode: when browsing normally. -.IP \fBi\fP +.TP +.B i Insert mode: when interacting with text fields on a website. -.IP \fBc\fP +.TP +.B c Command Line mode: when typing into Vimb's command line. .PD -.PP +.P 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 +.P As special key names have the format \fI<...>\fP. The following special keys can be used: , , , for the cursor keys, , , , , , - and -. .TP +.PD 0 .BI ":nm[ap] {" lhs "} {" rhs } .TP .BI ":im[ap] {" lhs "} {" rhs } @@ -534,9 +552,7 @@ 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 +.sp .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 @@ -544,9 +560,8 @@ 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" +.IP ":nmap \e \e 50G" Example which maps two spaces to go to 50% of the page. -.PD .RE .TP .BI ":nn[oremap] {" lhs "} {" rhs } @@ -565,6 +580,8 @@ Often used to redefine a command. .TP .BI ":cu[nmap] {" lhs } Remove the mapping of \fIlhs\fP for the applicable mode. +.PD +. .SS Bookmarks .TP .BI ":bma [" tags ] @@ -573,6 +590,7 @@ Save the current opened URI with \fItags\fP to the bookmark file. .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 @@ -582,7 +600,6 @@ 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 mailto=urxvt -e mutt %s" to start email client for mailto links. @@ -595,16 +612,17 @@ to handle ftp downloads via wget. .TP .BI ":handler-remove " "handler" Remove the handler for the given URI \fIhandler\fP. +. .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 +.P 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" +.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. @@ -616,7 +634,6 @@ 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. @@ -630,14 +647,15 @@ contain spaces like `:open map "city hall, London" railway station, London' .PD .RE .TP -.BI ":shortcut-remove " "shortcut" +.BI ":shortcut-remove " shortcut Remove the search engine to the given \fIshortcut\fP. .TP -.BI ":shortcut-default " "shortcut" +.BI ":shortcut-default " shortcut Set the shortcut for given \fIshortcut\fP as the default, that is the shortcut to be used if no shortcut is given and the string to open is not an URI. 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 @@ -671,6 +689,7 @@ Show the current set value of variable. .TP .BI ":se[t] " var ! Toggle the value of boolean variable \fIvar\fP and display the new set value. +. .SS Queue The queue allows the marking of URIs for later reading. This list is shared between the single instances of Vimb. @@ -687,12 +706,13 @@ 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 +.P Autocommands are built with following properties. .TP .I group @@ -704,8 +724,8 @@ Groups are useful to remove multiple grouped autocommands. .I event You can specify a comma separated list of event names. No white space can be used in this list. +.P .RS -.PP .PD 0 Events: .TP @@ -738,7 +758,7 @@ 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 '\e,'. .RS -.PP +.P .PD 0 Patterns: .IP "\fB*\fP" @@ -797,7 +817,7 @@ The name "end" selects the default group. .TP .BI ":aug[roup]! {" name "}" Delete the autocmd group \fIname\fP. -.PP +.P Example: .EX :aug github @@ -805,6 +825,7 @@ Example: : au LoadCommitted http{s,}://github.com/* set scripts=on :aug end .EE +. .SS Misc .TP .BI ":cl[eardata] [" dataTypes "] [" timespan "]" @@ -814,7 +835,7 @@ Note that the \fIdataTypes\fP must not contain spaces. If \fItimespan\fP is not given, all website data will be removed. Note that this effects all running instances of vimb. .RS -.PP +.P .PD 0 The \fIdataTypes\fP is a comma separated list of following types. .TP @@ -851,7 +872,7 @@ Can be used to clear all known data types in case a \fItimespan\fP is used. .PD .RE .RS -.PP +.P .PD 0 The \fItimespan\fP is given as sequence of '[multiplier]\fIunit\fP' tupels with following units. @@ -874,7 +895,7 @@ minute .B s second .PD -.PP +.P .I Example: .PD 0 .IP ":cleardata" @@ -902,10 +923,10 @@ Example: 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 +A '\e' before these patterns disables the expansion. +.P .RS -.PP +.P .PD 0 The following environment variables are set for called shell commands. .TP @@ -952,11 +973,11 @@ Close the browser independent from an running download. .B :reg[ister] Display the contents of all registers. .RS -.PP +.P .PD 0 Registers: .TP -.BR \(dqa " - " \(dqz +.BR \(dqa " \(em " \(dqz 26 named registers "a to "z. Vimb fills these registers only when you say so. .TP @@ -1002,9 +1023,11 @@ Like :normal, but no mapping is applied to \fIcmds\fP. Print current document. Open a GUI dialog where you can select the printer, number of copies, orientation, etc. +. +. .SH INPUT MODE .TP -.B , CTRL\-[ +.BR , " CTRL\-[" Switch back to normal mode. .TP .B CTRL\-O @@ -1018,6 +1041,8 @@ Pass the next key press directly to WebKit. .TP .B CTRL\-Z Enter the pass-through mode. +. +. .SH COMPLETIONS The completions are triggered by pressing `` or `` in the activated inputbox. @@ -1040,13 +1065,9 @@ prefix. 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 bookmarks @@ -1054,17 +1075,13 @@ The bookmark completion is similar to the history completion, but does match only the tags of the bookmarks. The bookmark completion is started by `:open \fB!\fP`, `:tabopen \fB!\fP` or `:bmr ` and does a prefix search for all given words in the bookmark tags. -.sp -Example: .RS -.PD 0 .IP ":open \fB!\fPfoo ba" will match all bookmarks that have tags starting with "foo" and "ba". If the bookmark does not have any tags set, the URL is split on `.' and `/' into tags. .IP ":bmr tag" will match all bookmarks that have tags starting with "tag". -.PD .RE .TP .B bookmark tags @@ -1075,27 +1092,29 @@ The bookmark tag completion allows the insertion of already used bookmarks for t 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. See \fBSettings\fP under \fBCOMMAND MODE\fP for syntax. .TP -.B accelerated-2d-canvas (bool) +.BR accelerated-2d-canvas (bool) Enable or disable accelerated 2D canvas. When accelerated 2D canvas is enabled, WebKit may render some 2D canvas content using hardware accelerated drawing operations. .TP -.B allow-file-access-from-file-urls (bool) +.BR allow-file-access-from-file-urls (bool) Indicates whether file access is allowed from file URLs. By default, when something is loaded using a file URI, cross origin requests to other file resources are not allowed. .TP -.B allow-universal-access-from-file-urls (bool) +.BR allow-universal-access-from-file-urls (bool) Indicates whether or not JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. By default, when something is loaded in a using a file scheme URL, access to the local file system and arbitrary local storage is not allowed. .TP -.B caret (bool) +.BR caret (bool) Whether to enable accessibility enhanced keyboard navigation. .TP .B cookie-accept (string) @@ -1149,8 +1168,7 @@ started from, also known as referer. .B $VIMB_DOWNLOAD_PATH Setting value of 'download-path' which would be used normally for downloads. .PD -.PP -Example: +.P .PD 0 .IP ":set download-command=/bin/sh -c ""cd '$VIMB_DOWNLOAD_PATH' \ && curl -sLJOC - -e '$VIMB_URI' %s""" @@ -1190,13 +1208,16 @@ Show the current window full-screen. This setting decides how to enable and disable hardware acceleration. .PD 0 .RS -.IP - 2 -`ondemand' enables the hardware acceleration when the web contents request it, disabling it again when no -longer needed. -.IP - 2 -`always' enforce hardware acceleration to be enabled. -.IP - 2 -`never' disables it completely. +.TP +.B ondemand +enables the hardware acceleration when the web contents request it, disabling +it again when no longer needed. +.TP +.B always +enforce hardware acceleration to be enabled. +.TP +.B never +disables it completely. Note that disabling hardware acceleration might cause some websites to not render correctly or consume more CPU. .RE @@ -1222,8 +1243,7 @@ or to open current page new by `O`. To use '=' within a header value the value must be quoted like shown in Example for the Cookie header. .RS -.PP -Example: +.P .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 @@ -1365,7 +1385,9 @@ Number of pixel vimb scrolls if 'j' or 'k' is used. The font family used as the default for content using serif font. .TP .B show-titlebar (bool) -Determines whether the titlebar is shown (on systems that provide window decoration). Defaults to true. +Determines whether the titlebar is shown (on systems that provide window +decoration). +Defaults to true. .TP .B site-specific-quirks (bool) Enables the site-specific compatibility workarounds. @@ -1460,6 +1482,8 @@ This fills the inputbox with the prefilled download command and replaces Whether to enable the XSS auditor. This feature filters some kinds of reflective XSS attacks on vulnerable web sites. +. +. .SH FILES .TP .IR $XDG_CONFIG_HOME/vimb[/PROFILE] @@ -1511,15 +1535,21 @@ These file is used if the config variable `stylesheet' is enabled. .TP There are also some sample scripts installed together with Vimb under PREFIX/share/vimb/examples. +. +. .SH ENVIRONMENT .TP .B http_proxy, HTTP_PROXY If either environment variable is non-empty, the specified host and optional port is used to tunnel requests. For example: HTTP_PROXY=localhost:8118. +. +. .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