diff options
Diffstat (limited to 'doc/cha-config.5')
| -rw-r--r-- | doc/cha-config.5 | 1514 |
1 files changed, 1514 insertions, 0 deletions
diff --git a/doc/cha-config.5 b/doc/cha-config.5 new file mode 100644 index 00000000..c5b71eba --- /dev/null +++ b/doc/cha-config.5 @@ -0,0 +1,1514 @@ +'\" t +.\" Automatically generated by Pandoc 2.17.1.1 +.\" +.\" Define V font for inline verbatim, using C font in formats +.\" that render this, and otherwise B font. +.ie "\f[CB]x\f[]"x" \{\ +. ftr V B +. ftr VI BI +. ftr VB B +. ftr VBI BI +.\} +.el \{\ +. ftr V CR +. ftr VI CI +. ftr VB CB +. ftr VBI CBI +.\} +.TH "cha-config" "5" "" "" "Configuration of Chawan" +.hy +.SH Configuration of Chawan +.PP +Chawan supports configuration of various options like keybindings, user +stylesheets, site preferences, etc. +The configuration format is very similar to toml, with the following +exceptions: +.IP \[bu] 2 +Inline tables may span across multiple lines. +.IP \[bu] 2 +Table arrays can be cleared by setting a variable by the same to the +empty array. +This allows users to disable default table array rules. +.PP +Example: +.IP +.nf +\f[C] +omnirule = [] # note: this must be placed at the beginning of the file. + +[[omnirule]] # this is legal. all default omni-rules are now disabled. +\f[R] +.fi +.PP +Chawan will look for a config file in the $XDG_CONFIG_HOME/chawan/ +directory called \f[V]config.toml\f[R]. +(Chawan defaults to \[ti]/.config if the XDG_CONFIG_HOME environment +variable is not set.) +See the default configuration file in the res/ folder, and bonus +configuration files in the bonus/ folder for further examples. +.SS Start +.PP +Start-up options are to be placed in the \f[V][start]\f[R] section. +.PP +Following is a list of start-up options: +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +visual-home +T}@T{ +url +T}@T{ +Page opened when Chawan is called with the -V option (and no other pages +are passed as arguments.) +T}@T{ +T} +T{ +startup-script +T}@T{ +JavaScript code +T}@T{ +Script Chawan runs on start-up. +Pages will not be loaded until this function exits. +(Note however that asynchronous functions like setTimeout do not block +loading.) +T}@T{ +T} +T{ +headless +T}@T{ +boolean +T}@T{ +Whether Chawan should always start in headless mode. +Automatically enabled when Chawan is called with -r. +T}@T{ +T} +T{ +console-buffer +T}@T{ +boolean +T}@T{ +Whether Chawan should open a console buffer in non-headless mode. +Defaults to true. +Warning: this is only useful for debugging. +Disabling this option without manually redirecting standard error will +result in error messages randomly appearing on your screen. +T}@T{ +T} +.TE +.SS Search +.PP +Search options are to be placed in the \f[V][search]\f[R] section. +.PP +Following is a list of search options: +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +wrap +T}@T{ +boolean +T}@T{ +When set to true, searchNext/searchPrev wraps around the document. +T}@T{ +T} +T{ +ignore-case +T}@T{ +boolean +T}@T{ +When set to true, document-wide searches are case-insensitive by +default. +Note: this can also be overridden inline in the search bar (vim-style), +with the escape sequences \f[V]c\f[R] (ignore case) and \f[V]C\f[R] +(strict case). +See search mode for details.) +T}@T{ +T} +.TE +.SS Encoding +.PP +Encoding options are to be placed in the \f[V][encoding]\f[R] section. +.PP +Following is a list of encoding options: +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +document-charset +T}@T{ +array of charset label strings +T}@T{ +List of character sets for loading documents. +All listed character sets are enumerated until the document has been +decoded without errors. +In HTML, meta tags and the BOM may override this with a different +charset, so long as the specified charset can decode the document +correctly. +T}@T{ +T} +T{ +display-charset +T}@T{ +string +T}@T{ +Character set for keyboard input and displaying documents. +Used in dump mode as well. +(This means that e.g.\ \f[V]cha -I EUC-JP -O UTF-8 a > b\f[R] is +equivalent to \f[V]iconv -f EUC-JP -t UTF-8\f[R].) +T}@T{ +T} +.TE +.SS External +.PP +External options are to be placed in the \f[V][external]\f[R] section. +.PP +Following is a list of external options: +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +tmpdir +T}@T{ +path +T}@T{ +Directory used to save temporary files. +T}@T{ +T} +T{ +editor +T}@T{ +shell command +T}@T{ +External editor command. +%s is substituted for the file name, %d for the line number. +T}@T{ +T} +T{ +mailcap +T}@T{ +array of paths +T}@T{ +Search path for mailcap files. +(See \f[B]cha-mailcap\f[R](5) for details.) +T}@T{ +T} +T{ +mime-types +T}@T{ +array of paths +T}@T{ +Search path for mime.types files. +(See \f[B]cha-mime.types\f[R](5) for details.) +T}@T{ +T} +T{ +cgi-dir +T}@T{ +array of paths +T}@T{ +Search path for local CGI scripts. +(See \f[B]cha-localcgi\f[R](5) for details.) +T}@T{ +T} +T{ +urimethodmap +T}@T{ +array of paths +T}@T{ +Search path for urimethodmap files. +(See \f[B]cha-urimethodmap\f[R](5) for details.) +T}@T{ +T} +T{ +w3m-cgi-compat +T}@T{ +boolean +T}@T{ +Enable local CGI compatibility with w3m. +In short, it redirects \f[V]file:///cgi-bin/*\f[R] and +\f[V]file:///$LIB/cgi-bin/*\f[R] to \f[V]cgi-bin:*\f[R]. +For further details, see \f[B]cha-localcgi\f[R](5). +T}@T{ +T} +T{ +download-dir +T}@T{ +string +T}@T{ +Path to pre-fill for \[lq]Save to:\[rq] prompts. +This is not validated, you can set it to whatever you find useful. +T}@T{ +T} +.TE +.SS Input +.PP +Input options are to be placed in the \f[V][input]\f[R] section. +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +vi-numeric-prefix +T}@T{ +boolean +T}@T{ +Whether vi-style numeric prefixes to commands should be accepted. +When set to true, commands that return a function will be called with +the numeric prefix as their first argument. +Note: this only applies for keybindings defined in [page]. +T}@T{ +T} +T{ +use-mouse +T}@T{ +boolean +T}@T{ +Whether Chawan is allowed to use the mouse. +Currently, the default behavior imitates that of w3m. +T}@T{ +T} +.TE +.PP +Examples: +.IP +.nf +\f[C] +[input] +vi-numeric-prefix = true + +[page] +# Here, the arrow function will be called with the vi numbered prefix if +# one was input, and with no argument otherwise. +# The numeric prefix can never be zero, so it is safe to test for undefined +# using the ternary operator. +G = \[aq]n => n ? pager.gotoLine(n) : pager.cursorLastLine()\[aq] +\f[R] +.fi +.SS Network +.PP +Network options are to be placed in the \f[V][network]\f[R] section. +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +max-redirect +T}@T{ +number +T}@T{ +Maximum number of redirections to follow. +T}@T{ +T} +T{ +prepend-scheme +T}@T{ +string +T}@T{ +Prepend this to URLs passed to Chawan without a scheme. +Note that local files (\f[V]file:\f[R] scheme) will always be checked +first; only if this fails, Chawan will retry the request with +\f[V]prepend-scheme\f[R] set as the scheme. +By default, this is set to \[lq]https://\[rq]. +Note that the \[lq]://\[rq] part is mandatory. +T}@T{ +T} +T{ +prepend-https +T}@T{ +boolean +T}@T{ +Deprecated: use prepend-scheme instead. +When set to false, Chawan will act as if prepend-scheme were set to +\[lq]\[lq]. +T}@T{ +T} +T{ +proxy +T}@T{ +URL +T}@T{ +Specify a proxy for all network requests Chawan makes. +All proxies supported by cURL may be used. +Can be overridden by siteconf. +T}@T{ +T} +T{ +default-headers +T}@T{ +Table +T}@T{ +Specify a list of default headers for all HTTP(S) network requests. +Can be overridden by siteconf. +T}@T{ +T} +.TE +.SS Display +.PP +Display options are to be placed in the \f[V][display]\f[R] section. +.PP +Following is a list of display options: +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +color-mode +T}@T{ +\[lq]monochrome\[rq] / \[lq]ansi\[rq] / \[lq]eight-bit\[rq] / +\[lq]true-color\[rq] / \[lq]auto\[rq] +T}@T{ +Set the color mode. +\[lq]auto\[rq] for automatic detection, \[lq]monochrome\[rq] for black +on white, \[lq]ansi\[rq] for ansi colors, \[lq]eight-bit\[rq] for +256-color mode, and \[lq]true-color\[rq] for true colors. +\[lq]8bit\[rq] is accepted as a legacy alias of \[lq]eight-bit\[rq]. +\[lq]24bit\[rq] is accepted as a legacy alias of \[lq]true-color\[rq]. +T}@T{ +T} +T{ +format-mode +T}@T{ +\[lq]auto\[rq] / [\[lq]bold\[rq], \[lq]italic\[rq], \[lq]underline\[rq], +\[lq]reverse\[rq], \[lq]strike\[rq], \[lq]overline\[rq], +\[lq]blink\[rq]] +T}@T{ +Specifies output formatting modes. +Accepts the string \[lq]auto\[rq] or an array of specific attributes. +An empty array (\f[V][]\f[R]) disables formatting completely. +T}@T{ +T} +T{ +no-format-mode +T}@T{ +[\[lq]bold\[rq], \[lq]italic\[rq], \[lq]underline\[rq], +\[lq]reverse\[rq], \[lq]strike\[rq], \[lq]overline\[rq], +\[lq]blink\[rq]] +T}@T{ +Disable specified formatting modes. +T}@T{ +T} +T{ +emulate-overline +T}@T{ +boolean +T}@T{ +When set to true and the overline formatting attribute is not enabled, +overlines are substituted by underlines on the previous line. +T}@T{ +T} +T{ +alt-screen +T}@T{ +\[lq]auto\[rq] / boolean +T}@T{ +Enable/disable the alternative screen. +T}@T{ +T} +T{ +highlight-color +T}@T{ +color +T}@T{ +Set the highlight color. +Both hex values and CSS color names are accepted. +T}@T{ +T} +T{ +highlight-marks +T}@T{ +boolean +T}@T{ +Enable/disable highlighting of marks. +T}@T{ +T} +T{ +double-width-ambiguous +T}@T{ +boolean +T}@T{ +Assume the terminal displays characters in the East Asian Ambiguous +category as double-width characters. +Useful when e.g.\ \[ci] occupies two cells. +T}@T{ +T} +T{ +minimum-contrast +T}@T{ +number +T}@T{ +Specify the minimum difference between the luminance (Y) of the +background and the foreground. +-1 disables this function (i.e.\ allows black letters on black +background, etc). +T}@T{ +T} +T{ +force-clear +T}@T{ +boolean +T}@T{ +Force the screen to be completely cleared every time it is redrawn. +T}@T{ +T} +T{ +set-title +T}@T{ +boolean +T}@T{ +Set the terminal emulator\[cq]s window title to that of the current +page. +T}@T{ +T} +T{ +default-background-color +T}@T{ +\[lq]auto\[rq] / color +T}@T{ +Overrides the assumed background color of the terminal. +\[lq]auto\[rq] leaves background color detection to Chawan. +T}@T{ +T} +T{ +default-foreground-color +T}@T{ +\[lq]auto\[rq] / color +T}@T{ +Sets the assumed foreground color of the terminal. +\[lq]auto\[rq] leaves foreground color detection to Chawan. +T}@T{ +T} +T{ +query-da1 +T}@T{ +bool +T}@T{ +Enable/disable querying Primary Device Attributes, and with it, all +\[lq]dynamic\[rq] terminal querying. +It is highly recommended not to alter the default value (which is true), +or the output will most likely look horrible. +(Except, obviously, if your terminal does not support Primary Device +Attributes.) +T}@T{ +T} +T{ +columns, lines, pixels-per-column, pixels-per-line +T}@T{ +number +T}@T{ +Fallback values for the number of columns, lines, pixels per column, and +pixels per line for the cases where it cannot be determined +automatically. +(For example, these values are used in dump mode.) +T}@T{ +T} +T{ +force-columns, force-lines, force-pixels-per-column, +force-pixels-per-line +T}@T{ +boolean +T}@T{ +Force-set columns, lines, pixels per column, or pixels per line to the +fallback values provided above. +T}@T{ +T} +.TE +.SS Omnirule +.PP +The omni-bar (by default opened with C-l) can be used to perform +searches using omni-rules. +These are to be placed in the table array \f[V][[omnirule]]\f[R]. +.PP +Examples: +.IP +.nf +\f[C] +# Search using DuckDuckGo Lite. (Bound to C-k by default.) +[[omnirule]] +match = \[aq]\[ha]ddg:\[aq] +substitute-url = \[aq](x) => \[dq]https://lite.duckduckgo.com/lite/?kp=-1&kd=-1&q=\[dq] + encodeURIComponent(x.split(\[dq]:\[dq]).slice(1).join(\[dq]:\[dq]))\[aq] + +# Search using Wikipedia, Firefox-style. +[[omnirule]] +match = \[aq]\[ha]\[at]wikipedia\[aq] +substitute-url = \[aq](x) => \[dq]https://en.wikipedia.org/wiki/Special:Search?search=\[dq] + encodeURIComponent(x.replace(/\[at]wikipedia/, \[dq]\[dq]))\[aq] +\f[R] +.fi +.PP +Omnirule options: +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +match +T}@T{ +regex +T}@T{ +Regular expression used to match the input string. +Note that websites passed as arguments are matched as well. +Note: regexes are handled according to the match mode regex handling +rules. +T}@T{ +T} +T{ +substitute-url +T}@T{ +JavaScript function +T}@T{ +A JavaScript function Chawan will pass the input string to. +If a new string is returned, it will be parsed instead of the old one. +T}@T{ +T} +.TE +.SS Siteconf +.PP +Configuration options can be specified for individual sites. +Entries are to be placed in the table array \f[V][[siteconf]]\f[R]. +.PP +Examples: +.IP +.nf +\f[C] +# Enable cookies on the orange website for log-in. +[[siteconf]] +url = \[aq]https://news.ycombinator.com/.*\[aq] +cookie = true + +# Redirect npr.org to text.npr.org. +[[siteconf]] +host = \[aq](www.)?npr.org\[aq] +rewrite-url = \[aq]\[aq]\[aq] +(x) => { +x.host = \[dq]text.npr.org\[dq]; +const s = x.pathname.split(\[aq]/\[aq]); +x.pathname = s.at(s.length > 2 ? -2 : 1); +/* No need to return; URL objects are passed by reference. */ +} +\[aq]\[aq]\[aq] + +# Allow cookie sharing on *sr.ht domains. +[[siteconf]] +host = \[aq](.*.)?sr.ht\[aq] # either \[aq]something.sr.ht\[aq] or \[aq]sr.ht\[aq] +cookie = true # enable cookies +share-cookie-jar = \[aq]sr.ht\[aq] # use the cookie jar of \[aq]sr.ht\[aq] for all matched hosts +third-party-cookie = \[aq].*.sr.ht\[aq] # allow cookies from subdomains +\f[R] +.fi +.PP +Siteconf options: +.PP +.TS +tab(@); +lw(15.6n) lw(19.4n) lw(31.1n) lw(3.9n). +T{ +Name +T}@T{ +Value +T}@T{ +Function +T}@T{ +T} +_ +T{ +url +T}@T{ +regex +T}@T{ +Regular expression used to match the URL. +Either this or the \f[V]host\f[R] option must be specified. +Note: regexes are handled according to the match mode regex handling +rules. +T}@T{ +T} +T{ +host +T}@T{ +regex +T}@T{ +Regular expression used to match the host part of the URL (i.e.\ domain +name/ip address.) +Either this or the \f[V]url\f[R] option must be specified. +Note: regexes are handled according to the match mode regex handling +rules. +T}@T{ +T} +T{ +rewrite-url +T}@T{ +JavaScript function +T}@T{ +A JavaScript function Chawan will pass the URL to. +If a new URL is returned, it will replace the old one. +T}@T{ +T} +T{ +cookie +T}@T{ +boolean +T}@T{ +Whether loading cookies should be allowed for this URL. +By default, this is false for all websites. +T}@T{ +T} +T{ +third-party-cookie +T}@T{ +array of regexes +T}@T{ +Domains for which third-party cookies are allowed on this domain. +Note: this only works for buffers which share the same cookie jar. +Note: regexes are handled according to the match mode regex handling +rules. +T}@T{ +T} +T{ +share-cookie-jar +T}@T{ +host +T}@T{ +Cookie jar to use for this domain. +Useful for e.g.\ sharing cookies with subdomains. +T}@T{ +T} +T{ +referer-from +T}@T{ +boolean +T}@T{ +Whether or not we should send a Referer header when opening requests +originating from this domain. +Simplified example: if you click a link on a.com that refers to b.com, +and referer-from is true, b.com is sent \[lq]a.com\[rq] as the Referer +header. +Defaults to false. +T}@T{ +T} +T{ +scripting +T}@T{ +boolean +T}@T{ +Enable/disable JavaScript execution on this site. +T}@T{ +T} +T{ +document-charset +T}@T{ +boolean +T}@T{ +Specify the default encoding for this site. +Overrides document-charset in encoding. +T}@T{ +T} +T{ +stylesheet +T}@T{ +CSS stylesheet +T}@T{ +Specify an additional user-stylesheet for this site. +Note: other user-stylesheets (specified under [css] or additional +matching siteconfs) are not overridden. +(In other words, they will be concatenated with this stylesheet to get +the final user stylesheet.) +T}@T{ +T} +T{ +proxy +T}@T{ +URL +T}@T{ +Specify a proxy for network requests fetching contents of this buffer. +T}@T{ +T} +T{ +default-headers +T}@T{ +Table +T}@T{ +Specify a list of default headers for HTTP(S) network requests to this +buffer. +T}@T{ +T} +.TE +.SS Stylesheets +.PP +User stylesheets are to be placed in the \f[V][css]\f[R] section. +.PP +There are two ways to import user stylesheets: +.IP "1." 3 +Include a user stylesheet using the format +\f[V]include = \[aq]path-to-user.css\[aq]\f[R]. +To include multiple stylesheets, use +\f[V]include = [\[aq]first-stylesheet.css, second-stylesheet.css\[aq]]\f[R]. +Relative paths are interpreted relative to the config directory. +.IP "2." 3 +Place your stylesheet directly in your configuration file using +\f[V]inline = \[dq]\[dq]\[dq]your-style\[dq]\[dq]\[dq]\f[R]. +.SS Keybindings +.PP +Keybindings are to be placed in these sections: +.IP \[bu] 2 +for pager interaction: \f[V][page]\f[R] +.IP \[bu] 2 +for line editing: \f[V][line]\f[R] +.PP +Keybindings are configured using the syntax +.PP +`' = `' +.PP +Where \f[V]<keybinding>\f[R] is a combination of unicode characters with +or without modifiers. +Modifiers are the prefixes \f[V]C-\f[R] and \f[V]M-\f[R], which add +control or escape to the keybinding respectively (essentially making +\f[V]M-\f[R] the same as \f[V]C-[\f[R]). +Modifiers can be escaped with the \[ga]\[ga] sign. +.PP +\f[V]<action>\f[R] is either a command defined in the \f[V][cmd]\f[R] +section, or a JavaScript expression. +Here we only describe the pre-defined actions in the default config; for +a description of the API, please see: +.PP +The API documentation at \f[B]cha-api\f[R](5). +.PP +Examples: +.IP +.nf +\f[C] +# show change URL when Control, Escape and j are pressed +\[aq]C-M-j\[aq] = \[aq]cmd.pager.load\[aq] +# go to the first line of the page when g is pressed twice without a preceding +# number, or to the line when a preceding number is given. +\[aq]gg\[aq] = \[aq]cmd.pager.gotoLineOrStart\[aq] +\f[R] +.fi +.SS Browser actions +.PP +.TS +tab(@); +lw(21.5n) lw(43.1n) lw(5.4n). +T{ +Name +T}@T{ +Function +T}@T{ +T} +_ +T{ +\f[V]cmd.pager.quit\f[R] +T}@T{ +Exit the browser. +T}@T{ +T} +T{ +\f[V]cmd.pager.suspend\f[R] +T}@T{ +Temporarily suspend the browser Note: this also suspends e.g.\ buffer +processes or CGI scripts. +So if you are downloading something, that will be delayed until you +restart the process. +T}@T{ +T} +.TE +.SS Pager actions +.PP +Note: \f[V]n\f[R] in the following text refers to a number preceding the +action. +e.g. +in \f[V]10gg\f[R], n = 10. +If no preceding number is input, then it is left unspecified. +.PP +.TS +tab(@); +lw(21.5n) lw(43.1n) lw(5.4n). +T{ +Name +T}@T{ +Function +T}@T{ +T} +_ +T{ +\f[V]cmd.pager.cursorUp\f[R] +T}@T{ +Move the cursor upwards by n lines, or if n is unspecified, by 1. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorDown\f[R] +T}@T{ +Move the cursor downwards by n lines, or if n is unspecified, by 1. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorLeft\f[R] +T}@T{ +Move the cursor to the left by n cells, or if n is unspecified, by 1. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorRight\f[R] +T}@T{ +Move the cursor to the right by n cells, or if n is unspecified, by 1. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorLineBegin\f[R] +T}@T{ +Move the cursor to the first cell of the line. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorLineTextStart\f[R] +T}@T{ +Move the cursor to the first non-blank character of the line. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorLineEnd\f[R] +T}@T{ +Move the cursor to the last cell of the line. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorNextWord\f[R], +\f[V]cmd.pager.cursorNextViWord\f[R], +\f[V]cmd.pager.cursorNextBigWord\f[R] +T}@T{ +Move the cursor to the beginning of the next word. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorPrevWord\f[R], +\f[V]cmd.pager.cursorPrevViWord\f[R], +\f[V]cmd.pager.cursorPrevBigWord\f[R] +T}@T{ +Move the cursor to the end of the previous word. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorWordEnd\f[R], \f[V]cmd.pager.cursorViWordEnd\f[R], +\f[V]cmd.pager.cursorBigWordEnd\f[R] +T}@T{ +Move the cursor to the end of the current word, or if already there, to +the end of the next word. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorWordBegin\f[R], +\f[V]cmd.pager.cursorViWordBegin\f[R], +\f[V]cmd.pager.cursorBigWordBegin\f[R] +T}@T{ +Move the cursor to the beginning of the current word, or if already +there, to the end of the previous word. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorPrevLink\f[R] +T}@T{ +Move the cursor to the beginning of the previous clickable element. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorNextLink\f[R] +T}@T{ +Move the cursor to the beginning of the next clickable element. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorPrevParagraph\f[R] +T}@T{ +Move the cursor to the beginning of the nth next paragraph. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorNextParagraph\f[R] +T}@T{ +Move the cursor to the end of the nth previous paragraph. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorRevNthLink\f[R] +T}@T{ +Move the cursor to the nth link of the document, counting backwards from +the document\[cq]s last line. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorNthLink\f[R] +T}@T{ +Move the cursor to the nth link of the document. +T}@T{ +T} +T{ +\f[V]cmd.pager.pageUp\f[R], \f[V]cmd.pager.pageDown\f[R], +\f[V]cmd.pager.pageLeft\f[R], \f[V]cmd.pager.pageRight\f[R] +T}@T{ +Scroll up/down/left/right by n pages, or if n is unspecified, by one +page. +T}@T{ +T} +T{ +\f[V]cmd.pager.halfPageUp\f[R], \f[V]cmd.pager.halfPageDown\f[R], +\f[V]cmd.pager.halfPageLeft\f[R], \f[V]pager.halfPageUp\f[R] +T}@T{ +Scroll up/down/left/right by n half pages, or if n is unspecified, by +one page. +T}@T{ +T} +T{ +\f[V]cmd.pager.scrollUp\f[R], \f[V]cmd.pager.scrollDown\f[R], +\f[V]cmd.pager.scrollLeft\f[R], \f[V]cmd.pager.scrollRight\f[R] +T}@T{ +Scroll up/down/left/right by n lines, or if n is unspecified, by one +line. +T}@T{ +T} +T{ +\f[V]cmd.pager.click\f[R] +T}@T{ +Click the HTML element currently under the cursor. +T}@T{ +T} +T{ +\f[V]cmd.pager.load\f[R] +T}@T{ +Open the current address in the URL bar. +T}@T{ +T} +T{ +\f[V]cmd.pager.webSearch\f[R] +T}@T{ +Open the URL bar with an arbitrary search engine. +At the moment, this is DuckDuckGo Lite. +(Note: Chawan developers aren\[cq]t affiliated with DuckDuckGo the +company or their product in any way.) +T}@T{ +T} +T{ +\f[V]cmd.pager.dupeBuffer\f[R] +T}@T{ +Duplicate the current buffer by loading its source to a new buffer. +T}@T{ +T} +T{ +\f[V]cmd.pager.discardBuffer\f[R] +T}@T{ +Discard the current buffer, and move back to its previous sibling +buffer, or if that doesn\[cq]t exist, to its parent. +If the current buffer is a root buffer (i.e.\ it has no parent), move to +the next sibling buffer instead. +T}@T{ +T} +T{ +\f[V]cmd.pager.discardTree\f[R] +T}@T{ +Discard all child buffers of the current buffer. +T}@T{ +T} +T{ +\f[V]cmd.pager.reload\f[R] +T}@T{ +Open a new buffer with the current buffer\[cq]s URL, replacing the +current buffer. +T}@T{ +T} +T{ +\f[V]cmd.pager.reshape\f[R] +T}@T{ +Reshape the current buffer (=render the current page anew.) +T}@T{ +T} +T{ +\f[V]cmd.pager.redraw\f[R] +T}@T{ +Redraw screen contents. +Useful if something messed up the display. +T}@T{ +T} +T{ +\f[V]cmd.pager.toggleSource\f[R] +T}@T{ +If viewing an HTML buffer, open a new buffer with its source. +Otherwise, open the current buffer\[cq]s contents as HTML. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorFirstLine\f[R], \f[V]cmd.pager.cursorLastLine\f[R] +T}@T{ +Move to the beginning/end in the buffer. +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorTop\f[R] +T}@T{ +Move to the first line on the screen. +(Equivalent to H in vi.) +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorMiddle\f[R] +T}@T{ +Move to the line in the middle of the screen. +(Equivalent to M in vi.) +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorBottom\f[R] +T}@T{ +Move to the last line on the screen. +(Equivalent to L in vi.) +T}@T{ +T} +T{ +\f[V]cmd.pager.raisePage\f[R], \f[V]cmd.pager.raisePageBegin\f[R], +\f[V]cmd.pager.centerLine\f[R], \f[V]cmd.pager.centerLineBegin\f[R], +\f[V]cmd.pager.lowerPage\f[R], \f[V]cmd.pager.lowerPageBegin\f[R] +T}@T{ +If n is specified, move cursor to line n.\ Then, * \f[V]raisePage\f[R] +scrolls down so that the cursor is on the top line of the screen. +(vi \f[V]z<CR>\f[R], vim \f[V]zt\f[R].) +* \f[V]centerLine\f[R] shifts the screen so that the cursor is in the +middle of the screen. +(vi \f[V]z.\f[R], vim \f[V]zz\f[R].) +* \f[V]lowerPage\f[R] scrolls up so that the cursor is on the bottom +line of the screen. +(vi \f[V]z-\f[R], vim \f[V]zb\f[R].) +The -\f[V]Begin\f[R] variants also move the cursor to the line\[cq]s +first non-blank character, as the variants originating from vi do. +T}@T{ +T} +T{ +\f[V]cmd.pager.nextPageBegin\f[R] +T}@T{ +If n is specified, move to the screen before the nth line and raise the +page. +Otherwise, go to the previous screen\[cq]s last line and raise the page. +(\f[V]z+\f[R] in vi.) +T}@T{ +T} +T{ +\f[V]cmd.pager.previousPageBegin\f[R] +T}@T{ +If n is specified, move to the screen before the nth line and raise the +page. +Otherwise, go to the previous screen\[cq]s last line and raise the page. +(\f[V]z+\f[R] in vi.) +T}@T{ +T} +T{ +\f[V]cmd.pager.cursorLeftEdge\f[R], +\f[V]cmd.pager.cursorMiddleColumn\f[R], +\f[V]cmd.pager.cursorRightEdge\f[R] +T}@T{ +Move to the first/middle/last column on the screen. +T}@T{ +T} +T{ +\f[V]cmd.pager.centerColumn\f[R] +T}@T{ +Center screen around the current column. +(w3m \f[V]Z\f[R].) +T}@T{ +T} +T{ +\f[V]cmd.pager.lineInfo\f[R] +T}@T{ +Display information about the current line on the status line. +T}@T{ +T} +T{ +\f[V]cmd.pager.searchForward\f[R], \f[V]cmd.pager.searchBackward\f[R] +T}@T{ +Search for a string in the current buffer, forwards or backwards. +T}@T{ +T} +T{ +\f[V]cmd.pager.isearchForward\f[R], \f[V]cmd.pager.searchBackward\f[R] +T}@T{ +Incremental-search for a string, highlighting the first result, forwards +or backwards. +T}@T{ +T} +T{ +\f[V]cmd.pager.gotoLineOrStart\f[R], \f[V]cmd.pager.gotoLineOrEnd\f[R] +T}@T{ +If n is specified, jump to line n.\ Otherwise, jump to the start/end of +the page. +T}@T{ +T} +T{ +\f[V]cmd.pager.searchNext\f[R], \f[V]cmd.pager.searchPrev\f[R] +T}@T{ +Jump to the nth (or if unspecified, first) next/previous search result. +T}@T{ +T} +T{ +\f[V]cmd.pager.peek\f[R] +T}@T{ +Display a message of the current buffer\[cq]s URL on the status line. +T}@T{ +T} +T{ +\f[V]cmd.pager.peekCursor\f[R] +T}@T{ +Display a message of the URL or title under the cursor on the status +line. +Multiple calls allow cycling through the two. +(i.e.\ by default, press u once -> title, press again -> URL) +T}@T{ +T} +T{ +\f[V]cmd.pager.setMark\f[R] +T}@T{ +Wait for a character \f[V]x\f[R] and then set a mark with the ID +\f[V]x\f[R]. +T}@T{ +T} +T{ +\f[V]cmd.pager.gotoMark\f[R], \f[V]cmd.pager.gotoMarkY\f[R] +T}@T{ +Wait for a character \f[V]x\f[R] and then jump to the mark with the ID +\f[V]x\f[R] (if it exists on the page). +\f[V]gotoMark\f[R] sets both the X and Y positions; gotoMarkY only sets +the Y position. +T}@T{ +T} +T{ +\f[V]cmd.pager.markURL\f[R] +T}@T{ +Convert URL-like strings to anchors on the current page. +T}@T{ +T} +T{ +\f[V]cmd.pager.saveLink\f[R] +T}@T{ +Save resource from the URL pointed to by the cursor to the disk. +T}@T{ +T} +T{ +\f[V]cmd.pager.saveSource\f[R] +T}@T{ +Save the source of the current buffer to the disk. +T}@T{ +T} +.TE +.SS Line-editing actions +.PP +.TS +tab(@); +lw(21.5n) lw(43.1n) lw(5.4n). +T{ +Name +T}@T{ +Function +T}@T{ +T} +_ +T{ +\f[V]cmd.line.submit\f[R] +T}@T{ +Submit line +T}@T{ +T} +T{ +\f[V]cmd.line.cancel\f[R] +T}@T{ +Cancel operation +T}@T{ +T} +T{ +\f[V]cmd.line.backspace\f[R] +T}@T{ +Delete character before cursor +T}@T{ +T} +T{ +\f[V]cmd.line.delete\f[R] +T}@T{ +Delete character after cursor +T}@T{ +T} +T{ +\f[V]cmd.line.clear\f[R] +T}@T{ +Clear text before cursor +T}@T{ +T} +T{ +\f[V]cmd.line.kill\f[R] +T}@T{ +Clear text after cursor +T}@T{ +T} +T{ +\f[V]cmd.line.clearWord\f[R] +T}@T{ +Delete word before cursor +T}@T{ +T} +T{ +\f[V]cmd.line.killWord\f[R] +T}@T{ +Delete word after cursor +T}@T{ +T} +T{ +\f[V]cmd.line.backward\f[R] +T}@T{ +Move cursor back by one character +T}@T{ +T} +T{ +\f[V]cmd.line.forward\f[R] +T}@T{ +Move cursor forward by one character +T}@T{ +T} +T{ +\f[V]cmd.line.prevWord\f[R] +T}@T{ +Move cursor to the previous word by one character +T}@T{ +T} +T{ +\f[V]cmd.line.nextWord\f[R] +T}@T{ +Move cursor to the previous word by one character +T}@T{ +T} +T{ +\f[V]cmd.line.begin\f[R] +T}@T{ +Move cursor to the previous word by one character +T}@T{ +T} +T{ +\f[V]cmd.line.end\f[R] +T}@T{ +Move cursor to the previous word by one character +T}@T{ +T} +T{ +\f[V]cmd.line.escape\f[R] +T}@T{ +Ignore keybindings for next character +T}@T{ +T} +T{ +\f[V]cmd.line.prevHist\f[R] +T}@T{ +Jump to the previous history entry +T}@T{ +T} +T{ +\f[V]cmd.line.nextHist\f[R] +T}@T{ +Jump to the next history entry +T}@T{ +T} +.TE +.PP +Note: to facilitate URL editing, the line editor has a different +definition of what a word is than the pager. +For the line editor, a word is either a sequence of alphanumeric +characters, or any single non-alphanumeric character. +(This means that e.g.\ \f[V]https://\f[R] consists of four words: +\f[V]https\f[R], \f[V]:\f[R], \f[V]/\f[R] and \f[V]/\f[R].) +.IP +.nf +\f[C] +# Control+A moves the cursor to the beginning of the line. +\[aq]C-a\[aq] = \[aq]cmd.line.begin\[aq] + +# Escape+D deletes everything after the cursor until it reaches a word-breaking +# character. +\[aq]M-d\[aq] = \[aq]cmd.line.killWord\[aq] +\f[R] +.fi +.SS Appendix +.SS Regex handling +.PP +Regular expressions are currently handled using libregexp which is +included in QuickJS. +This means that all regular expressions work as in JavaScript. +.PP +There are two different modes of regex preprocessing in Chawan: +\[lq]search\[rq] mode, and \[lq]match\[rq] mode. +\[lq]match\[rq] mode is used for configurations (meaning in all values +in this document described as \[lq]regex\[rq]). +\[lq]search\[rq] mode is used for the on-page search function (using +searchForward/isearchForward etc.) +.SS Match mode +.PP +Regular expressions are assumed to be exact matches, except when they +start with a caret (\[ha]) sign or end with an unescaped dollar ($) +sign. +.PP +In other words, the following transformations occur: +.IP +.nf +\f[C] +\[ha]abcd -> \[ha]abcd (no change, only beginning is matched) +efgh$ -> efgh$ (no change, only end is matched) +\[ha]ijkl$ -> \[ha]ijkl$ (no change, the entire line is matched) +mnop -> \[ha]mnop$ (changed to exact match, the entire line is matched) +\f[R] +.fi +.PP +Match mode has no way to toggle JavaScript regex flags like \f[V]i\f[R]. +.SS Search mode +.PP +For on-page search, the above transformations do not apply; the search +\f[V]/abcd\f[R] searches for the string \f[V]abcd\f[R] inside all lines. +.PP +\[lq]Search\[rq] mode also has some other convenience transformations: +.IP \[bu] 2 +The string \f[V]c\f[R] (backslash + lower-case c) inside a search-mode +regex enables case-insensitive matching. +.IP \[bu] 2 +Conversely, \f[V]C\f[R] (backslash + capital C) disables +case-insensitive matching. +(Useful if you have the \[lq]i\[rq] flag inside default-flags.) +.IP \[bu] 2 +\f[V]<\f[R] and \f[V]>\f[R] is converted to \f[V]b\f[R] (as in vi, grep, +etc.) +.PP +Note that none of these work in \[lq]match\[rq] mode. +.SS Path handling +.PP +Rules for path handling are similar to how strings in the shell are +handled. +.IP \[bu] 2 +Tilde-expansion is used to determine the user\[cq]s home directory. +So e.g.\ \f[V]\[ti]/whatever\f[R] works. +.IP \[bu] 2 +Environment variables can be used like \f[V]$ENV_VAR\f[R]. +.IP \[bu] 2 +Relative paths are relative to the Chawan configuration directory. +.PP +Some non-external variables are also defined by Chawan. +These can be accessed using the syntax \f[V]${%VARIABLE}\f[R]: +.IP \[bu] 2 +\f[V]${%CHA_BIN_DIR}\f[R]: the directory which the \f[V]cha\f[R] binary +resides in. +Note that symbolic links are automatically resolved to determine this +path. +.IP \[bu] 2 +\f[V]${%CHA_LIBEXEC_DIR}\f[R]: the directory for all executables Chawan +uses for operation. +By default, this is \f[V]${%CHA_BIN_DIR}/../libexec/chawan\f[R]. +.SS Word types +.PP +Word-based pager commands can operate with different definitions of +words. +Currently, these are: +.IP \[bu] 2 +w3m words +.IP \[bu] 2 +vi words +.IP \[bu] 2 +Big words +.SS w3m word +.PP +A w3m word is a sequence of alphanumeric characters. +Symbols are treated in the same way as whitespace. +.SS vi word +.PP +A vi word is a sequence of alphanumeric characters, OR a sequence of +symbols. +.PP +vi words may be separated by whitespace; however, symbolic and +alphanumeric vi words do not have to be whitespace-separated. +e.g.\ following character sequence contains two words: +.IP +.nf +\f[C] +hello[]+{}\[at]\[ga]! +\f[R] +.fi +.SS Big word +.PP +A big word is a sequence of non-whitespace characters. +.PP +It is essentially the same as a w3m word, but with symbols being defined +as non-whitespace. +.SS See also +.PP +\f[B]cha\f[R](1) |