'\" t
.\" Automatically generated by Pandoc 3.7.0.1
.\"
.TH "CHA-CONFIG" "5"
.SH Configuration of Chawan
Chawan supports configuration of various options like keybindings, user
stylesheets, site preferences, etc.
The configuration format is similar to toml, with the following
exceptions:
.IP \(bu 2
Inline tables may span across multiple lines.
.IP \(bu 2
Regular tables (\f[CR][table]\f[R]) and inline tables
(\f[CR]table = {}\f[R]) have different semantics.
The first is additive, meaning old values are not removed.
The second is destructive, and clears all definitions in the table
specified.
.IP \(bu 2
\f[CR][[table\-array]]\f[R] is sugar for \f[CR][table\-array.n]\f[R],
where \f[CR]n\f[R] is the number of declared table arrays.
For example, you can declare anonymous siteconfs using the syntax
\f[CR][[siteconf]]\f[R].
.PP
The canonical configuration file path is \(ti/.chawan/config.toml, but
the search path accommodates XDG basedirs as well:
.IP "1." 3
config file specified through \-C switch \-> use that
.IP "2." 3
\f[CR]$CHA_DIR\f[R] is set \-> use \f[CR]$CHA_DIR/config.toml\f[R]
.IP "3." 3
\f[CR]${XDG_CONFIG_HOME:\-\(ti/.config}/chawan/config.toml\f[R] exists
\-> use that
.IP "4." 3
\f[CR]\(ti/.chawan/config.toml\f[R] exists \-> use that
.PP
See the path handling section for details on how the config directory
can be accessed.
.SS Start
Start\-up options are to be placed in the \f[CR][start]\f[R] section.
.PP
Following is a list of start\-up options:
.PP
.TS
tab(@);
lw(14.0n) lw(7.0n) lw(10.5n) lw(38.5n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
visual\-home
T}@T{
url
T}@T{
\(lqabout:chawan\(rq
T}@T{
Page opened when Chawan is called with the \-V option and no other pages
are passed as arguments.
T}
_
T{
startup\-script
T}@T{
JavaScript code
T}@T{
\(lq\(lq
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{
headless
T}@T{
boolean / \(lqdump\(rq
T}@T{
false
T}@T{
When set to true or \(lqdump\(rq, the browser does not take input;
instead, it prints a rendered version of all buffers in order, then
exits.
.PP
The difference between \f[CR]true\f[R] and \(lqdump\(rq is that
\f[CR]true\f[R] first waits for all scripts and network requests to run
to completion, while \(lqdump\(rq does not.
This means that \f[CR]true\f[R] may never exit when scripting is enabled
(e.g.\ if a script sets \f[CR]setInterval\f[R].)
.PP
Piping \f[CR]cha\f[R] to an external program or passing the
\f[CR]\-d\f[R] switch has the same effect as setting this option to
\(lqdump\(rq.
T}
_
T{
console\-buffer
T}@T{
boolean
T}@T{
true
T}@T{
Whether Chawan should open a console buffer in non\-headless mode.
.PP
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}
.TE
.SS Buffer
Buffer options are to be placed in the \f[CR][buffer]\f[R] section.
.PP
These options are global to all buffers.
For more granular filtering, use \f[CR][[siteconf]]\f[R].
.PP
Example:
.IP
.EX
\f[B][buffer]\f[R]
\f[I]# show images on all websites\f[R]
images = true
\f[I]# disable website CSS\f[R]
styling = false
\f[I]# Specify user styles.\f[R]
user\-style = \(aq\(aq\(aq
/* you can import external UA styles like this: */
\(atimport \(aquser.css\(aq;
/* or just insert the style inline as follows. */
/* enforce the default text\-decoration for links (i.e. underline). */
a[href] { text\-decoration: revert !important }
\(atmedia (monochrome) { /* only in color\-mode \(dqmonochrome\(dq (or \-M) */
	/* disable UA style of bold font (no need for important here) */
	a[href]:hover { font\-weight: initial }
	/* ...and italicize the font on hover instead.
	 * here we use important because we don\(aqt want websites to
	 * override the value. */
	a[href]:hover { font\-style: italic !important }
}
\(aq\(aq\(aq
\f[I]# You *can* set scripting to true here, but I strongly recommend using\f[R]
\f[I]# [[siteconf]] to enable it on a per\-site basis instead.\f[R]
.EE
.PP
Following is a list of buffer options:
.PP
.TS
tab(@);
lw(14.0n) lw(10.5n) lw(7.0n) lw(38.5n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
styling
T}@T{
boolean
T}@T{
true
T}@T{
Enable/disable author style sheets.
Note that disabling this does not affect user styles.
T}
_
T{
scripting
T}@T{
boolean / \(lqapp\(rq
T}@T{
false
T}@T{
Enable/disable JavaScript in \f[I]all\f[R] buffers.
.PP
\f[CR]\(dqapp\(dq\f[R] also enables JavaScript APIs that can be used to
fingerprint users (e.g.\ querying the window\(cqs size.)
This may achieve better compatibility with websites that behave like
applications, at the cost of reduced privacy.
.PP
For security reasons, users are encouraged to selectively enable
JavaScript with \f[CR][[siteconf]]\f[R] instead of using this setting.
T}
_
T{
images
T}@T{
boolean
T}@T{
false
T}@T{
Enable/disable inline image display.
T}
_
T{
cookie
T}@T{
boolean / \(lqsave\(rq
T}@T{
false
T}@T{
Enable/disable cookies on sites.
.PP
If the string \(lqsave\(rq is specified, then cookies are also saved to
\f[CR]external.cookie\-file\f[R].
\f[CR]true\f[R] still reads cookies.txt, but does not modify it.
.PP
In Chawan, each website gets a separate cookie jar, so websites relying
on cross\-site cookies may not work as expected.
You may use the \f[CR][[siteconf]]\f[R]
\f[CR]\(dqshare\-cookie\-jar\(dq\f[R] setting to adjust this behavior
for specific sites.
T}
_
T{
referer\-from
T}@T{
boolean
T}@T{
false
T}@T{
Enable/disable the \(lqReferer\(rq header.
.PP
Defaults to false.
For privacy reasons, users are encouraged to leave this option disabled,
only enabling it for specific sites in \f[CR][[siteconf]]\f[R].
T}
_
T{
autofocus
T}@T{
boolean
T}@T{
false
T}@T{
When set to true, elements with an \(lqautofocus\(rq attribute are
focused on automatically after the buffer is loaded.
.PP
If scripting is enabled, this also allows scripts to focus on elements.
T}
_
T{
meta\-refresh
T}@T{
\(lqnever\(rq / \(lqalways\(rq / \(lqask\(rq
T}@T{
\(lqask\(rq
T}@T{
Whether or not \f[CR]http\-equiv=refresh\f[R] meta tags should be
respected.
\(lqnever\(rq completely disables them, \(lqalways\(rq automatically
accepts all of them, \(lqask\(rq brings up a pop\-up menu.
T}
_
T{
history
T}@T{
boolean
T}@T{
true
T}@T{
Whether or not browsing history should be saved to the disk.
T}
_
T{
mark\-links
T}@T{
boolean
T}@T{
false
T}@T{
Add numeric markers before links.
In headless/dump mode, this also prints a list of URLs after the page.
T}
_
T{
user\-style
T}@T{
string
T}@T{
\(lq\(lq
T}@T{
A user stylesheet applied to all buffers.
.PP
External stylesheets can be imported using the
\f[CR]\(atimport \(aqfile.css\(aq;\f[R] syntax.
Paths are relative to the configuration directory.
.PP
Nested \(atimport is not supported yet.
T}
.TE
.SS Search
Search options are to be placed in the \f[CR][search]\f[R] section.
.PP
Following is a list of search options:
.PP
.TS
tab(@);
lw(14.0n) lw(10.5n) lw(7.0n) lw(38.5n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
wrap
T}@T{
boolean
T}@T{
true
T}@T{
Whether on\-page searches should wrap around the document.
T}
_
T{
ignore\-case
T}@T{
\(lqauto\(rq / boolean
T}@T{
\(lqauto\(rq
T}@T{
When set to true, document\-wide searches are case\-insensitive by
default.
When set to \(lqauto\(rq, searches are only case\-sensitive when the
search term includes a capital letter.
.PP
Note: this can also be overridden inline in the search bar (vim\-style),
with the escape sequences \f[CR]\(rsc\f[R] (ignore case) and
\f[CR]\(rsC\f[R] (strict case).
See search mode for details.)
T}
.TE
.SS Encoding
Encoding options are to be placed in the \f[CR][encoding]\f[R] section.
.PP
Following is a list of encoding options:
.PP
.TS
tab(@);
lw(14.0n) lw(10.5n) lw(10.5n) lw(35.0n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
document\-charset
T}@T{
array of charset label strings
T}@T{
[\(lqutf\-8\(rq, \(lqsjis\(rq, \(lqeuc\-jp\(rq, \(lqlatin2\(rq]
T}@T{
List of character sets for loading documents.
.PP
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{
display\-charset
T}@T{
string
T}@T{
\(lqauto\(rq
T}@T{
Character set for keyboard input and displaying documents.
.PP
Used in dump mode as well.
.PP
(This means that e.g.\ \f[CR]cha \-I EUC\-JP \-O UTF\-8 a > b\f[R] is
roughly equivalent to \f[CR]iconv \-f EUC\-JP \-t UTF\-8\f[R].)
T}
.TE
.SS External
External options are to be placed in the \f[CR][external]\f[R] section.
.PP
Following is a list of external options:
.PP
.TS
tab(@);
lw(17.5n) lw(7.0n) lw(14.0n) lw(31.5n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
tmpdir
T}@T{
path
T}@T{
{usually /tmp/cha\-tmp\-user}
T}@T{
Directory used to save temporary files.
T}
_
T{
editor
T}@T{
shell command
T}@T{
{usually \f[CR]$EDITOR\f[R]}
T}@T{
External editor command.
%s is substituted for the file name, %d for the line number.
T}
_
T{
mailcap
T}@T{
array of paths
T}@T{
{see mailcap docs}
T}@T{
Search path for mailcap files.
(See \f[B]cha\-mailcap\f[R](5) for details.)
Directories specified first have higher precedence.
T}
_
T{
mime\-types
T}@T{
array of paths
T}@T{
{see mime.types docs}
T}@T{
Search path for mime.types files.
(See \f[B]cha\-mime.types\f[R](5) for details.)
T}
_
T{
auto\-mailcap
T}@T{
path
T}@T{
\(lqauto.mailcap\(rq
T}@T{
Mailcap file for entries that are automatically executed.
.PP
The \(lqOpen as\(rq prompt also saves entries in this file.
T}
_
T{
cgi\-dir
T}@T{
array of paths
T}@T{
{see local CGI docs}
T}@T{
Search path for local CGI scripts.
(See \f[B]cha\-localcgi\f[R](5) for details.)
T}
_
T{
urimethodmap
T}@T{
array of paths
T}@T{
{see urimethodmap docs}
T}@T{
Search path for urimethodmap files.
(See \f[B]cha\-urimethodmap\f[R](5) for details.)
T}
_
T{
w3m\-cgi\-compat
T}@T{
boolean
T}@T{
false
T}@T{
Enable local CGI compatibility with w3m.
In short, it redirects \f[CR]file:///cgi\-bin/*\f[R] and
\f[CR]file:///$LIB/cgi\-bin/*\f[R] to \f[CR]cgi\-bin:*\f[R].
For further details, see \f[B]cha\-localcgi\f[R](5).
T}
_
T{
download\-dir
T}@T{
path
T}@T{
{same as tmpdir}
T}@T{
Path to pre\-fill for \(lqSave to:\(rq prompts.
T}
_
T{
show\-download\-panel
T}@T{
boolean
T}@T{
true
T}@T{
Whether the \f[CR]about:downloads\f[R] should be shown after starting a
download.
T}
_
T{
copy\-cmd
T}@T{
shell command
T}@T{
\(lqxsel \-bi\(rq
T}@T{
Command to use for \(lqcopy to clipboard\(rq operations.
T}
_
T{
paste\-cmd
T}@T{
shell command
T}@T{
\(lqxsel \-bo\(rq
T}@T{
Command to use for \(lqread from clipboard\(rq operations.
T}
_
T{
bookmark
T}@T{
path
T}@T{
\(lqbookmark.md\(rq
T}@T{
Path to the bookmark.md file.
(The file it points to should have a .md extension, so that its type can
be correctly deduced.)
T}
_
T{
history\-file
T}@T{
path
T}@T{
\(lqhistory.uri\(rq
T}@T{
Path to the history file.
T}
_
T{
history\-size
T}@T{
number
T}@T{
100
T}@T{
Maximum length of the history file.
T}
_
T{
cookie\-file
T}@T{
path
T}@T{
\(lqcookies.txt\(rq
T}@T{
Path to the cookie file.
.PP
The format is equivalent to curl\(cqs \(lqcookies.txt\(rq format, except
that a \(lqjar\(at\(rq part is prepended for cookies that belong in a
different jar than the domain.
.PP
Cookies from this file are used if \(lqbuffer.cookie\(rq (or its
equivalent siteconf override) is set to \f[CR]true\f[R] or
\f[CR]\(dqsave\(dq\f[R].
This means that \f[CR]true\f[R] sets the cookie\-file to a
\(lqread\-only\(rq mode.
T}
.TE
.SS Input
Input options are to be placed in the \f[CR][input]\f[R] section.
.PP
.TS
tab(@);
lw(14.0n) lw(7.0n) lw(7.0n) lw(42.0n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
vi\-numeric\-prefix
T}@T{
boolean
T}@T{
true
T}@T{
Whether vi\-style numeric prefixes to commands should be accepted.
.PP
Only applies for keybindings defined in \f[CR][page]\f[R].
T}
_
T{
use\-mouse
T}@T{
boolean
T}@T{
true
T}@T{
Whether Chawan is allowed to intercept mouse clicks.
.PP
The current implementation imitates w3m.
T}
_
T{
osc52\-copy
T}@T{
boolean / \(lqauto\(rq
T}@T{
auto
T}@T{
Whether Chawan should use the OSC 52 escape sequence for copying to the
clipboard directly through the terminal.
When available, OSC 52 overrides \f[CR]external.copy\-cmd\f[R].
.PP
When set to \(lqauto\(rq (the default), Chawan tries to detect whether
OSC 52 is available on launch.
T}
_
T{
bracketed\-paste
T}@T{
boolean
T}@T{
true
T}@T{
Whether Chawan should ask for bracketed paste.
.PP
When true, the terminal will (hopefully) mark pasted text with escape
sequences, which a) ensures that pasting a newline character into the
line editor does not submit the editor, b) allows Chawan to intercept
text pasted into the pager, automatically loading it into the
browser\(cqs URL bar.
T}
_
T{
wheel\-scroll
T}@T{
number
T}@T{
5
T}@T{
Number of lines to scroll for a mouse wheel event.
T}
_
T{
side\-wheel\-scroll
T}@T{
number
T}@T{
5
T}@T{
Number of columns to scroll for a mouse side\-wheel event.
T}
_
T{
link\-hint\-chars
T}@T{
string
T}@T{
abcdefghijklmnoprstuvxyz
T}@T{
A string of characters to use in \f[CR]toggleLinkHints\f[R].
Any Unicode codepoint is accepted, and they are ordered as specified in
this option.
T}
.TE
.PP
Examples:
.IP
.EX
[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 = \(aqn => n ? pager.gotoLine(n) : pager.cursorLastLine()\(aq
.EE
.SS Network
Network options are to be placed in the \f[CR][network]\f[R] section.
.PP
.TS
tab(@);
lw(17.5n) lw(8.4n) lw(9.1n) lw(35.0n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
max\-redirect
T}@T{
number
T}@T{
10
T}@T{
Maximum number of redirections to follow.
T}
_
T{
max\-net\-connections
T}@T{
number
T}@T{
12
T}@T{
Maximum number of simultaneous network connections allowed in one
buffer.
Further connections are held back until the number returns below the
threshold.
T}
_
T{
prepend\-scheme
T}@T{
string
T}@T{
\(lqhttps://\(rq
T}@T{
Prepend this to URLs passed to Chawan without a scheme.
.PP
Note that local files (\f[CR]file:\f[R] scheme) will always be checked
first; only if this fails, Chawan will retry the request with
\f[CR]prepend\-scheme\f[R] set as the scheme.
T}
_
T{
proxy
T}@T{
URL
T}@T{
unset
T}@T{
Specify a proxy for all network requests Chawan makes.
Currently, the formats \f[CR]http://user:pass\(atdomain\f[R] and
\f[CR]socks5://user:pass\(atdomain\f[R] are accepted.
(Unlike in curl, \f[CR]socks5h\f[R] is an alias of \f[CR]socks5\f[R],
and DNS requests are always tunneled.)
.PP
Can be overridden by siteconf.
T}
_
T{
default\-headers
T}@T{
table
T}@T{
{omitted}
T}@T{
Specify a list of default headers for all HTTP(S) network requests.
Can be overridden by siteconf.
T}
_
T{
allow\-http\-from\-file
T}@T{
boolean
T}@T{
false
T}@T{
\f[B]WARNING: think twice before enabling this.\f[R]
.PP
Allows HTTP and HTTPS requests from the \f[CR]file:\f[R] and
\f[CR]stream:\f[R] schemes.
This is a very bad idea in general, because it allows local files to
ping remote servers (a functionality commonly abused by HTML e\-mails to
track your mailbox activity.)
.PP
On the other hand, it allows loading images in HTML e\-mails if you
don\(cqt care about the privacy implications.
T}
.TE
.SS Display
Display options are to be placed in the \f[CR][display]\f[R] section.
.PP
Following is a list of display options:
.PP
.TS
tab(@);
lw(23.1n) lw(11.9n) lw(7.0n) lw(28.0n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
color\-mode
T}@T{
\(lqmonochrome\(rq / \(lqansi\(rq / \(lqeight\-bit\(rq /
\(lqtrue\-color\(rq / \(lqauto\(rq
T}@T{
\(lqauto\(rq
T}@T{
Set the color mode.
\(lqauto\(rq for automatic detection, \(lqmonochrome\(rq for black on
white, \(lqansi\(rq for ansi colors, \(lqeight\-bit\(rq for 256\-color
mode, and \(lqtrue\-color\(rq for true colors.
T}
_
T{
format\-mode
T}@T{
\(lqauto\(rq / [\(lqbold\(rq, \(lqitalic\(rq, \(lqunderline\(rq,
\(lqreverse\(rq, \(lqstrike\(rq, \(lqoverline\(rq, \(lqblink\(rq]
T}@T{
\(lqauto\(rq
T}@T{
Specifies output formatting modes.
Accepts the string \(lqauto\(rq or an array of specific attributes.
An empty array (\f[CR][]\f[R]) disables formatting completely.
T}
_
T{
no\-format\-mode
T}@T{
[\(lqbold\(rq, \(lqitalic\(rq, \(lqunderline\(rq, \(lqreverse\(rq,
\(lqstrike\(rq, \(lqoverline\(rq, \(lqblink\(rq]
T}@T{
\(lqoverline\(rq
T}@T{
Disable specific formatting modes.
T}
_
T{
image\-mode
T}@T{
\(lqauto\(rq / \(lqnone\(rq / \(lqsixel\(rq / \(lqkitty\(rq
T}@T{
\(lqauto\(rq
T}@T{
Specifies the image output mode.
\(lqsixel\(rq uses sixels for output, \(lqkitty\(rq uses the Kitty image
display protocol, \(lqnone\(rq disables image display completely.
.PP
\(lqauto\(rq tries to detect sixel or kitty support, and falls back to
\(lqnone\(rq when neither are available.
This is the default setting, but you must also enable
\f[CR]buffer.images\f[R] for images to work.
T}
_
T{
sixel\-colors
T}@T{
\(lqauto\(rq / 2..65535
T}@T{
\(lqauto\(rq
T}@T{
Only applies when \f[CR]display.image\-mode=\(dqsixel\(dq\f[R].
Setting a number overrides the number of sixel color registers reported
by the terminal.
T}
_
T{
alt\-screen
T}@T{
\(lqauto\(rq / boolean
T}@T{
\(lqauto\(rq
T}@T{
Enable/disable the alternative screen.
T}
_
T{
highlight\-color
T}@T{
color
T}@T{
\(lqcyan\(rq
T}@T{
Set the highlight color for incremental search and marks.
Both hex values and CSS color names are accepted.
.PP
In monochrome mode, this setting is ignored; instead, reverse video is
used.
T}
_
T{
highlight\-marks
T}@T{
boolean
T}@T{
true
T}@T{
Enable/disable highlighting of marks.
T}
_
T{
double\-width\-ambiguous
T}@T{
boolean
T}@T{
false
T}@T{
Assume the terminal displays characters in the East Asian Ambiguous
category as double\-width characters.
Useful when e.g.\ ○ occupies two cells.
T}
_
T{
minimum\-contrast
T}@T{
number
T}@T{
100
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{
force\-clear
T}@T{
boolean
T}@T{
false
T}@T{
Force the screen to be completely cleared every time it is redrawn.
T}
_
T{
set\-title
T}@T{
boolean
T}@T{
true
T}@T{
Set the terminal emulator\(cqs window title to that of the current page.
T}
_
T{
default\-background\-color
T}@T{
\(lqauto\(rq / color
T}@T{
\(lqauto\(rq
T}@T{
Overrides the assumed background color of the terminal.
\(lqauto\(rq leaves background color detection to Chawan.
T}
_
T{
default\-foreground\-color
T}@T{
\(lqauto\(rq / color
T}@T{
\(lqauto\(rq
T}@T{
Sets the assumed foreground color of the terminal.
\(lqauto\(rq leaves foreground color detection to Chawan.
T}
_
T{
query\-da1
T}@T{
bool
T}@T{
true
T}@T{
Enable/disable querying Primary Device Attributes, and with it, all
\(lqdynamic\(rq terminal querying.
.PP
Do not alter this value unless Chawan told you so; the output will look
awful.
T}
_
T{
columns, lines, pixels\-per\-column, pixels\-per\-line
T}@T{
number
T}@T{
80, 24, 9, 18
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{
force\-columns, force\-lines, force\-pixels\-per\-column,
force\-pixels\-per\-line
T}@T{
boolean
T}@T{
false
T}@T{
Force\-set columns, lines, pixels per column, or pixels per line to the
fallback values provided above.
T}
.TE
.SS Status
Options concerning the status bar (last line on the screen) are to be
placed in the \f[CR][status]\f[R] section.
.PP
Following is a list of status options:
.PP
.TS
tab(@);
lw(23.1n) lw(11.9n) lw(7.0n) lw(28.0n).
T{
Name
T}@T{
Value
T}@T{
Default
T}@T{
Function
T}
_
T{
show\-cursor\-position
T}@T{
boolean
T}@T{
true
T}@T{
Whether or not the current line number should be displayed.
T}
_
T{
show\-hover\-link
T}@T{
boolean
T}@T{
true
T}@T{
Whether or not the link under the cursor should be displayed.
T}
.TE
.SS Omnirule
The omni\-bar (by default opened with C\-l) can be used to perform
searches using omni\-rules.
These are to be specified as sub\-keys to table \f[CR][omnirule]\f[R].
(The sub\-key itself is ignored; you can use anything as long it
doesn\(cqt conflict with other keys.)
.PP
Examples:
.IP
.EX
# Search using DuckDuckGo Lite.
# (This rule is included in the default config, although C\-k invokes
# Brave search.)
[omnirule.ddg]
match = \(aq\(haddg:\(aq
substitute\-url = \(aq(x) => \(dqhttps://lite.duckduckgo.com/lite/?kp=\-1&kd=\-1&q=\(dq + encodeURIComponent(x.split(\(dq:\(dq).slice(1).join(\(dq:\(dq))\(aq

# To use the above rule, open the URL bar with C\-k, clear it with
# C\-u, and type ddg:keyword.
# Alternatively, you can also redefine C\-k like:
[page]
\(aqC\-k\(aq = \(aq() => pager.load(\(dqddg:\(dq)\(aq

# Search using Wikipedia, Firefox\-style.
# The [[omnirule]] syntax introduces an anonymous omnirule; it is
# equivalent to the named one.
[[omnirule]]
match = \(aq\(ha\(atwikipedia\(aq
substitute\-url = \(aq(x) => \(dqhttps://en.wikipedia.org/wiki/Special:Search?search=\(dq + encodeURIComponent(x.replace(/\(atwikipedia/, \(dq\(dq))\(aq
.EE
.PP
As noted above, the default config includes some built\-in rules,
selected according to the maintainer\(cqs preference and the minimum
criterion that they must work without cookies and JavaScript.
Currently, these are:
.IP \(bu 2
\f[CR]ddg:\f[R] \- DuckDuckGo Lite.
.IP \(bu 2
\f[CR]br:\f[R] \- Brave Search.
.IP \(bu 2
\f[CR]wk:\f[R] \- English Wikipedia.
.IP \(bu 2
\f[CR]wd:\f[R] \- English Wikitionary.
.IP \(bu 2
\f[CR]mo:\f[R] \- Mojeek.
.PP
Omnirule options:
.PP
.TS
tab(@);
lw(17.5n) lw(17.5n) lw(35.0n).
T{
Name
T}@T{
Value
T}@T{
Function
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.
.PP
Note: regexes are handled according to the match mode regex handling
rules.
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}
.TE
.SS Siteconf
Configuration options can be specified for individual sites.
Entries are to be specified as sub\-keys to table \f[CR][siteconf]\f[R].
(The sub\-key itself is ignored; you can use anything as long it
doesn\(cqt conflict with other keys.)
.PP
Most siteconf options can also be specified globally; see the
\(lqoverrides\(rq field.
.PP
Examples:
.IP
.EX
# Enable cookies on the orange website for log\-in.
[siteconf.hn]
url = \(aqhttps://news\(rs.ycombinator\(rs.com/.*\(aq
cookie = true

# Redirect npr.org to text.npr.org.
[siteconf.npr]
host = \(aq(www\(rs.)?npr\(rs.org\(aq
rewrite\-url = \(aq\(aq\(aq
(x) => {
	x.host = \(dqtext.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.sr\-ht]
host = \(aq(.*\(rs.)?sr\(rs.ht\(aq # either \(aqsomething.sr.ht\(aq or \(aqsr.ht\(aq
cookie = true # enable cookies (read\-only; use \(dqsave\(dq to persist them)
share\-cookie\-jar = \(aqsr.ht\(aq # use the cookie jar of \(aqsr.ht\(aq for all matched hosts

# Use the \(dqvector\(dq skin on Wikipedia.
# The [[siteconf]] syntax introduces an anonymous siteconf; it is
# equivalent to the above ones.
[[siteconf]]
url = \(aq\(hahttps?://[a\-z]+\(rs.wikipedia\(rs.org/wiki/(?!.*useskin=.*)\(aq
rewrite\-url = \(aqx => x.searchParams.append(\(dquseskin\(dq, \(dqvector\(dq)\(aq

# Make imgur send us images.
[siteconf.imgur]
host = \(aq(i\(rs.)?imgur\(rs.com\(aq
default\-headers = {
	User\-Agent = \(dqMozilla/5.0 chawan\(dq,
	Accept = \(dq*/*\(dq,
	Accept\-Encoding = \(dqgzip, deflate\(dq,
	Accept\-Language = \(dqen;q=1.0\(dq,
	Pragma = \(dqno\-cache\(dq,
	Cache\-Control = \(dqno\-cache\(dq
}
.EE
.PP
Siteconf options:
.PP
.TS
tab(@);
lw(17.5n) lw(10.5n) lw(19.6n) lw(22.4n).
T{
Name
T}@T{
Value
T}@T{
Overrides
T}@T{
Function
T}
_
T{
url
T}@T{
regex
T}@T{
n/a
T}@T{
Regular expression used to match the URL.
Either this or the \f[CR]host\f[R] option must be specified.
.PP
Note: regexes are handled according to the match mode regex handling
rules.
T}
_
T{
host
T}@T{
regex
T}@T{
n/a
T}@T{
Regular expression used to match the host part of the URL (i.e.\ domain
name/ip address.)
Either this or the \f[CR]url\f[R] option must be specified.
.PP
Note: regexes are handled according to the match mode regex handling
rules.
T}
_
T{
rewrite\-url
T}@T{
JavaScript function
T}@T{
n/a
T}@T{
A JavaScript function Chawan will pass the site\(cqs URL object to.
If a new URL is returned, or the URL object is modified in any way,
Chawan will transparently redirect the user to this new URL.
T}
_
T{
cookie
T}@T{
boolean / \(lqsave\(rq
T}@T{
\f[CR]buffer.cookie\f[R]
T}@T{
Whether loading (with \(lqsave\(rq, also saving) cookies should be
allowed for this URL.
T}
_
T{
share\-cookie\-jar
T}@T{
host
T}@T{
n/a
T}@T{
Cookie jar to use for this domain.
Useful for e.g.\ sharing cookies with subdomains.
T}
_
T{
referer\-from
T}@T{
boolean
T}@T{
\f[CR]buffer.referer\-from\f[R]
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 \(lqa.com\(rq as the Referer
header.
T}
_
T{
scripting
T}@T{
boolean / \(lqapp\(rq
T}@T{
\f[CR]buffer.scripting\f[R]
T}@T{
Enable/disable JavaScript execution on this site.
See \f[CR]buffer.scripting\f[R] for details.
T}
_
T{
styling
T}@T{
boolean
T}@T{
\f[CR]buffer.styling\f[R]
T}@T{
Enable/disable author styles (CSS) on this site.
T}
_
T{
images
T}@T{
boolean
T}@T{
\f[CR]buffer.images\f[R]
T}@T{
Enable/disable image display on this site.
T}
_
T{
document\-charset
T}@T{
charset label string
T}@T{
\f[CR]encoding.document\-charset\f[R]
T}@T{
Specify the default encoding for this site.
T}
_
T{
proxy
T}@T{
URL
T}@T{
\f[CR]network.proxy\f[R]
T}@T{
Specify a proxy for network requests fetching contents of this buffer.
T}
_
T{
default\-headers
T}@T{
table
T}@T{
\f[CR]network.default\-headers\f[R]
T}@T{
Specify a list of default headers for HTTP(S) network requests to this
buffer.
T}
_
T{
insecure\-ssl\-no\-verify
T}@T{
boolean
T}@T{
n/a
T}@T{
Defaults to false.
When set to true, this disables peer and hostname verification for SSL
keys on this site, like \f[CR]curl \-\-insecure\f[R] would.
.PP
Please do not use this unless you are absolutely sure you know what you
are doing.
T}
_
T{
autofocus
T}@T{
boolean
T}@T{
\f[CR]buffer.autofocus\f[R]
T}@T{
When set to true, elements with an \(lqautofocus\(rq attribute are
focused on automatically after the buffer is loaded.
.PP
If scripting is enabled, this also allows scripts to focus on elements.
T}
_
T{
meta\-refresh
T}@T{
\(lqnever\(rq / \(lqalways\(rq / \(lqask\(rq
T}@T{
\f[CR]buffer.meta\-refresh\f[R]
T}@T{
Whether or not \f[CR]http\-equiv=refresh\f[R] meta tags should be
respected.
\(lqnever\(rq completely disables them, \(lqalways\(rq automatically
accepts all of them, \(lqask\(rq brings up a pop\-up menu.
T}
_
T{
history
T}@T{
boolean
T}@T{
\f[CR]buffer.history\f[R]
T}@T{
Whether or not browsing history should be saved to the disk for this
URL.
T}
_
T{
mark\-links
T}@T{
boolean
T}@T{
\f[CR]buffer.mark\-links\f[R]
T}@T{
Add numeric markers before links.
T}
_
T{
user\-style
T}@T{
string
T}@T{
\f[CR]buffer.user\-style\f[R]
T}@T{
Specify a user style sheet specific to the site.
.PP
Please refer to \f[CR]buffer.user\-style\f[R] for details.
T}
.TE
.SS Keybindings
Keybindings are to be placed in these sections:
.IP \(bu 2
for pager interaction: \f[CR][page]\f[R]
.IP \(bu 2
for line editing: \f[CR][line]\f[R]
.PP
Keybindings are configured using the syntax
.IP
.EX
\(aq<keybinding>\(aq = \(aq<action>\(aq
.EE
.PP
Where \f[CR]<keybinding>\f[R] is a combination of unicode characters
with or without modifiers.
Modifiers are the prefixes \f[CR]C\-\f[R] and \f[CR]M\-\f[R], which add
control or escape to the keybinding respectively (essentially making
\f[CR]M\-\f[R] the same as \f[CR]C\-[\f[R]).
Modifiers can be escaped with the \f[CR]\(rs\f[R] sign.
.PP
\f[CR]<action>\f[R] is either a command defined in the \f[CR][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](7).
.PP
Examples:
.IP
.EX
\f[I]# show change URL when Control, Escape and j are pressed\f[R]
\(aqC\-M\-j\(aq = \(aqload\(aq

\f[I]# go to the first line of the page when g is pressed twice without a preceding\f[R]
\f[I]# number, or to the line when a preceding number is given.\f[R]
\(aqgg\(aq = \(aqgotoLineOrStart\(aq

\f[I]# JS functions and expressions are accepted too. Following replaces the\f[R]
\f[I]# default search engine with DuckDuckGo Lite.\f[R]
\f[I]# (See api.md for a list of available functions, and a discussion on how\f[R]
\f[I]# to add your own \(dqnamespaced\(dq commands like above.)\f[R]
\(aqC\-k\(aq = \(aq() => pager.load(\(dqddg:\(dq)\(aq
.EE
.SS Pager actions
.PP
.TS
tab(@);
lw(14.0n) lw(21.0n) lw(35.0n).
T{
Default key
T}@T{
Name
T}@T{
Function
T}
_
T{
q
T}@T{
\f[CR]quit\f[R]
T}@T{
Exit the browser.
T}
_
T{
C\-z
T}@T{
\f[CR]suspend\f[R]
T}@T{
Temporarily suspend the browser
.PP
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{
C\-l
T}@T{
\f[CR]load\f[R]
T}@T{
Open the current address in the URL bar.
T}
_
T{
M\-l
T}@T{
\f[CR]loadCursor\f[R]
T}@T{
Open the address of the link or image being hovered in the URL bar.
.PP
If no link/image is under the cursor, an empty URL bar is opened.
T}
_
T{
None
T}@T{
\f[CR]loadEmpty\f[R]
T}@T{
Open an empty address bar.
T}
_
T{
C\-k
T}@T{
\f[CR]webSearch\f[R]
T}@T{
Open the URL bar with an arbitrary search engine.
At the moment, this is Brave Search, but this may change in the future.
T}
_
T{
M\-u
T}@T{
\f[CR]dupeBuffer\f[R]
T}@T{
Duplicate the current buffer by forking its content process.
T}
_
T{
U
T}@T{
\f[CR]reloadBuffer\f[R]
T}@T{
Open a new buffer with the current buffer\(cqs URL, replacing the
current buffer.
T}
_
T{
C\-g
T}@T{
\f[CR]lineInfo\f[R]
T}@T{
Display information about the current line on the status line.
T}
_
T{
\(rs
T}@T{
\f[CR]toggleSource\f[R]
T}@T{
If viewing an HTML buffer, open a new buffer with its source.
Otherwise, open the current buffer\(cqs contents as HTML.
T}
_
T{
D
T}@T{
\f[CR]discardBuffer\f[R]
T}@T{
Discard the current buffer, and move back to the previous/next buffer
depending on what the previously viewed buffer was.
T}
_
T{
d,, d.
T}@T{
\f[CR]discardBufferPrev\f[R], \f[CR]discardBufferNext\f[R]
T}@T{
Discard the current buffer, and move back to the previous/next buffer,
or open the link under the cursor.
T}
_
T{
M\-d
T}@T{
\f[CR]discardTree\f[R]
T}@T{
Discard all child buffers of the current buffer.
T}
_
T{
\&., ,, M\-,, M\-., M\-/
T}@T{
\f[CR]nextBuffer\f[R], \f[CR]prevBuffer\f[R],
\f[CR]prevSiblingBuffer\f[R], \f[CR]nextSiblingBuffer\f[R],
\f[CR]parentBuffer\f[R]
T}@T{
Traverse the buffer list.
.PP
\f[CR]nextBuffer\f[R] and \f[CR]prevBuffer\f[R] switch to the next or
previous buffer respectively.
.PP
\f[CR]prevSiblingBuffer\f[R] and \f[CR]parentBuffer\f[R] are deprecated
aliases for \f[CR]prevBuffer\f[R], while \f[CR]nextSiblingBuffer\f[R] is
a deprecated alias for \f[CR]nextBuffer\f[R].
T}
_
T{
M\-c
T}@T{
\f[CR]enterCommand\f[R]
T}@T{
Directly enter a JavaScript command.
Note that this interacts with the pager, not the website being
displayed.
T}
_
T{
None
T}@T{
\f[CR]searchForward\f[R], \f[CR]searchBackward\f[R]
T}@T{
Search for a string in the current buffer, forwards or backwards.
T}
_
T{
/, ?
T}@T{
\f[CR]isearchForward\f[R], \f[CR]searchBackward\f[R]
T}@T{
Incremental\-search for a string, highlighting the first result,
forwards or backwards.
T}
_
T{
n, N
T}@T{
\f[CR]searchNext\f[R], \f[CR]searchPrev\f[R]
T}@T{
Jump to the nth (or if unspecified, first) next/previous search result.
T}
_
T{
None
T}@T{
\f[CR]peek\f[R]
T}@T{
Display a message of the current buffer\(cqs URL on the status line.
T}
_
T{
u
T}@T{
\f[CR]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{
su
T}@T{
\f[CR]showFullAlert\f[R]
T}@T{
Show the last alert inside the line editor.
You can also view previous ones using C\-p or C\-n.
T}
_
T{
M\-y
T}@T{
\f[CR]copyURL\f[R]
T}@T{
Copy the current buffer\(cqs URL to the system clipboard.
T}
_
T{
yu
T}@T{
\f[CR]copyCursorLink\f[R]
T}@T{
Copy the link under the cursor to the system clipboard.
T}
_
T{
yI
T}@T{
\f[CR]copyCursorImage\f[R]
T}@T{
Copy the URL of the image under the cursor to the system clipboard.
T}
_
T{
M\-p
T}@T{
\f[CR]gotoClipboardURL\f[R]
T}@T{
Go to the URL currently on the clipboard.
T}
_
T{
M\-b
T}@T{
\f[CR]openBookmarks\f[R]
T}@T{
Open the bookmark file.
T}
_
T{
M\-a
T}@T{
\f[CR]addBookmark\f[R]
T}@T{
Add the current page to your bookmarks.
T}
_
T{
f
T}@T{
\f[CR]toggleLinkHints\f[R]
T}@T{
Show hints before each link (or button).
After typing a hint, the cursor is placed on the respective link.
.PP
The hint character set may be customized with
\f[CR]input.link\-hint\-chars\f[R].
T}
.TE
.SS Buffer actions
Note: \f[CR]n\f[R] in the following text refers to a number preceding
the action.
e.g.
in \f[CR]10gg\f[R], n = 10.
If no preceding number is input, then it is left unspecified.
.PP
.TS
tab(@);
lw(14.0n) lw(24.5n) lw(31.5n).
T{
Default key
T}@T{
Name
T}@T{
Function
T}
_
T{
j/C\-p/Up arrow, k/C\-n/Down arrow
T}@T{
\f[CR]cursorUp\f[R], \f[CR]cursorDown\f[R]
T}@T{
Move the cursor upwards/downwards by n lines, or if n is unspecified, by
1.
T}
_
T{
h/Left arrow, l/Right arrow
T}@T{
\f[CR]cursorLeft\f[R], \f[CR]cursorRight\f[R]
T}@T{
Move the cursor to the left/right by n cells, or if n is unspecified, by
1.
T}
_
T{
0/Home
T}@T{
\f[CR]cursorLineBegin\f[R]
T}@T{
Move the cursor to the first cell of the line.
T}
_
T{
\(ha
T}@T{
\f[CR]cursorLineTextStart\f[R]
T}@T{
Move the cursor to the first non\-blank character of the line.
T}
_
T{
$/End
T}@T{
\f[CR]cursorLineEnd\f[R]
T}@T{
Move the cursor to the last cell of the line.
T}
_
T{
w, W
T}@T{
\f[CR]cursorNextWord\f[R], \f[CR]cursorNextViWord\f[R],
\f[CR]cursorNextBigWord\f[R]
T}@T{
Move the cursor to the beginning of the next word.
T}
_
T{
None
T}@T{
\f[CR]cursorPrevWord\f[R], \f[CR]cursorPrevViWord\f[R],
\f[CR]cursorPrevBigWord\f[R]
T}@T{
Move the cursor to the end of the previous word.
T}
_
T{
e, E
T}@T{
\f[CR]cursorWordEnd\f[R], \f[CR]cursorViWordEnd\f[R],
\f[CR]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{
b, B
T}@T{
\f[CR]cursorWordBegin\f[R], \f[CR]cursorViWordBegin\f[R],
\f[CR]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[CR]cursorPrevLink\f[R], \f[CR]cursorNextLink\f[R]
T}@T{
Move the cursor to the end/beginning of the previous/next clickable
element (e.g.\ link, input field, etc).
T}
_
T{
{, }
T}@T{
\f[CR]cursorPrevParagraph\f[R], \f[CR]cursorNextParagraph\f[R]
T}@T{
Move the cursor to the end/beginning of the nth previous/next paragraph.
T}
_
T{
None
T}@T{
\f[CR]cursorRevNthLink\f[R]
T}@T{
Move the cursor to the nth link of the document, counting backwards from
the document\(cqs last line.
T}
_
T{
None
T}@T{
\f[CR]cursorNthLink\f[R]
T}@T{
Move the cursor to the nth link of the document.
T}
_
T{
C\-b, C\-f, zH, zL
T}@T{
\f[CR]pageUp\f[R], \f[CR]pageDown\f[R], \f[CR]pageLeft\f[R],
\f[CR]pageRight\f[R]
T}@T{
Scroll up/down/left/right by n pages, or if n is unspecified, by one
page.
T}
_
T{
C\-u, C\-d
T}@T{
\f[CR]halfPageUp\f[R], \f[CR]halfPageDown\f[R], \f[CR]halfPageLeft\f[R],
\f[CR]halfPageUp\f[R]
T}@T{
Scroll up/down/left/right by n half pages, or if n is unspecified, by
one page.
T}
_
T{
K/C\-y, J/C\-e, zh, zl
T}@T{
\f[CR]scrollUp\f[R], \f[CR]scrollDown\f[R], \f[CR]scrollLeft\f[R],
\f[CR]scrollRight\f[R]
T}@T{
Scroll up/down/left/right by n lines, or if n is unspecified, by one
line.
T}
_
T{
Enter/Return
T}@T{
\f[CR]click\f[R]
T}@T{
Click the HTML element currently under the cursor.
n specifies the number of clicks in JS events.
T}
_
T{
c
T}@T{
\f[CR]rightClick\f[R]
T}@T{
Send a right click to the buffer.
If it doesn\(cqt catch the event (i.e.\ no JS context menu is shown),
toggle the menu instead.
T}
_
T{
C
T}@T{
\f[CR]toggleMenu\f[R]
T}@T{
Toggle the menu.
T}
_
T{
I
T}@T{
\f[CR]viewImage\f[R]
T}@T{
View the image currently under the cursor in an external viewer.
T}
_
T{
R
T}@T{
\f[CR]reshape\f[R]
T}@T{
Reshape the current buffer (=render the current page anew.)
Useful if the layout is not updating even though it should have.
T}
_
T{
r
T}@T{
\f[CR]redraw\f[R]
T}@T{
Redraw screen contents.
Useful if something messed up the display.
T}
_
T{
None (see gotoLineOrStart/End instead)
T}@T{
\f[CR]cursorFirstLine\f[R], \f[CR]cursorLastLine\f[R]
T}@T{
Move to the beginning/end in the buffer.
T}
_
T{
H, M, L
T}@T{
\f[CR]cursorTop\f[R], \f[CR]cursorMiddle\f[R], \f[CR]cursorBottom\f[R]
T}@T{
Move to the first line/line in the middle of/last line on the screen.
(Equivalent to \f[CR]H\f[R], \f[CR]M\f[R], \f[CR]L\f[R] in vi.)
T}
_
T{
zt, z Return, zz, z., zb, z\-
T}@T{
\f[CR]raisePage\f[R], \f[CR]raisePageBegin\f[R], \f[CR]centerLine\f[R],
\f[CR]centerLineBegin\f[R], \f[CR]lowerPage\f[R],
\f[CR]lowerPageBegin\f[R]
T}@T{
.PP
If n is specified, move cursor to line n.\ Then,
.IP \(bu 2
\f[CR]raisePage\f[R] scrolls down so that the cursor is on the top line
of the screen.
(vi \f[CR]z<CR>\f[R], vim \f[CR]zt\f[R].)
.IP \(bu 2
\f[CR]centerLine\f[R] shifts the screen so that the cursor is in the
middle of the screen.
(vi \f[CR]z.\f[R], vim \f[CR]zz\f[R].)
.IP \(bu 2
\f[CR]lowerPage\f[R] scrolls up so that the cursor is on the bottom line
of the screen.
(vi \f[CR]z\-\f[R], vim \f[CR]zb\f[R].)
The \-\f[CR]Begin\f[R] variants also move the cursor to the line\(cqs
first non\-blank character, as the variants originating from vi do.
T}
_
T{
z+
T}@T{
\f[CR]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 next screen\(cqs first line and raise the page.
T}
_
T{
z\(ha
T}@T{
\f[CR]previousPageBegin\f[R]
T}@T{
If n is specified, move to the screen before the nth line and lower the
page.
Otherwise, go to the previous screen\(cqs last line and lower the page.
T}
_
T{
g0, gc, g$
T}@T{
\f[CR]cursorLeftEdge\f[R], \f[CR]cursorMiddleColumn\f[R],
\f[CR]cursorRightEdge\f[R]
T}@T{
Move to the first/middle/last column on the screen.
T}
_
T{
None
T}@T{
\f[CR]centerColumn\f[R]
T}@T{
Center screen around the current column.
(w3m \f[CR]Z\f[R].)
T}
_
T{
gg, G
T}@T{
\f[CR]gotoLineOrStart\f[R], \f[CR]gotoLineOrEnd\f[R]
T}@T{
If n is specified, jump to line n.\ Otherwise, jump to the start/end of
the page.
T}
_
T{
|, None
T}@T{
\f[CR]gotoColumnOrBegin\f[R], \f[CR]gotoColumnOrEnd\f[R]
T}@T{
If n is specified, jump to column n of the current line.
Otherwise, jump to the first/last column.
T}
_
T{
m
T}@T{
\f[CR]mark\f[R]
T}@T{
Wait for a character \f[CR]x\f[R] and then set a mark with the ID
\f[CR]x\f[R].
T}
_
T{
\(ga, \(cq
T}@T{
\f[CR]gotoMark\f[R], \f[CR]gotoMarkY\f[R]
T}@T{
Wait for a character \f[CR]x\f[R] and then jump to the mark with the ID
\f[CR]x\f[R] (if it exists on the page).
.PP
\f[CR]gotoMark\f[R] sets both the X and Y positions; gotoMarkY only sets
the Y position.
T}
_
T{
:
T}@T{
\f[CR]markURL\f[R]
T}@T{
Convert URL\-like strings to anchors on the current page.
T}
_
T{
s Return
T}@T{
\f[CR]saveLink\f[R]
T}@T{
Save resource from the URL pointed to by the cursor to the disk.
T}
_
T{
sS
T}@T{
\f[CR]saveSource\f[R]
T}@T{
Save the source of the current buffer to the disk.
T}
_
T{
sI
T}@T{
\f[CR]saveImage\f[R]
T}@T{
Save the image currently under the cursor.
T}
_
T{
M\-i
T}@T{
\f[CR]toggleImages\f[R]
T}@T{
Toggle display of images in the current buffer.
T}
_
T{
M\-j
T}@T{
\f[CR]toggleScripting\f[R]
T}@T{
Reload the current buffer with scripting enabled/disabled.
T}
_
T{
M\-k
T}@T{
\f[CR]toggleCookie\f[R]
T}@T{
Reload the current buffer with cookies enabled/disabled.
T}
.TE
.SS Line\-editing actions
.PP
.TS
tab(@);
lw(14.0n) lw(21.0n) lw(35.0n).
T{
Default key
T}@T{
Name
T}@T{
Function
T}
_
T{
Return
T}@T{
\f[CR]line.submit\f[R]
T}@T{
Submit the line.
T}
_
T{
C\-c
T}@T{
\f[CR]line.cancel\f[R]
T}@T{
Cancel the current operation.
T}
_
T{
C\-h, C\-d
T}@T{
\f[CR]line.backspace\f[R], \f[CR]line.delete\f[R]
T}@T{
Delete character before (backspace)/after (delete) the cursor.
T}
_
T{
C\-u/C\-xC\-?, C\-k
T}@T{
\f[CR]line.clear\f[R], \f[CR]line.kill\f[R]
T}@T{
Delete text before (clear)/after (kill) the cursor.
T}
_
T{
C\-xC\-e
T}@T{
\f[CR]line.openEditor\f[R]
T}@T{
Open the line editor\(cqs contents in \f[CR]$EDITOR\f[R].
T}
_
T{
C\-w, M\-d
T}@T{
\f[CR]line.clearWord\f[R], \f[CR]line.killWord\f[R]
T}@T{
Delete word before (clear)/after (kill) the cursor.
T}
_
T{
C\-b, C\-f
T}@T{
\f[CR]line.backward\f[R], \f[CR]line.forward\f[R]
T}@T{
Move cursor backward/forward by one character.
T}
_
T{
M\-b, M\-f
T}@T{
\f[CR]line.prevWord\f[R], \f[CR]line.nextWord\f[R]
T}@T{
Move cursor to the previous/next word by one character
T}
_
T{
C\-a/Home, C\-e/End
T}@T{
\f[CR]line.begin\f[R], \f[CR]line.end\f[R]
T}@T{
Move cursor to the beginning/end of the line.
T}
_
T{
C\-v
T}@T{
\f[CR]line.escape\f[R]
T}@T{
Ignore keybindings for next character.
T}
_
T{
C\-p, C\-n
T}@T{
\f[CR]line.prevHist\f[R], \f[CR]line.nextHist\f[R]
T}@T{
Jump to the previous/next history entry
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[CR]https://\f[R] consists of four words:
\f[CR]https\f[R], \f[CR]:\f[R], \f[CR]/\f[R] and \f[CR]/\f[R].)
.IP
.EX
# Control+A moves the cursor to the beginning of the line.
\(aqC\-a\(aq = \(aqline.begin\(aq

# Escape+D deletes everything after the cursor until it reaches a word\-breaking
# character.
\(aqM\-d\(aq = \(aqline.killWord\(aq
.EE
.SS Appendix
.SS Regex handling
Regular expressions are currently handled using the libregexp library
from QuickJS.
This means that all regular expressions work as in JavaScript.
.PP
There are two different modes of regex preprocessing in Chawan:
\(lqsearch\(rq mode and \(lqmatch\(rq mode.
Match mode is used for configurations (meaning in all values in this
document described as \(lqregex\(rq).
Search mode is used for the on\-page search function (using
searchForward/isearchForward etc.)
.SS Match mode
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
.EX
\(haabcd \-> \(haabcd (no change, only beginning is matched)
efgh$ \-> efgh$ (no change, only end is matched)
\(haijkl$ \-> \(haijkl$ (no change, the entire line is matched)
mnop \-> \(hamnop$ (changed to exact match, the entire line is matched)
.EE
.PP
Match mode has no way to toggle JavaScript regex flags like
\f[CR]i\f[R].
.SS Search mode
For on\-page search, the above transformations do not apply; the search
\f[CR]/abcd\f[R] searches for the string \f[CR]abcd\f[R] inside all
lines.
.PP
Search mode also has some other convenience transformations (these do
not work in match mode):
.IP \(bu 2
The string \f[CR]\(rsc\f[R] (backslash + lower\-case c) inside a
search\-mode regex enables case\-insensitive matching.
.IP \(bu 2
Conversely, \f[CR]\(rsC\f[R] (backslash + capital C) disables
case\-insensitive matching.
(Useful if you have \f[CR]ignore\-case\f[R] set to true, which is the
default.)
.IP \(bu 2
\f[CR]\(rs<\f[R] and \f[CR]\(rs>\f[R] is converted to \f[CR]\(rsb\f[R]
(as in vi, grep, etc.)
.PP
Like match mode, search mode operates on individual lines.
This means that search patterns do not match text wrapped over multiple
lines.
.SS Path handling
Rules for path handling are similar to how the shell handles strings.
.IP \(bu 2
Tilde\-expansion is used to determine the user\(cqs home directory.
So e.g.\ \f[CR]\(ti/whatever\f[R] works.
.IP \(bu 2
Environment variables can be used like \f[CR]$ENV_VAR\f[R].
.IP \(bu 2
Relative paths are relative to the Chawan configuration directory
(i.e.\ \f[CR]$CHA_DIR\f[R]).
.PP
Some environment variables are also exported by Chawan:
.IP \(bu 2
\f[CR]$CHA_BIN_DIR\f[R]: the directory which the \f[CR]cha\f[R] binary
resides in.
Symbolic links are automatically resolved to determine this path.
.IP \(bu 2
\f[CR]$CHA_LIBEXEC_DIR\f[R]: the directory for all executables Chawan
uses for operation.
By default, this is \f[CR]$CHA_BIN_DIR/../libexec/chawan\f[R].
.IP \(bu 2
\f[CR]$CHA_DIR\f[R]: the configuration directory.
(This can also be set by the user; see the top section for details.)
.IP \(bu 2
\f[CR]$CHA_DATA_DIR\f[R]: if the configuration file uses XDG base
directories, this is
\f[CR]${XDG_DATA_HOME:\-$HOME/.local/share}/chawan\f[R].
Otherwise, it is the same as \f[CR]$CHA_DIR\f[R].
.RS 2
.IP \(bu 2
Exception: if \f[CR]$CHA_DIR\f[R] is set before \f[CR]cha\f[R] is
invoked, then \f[CR]$CHA_DATA_DIR\f[R] is also read.
This is to make nested invocations work in configurations with XDG
basedirs.
.RE
.SS Word types
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
A w3m word is a sequence of alphanumeric characters.
Symbols are treated in the same way as whitespace.
.SS vi word
A vi word is a sequence of characters in the same character category.
Currently, character categories are alphanumeric characters, symbols,
han letters, hiragana, katakana, and hangul.
.PP
vi words may be separated by whitespace; however, vi words from separate
categories do not have to be whitespace\-separated.
e.g.\ the following character sequence contains two words:
.IP
.EX
hello[]+{}\(at\(ga!
.EE
.SS Big word
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
\f[B]cha\f[R](1) \f[B]cha\-api\f[R](7)