diff options
author | bptato <nincsnevem662@gmail.com> | 2024-06-24 18:28:06 +0200 |
---|---|---|
committer | bptato <nincsnevem662@gmail.com> | 2024-06-24 18:28:06 +0200 |
commit | 43ea49c215c85925b8a4eb8661a37fc71c521cfd (patch) | |
tree | efcca78216b2c2c6361925c94415b728afb604cd | |
parent | 34690f5ba45c5d67f8a59ecb09c40da07481c40f (diff) | |
download | chawan-43ea49c215c85925b8a4eb8661a37fc71c521cfd.tar.gz |
doc: update manpages
-rw-r--r-- | doc/cha-api.5 | 13 | ||||
-rw-r--r-- | doc/cha-config.5 | 54 | ||||
-rw-r--r-- | doc/cha-localcgi.5 | 278 | ||||
-rw-r--r-- | doc/cha-mailcap.5 | 111 | ||||
-rw-r--r-- | doc/cha-mime.types.5 | 50 | ||||
-rw-r--r-- | doc/cha-protocols.5 | 2 | ||||
-rw-r--r-- | doc/cha-urimethodmap.5 | 129 |
7 files changed, 287 insertions, 350 deletions
diff --git a/doc/cha-api.5 b/doc/cha-api.5 index 5ffdf460..66088fa9 100644 --- a/doc/cha-api.5 +++ b/doc/cha-api.5 @@ -1,5 +1,5 @@ '\" t -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" .TH "cha\-api" "5" "" "" "Chawan\[cq]s command API" .SH Chawan\[cq]s command API @@ -140,12 +140,13 @@ Duplicate the current buffer by loading its source to a new buffer. T}@T{ T} T{ -\f[CR]discardBuffer()\f[R] +\f[CR]discardBuffer(buffer = pager.buffer, dir = pager.navDirection)\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. +Discard \f[CR]buffer\f[R], then move back to the buffer opposite to +\f[CR]dir\f[R]. +Possible values of \f[CR]dir\f[R] are: \[lq]prev\[rq], \[lq]next\[rq], +\[lq]prev\-sibling\[rq], \[lq]next\-sibling\[rq], \[lq]parent\[rq], +\[lq]first\-child\[rq], \[lq]any\[rq]. T}@T{ T} T{ diff --git a/doc/cha-config.5 b/doc/cha-config.5 index 1fb0a804..48b60cac 100644 --- a/doc/cha-config.5 +++ b/doc/cha-config.5 @@ -1,5 +1,5 @@ '\" t -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" .TH "cha\-config" "5" "" "" "Configuration of Chawan" .SH Configuration of Chawan @@ -553,6 +553,34 @@ fallback values provided above. T}@T{ T} .TE +.SS Protocol +Protocol\-related rules are to be placed in objects keyed as +\f[CR][protocol.{protocol\-name}]\f[R]. +e.g.\ FTP related rules are placed in in \f[CR][protocol.ftp]\f[R]. +.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{ +form\-request +T}@T{ +http, ftp, data, mailto +T}@T{ +Specify which protocol to imitate when submitting forms to this +protocol. +Defaults to HTTP. +T}@T{ +T} +.TE .SS Omnirule The omni\-bar (by default opened with C\-l) can be used to perform searches using omni\-rules. @@ -789,6 +817,16 @@ Please do not use this unless you are absolutely sure you know what you are doing. T}@T{ T} +T{ +autofocus +T}@T{ +boolean +T}@T{ +Defaults to false. +When set to true, elements with an \[ga]autofocus\[cq] attribute are +focused on automatically after the buffer is loaded. +T}@T{ +T} .TE .SS Stylesheets User stylesheets are to be placed in the \f[CR][css]\f[R] section. @@ -1029,10 +1067,16 @@ T} T{ \f[CR]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. +Discard the current buffer, and move back to the previous/next buffer +depending on what the previously viewed buffer was. +T}@T{ +T} +T{ +\f[CR]cmd.pager.discardBufferPrev\f[R], +\f[CR]cmd.pager.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{ T} T{ diff --git a/doc/cha-localcgi.5 b/doc/cha-localcgi.5 index c9a8a54e..138ac00a 100644 --- a/doc/cha-localcgi.5 +++ b/doc/cha-localcgi.5 @@ -1,101 +1,85 @@ -.\" Automatically generated by Pandoc 2.17.1.1 +.\" Automatically generated by Pandoc 3.2 .\" -.\" 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-localcgi" "5" "" "" "Local CGI support in Chawan" -.hy +.TH "cha\-localcgi" "5" "" "" "Local CGI support in Chawan" .SH Local CGI support in Chawan -.PP Chawan supports the invocation of CGI scripts locally. This feature can be used in the following way: .IP \[bu] 2 All local CGI scripts must be placed in a directory specified in -\f[V]external.cgi-dir\f[R]. +\f[CR]external.cgi\-dir\f[R]. Multiple directories can be specified in an array too, and directories specified first have higher precedence. .IP \[bu] 2 Then, a CGI script in one of these directories can be executed by -visiting the URL \f[V]cgi-bin:script-name\f[R]. +visiting the URL \f[CR]cgi\-bin:script\-name\f[R]. $PATH_INFO and $QUERY_STRING are set as normal, -i.e.\ \f[V]cgi-bin:script-name/abcd?defgh=ijkl\f[R] will set $PATH_INFO -to \f[V]/abcd\f[R], and $QUERY_STRING to \f[V]defgh=ijkl\f[R]. +i.e.\ \f[CR]cgi\-bin:script\-name/abcd?defgh=ijkl\f[R] will set +$PATH_INFO to \f[CR]/abcd\f[R], and $QUERY_STRING to +\f[CR]defgh=ijkl\f[R]. .PP Further notes on processing CGI paths: .IP \[bu] 2 The URL must be opaque, so you must not add a double slash after the scheme. -e.g.\ \f[V]cgi-bin://script-name\f[R] will NOT work, only -\f[V]cgi-bin:script-name\f[R]. +e.g.\ \f[CR]cgi\-bin://script\-name\f[R] will NOT work, only +\f[CR]cgi\-bin:script\-name\f[R]. .IP \[bu] 2 -Paths beginning with \f[V]/cgi-bin/\f[R] or \f[V]/$LIB/\f[R] are +Paths beginning with \f[CR]/cgi\-bin/\f[R] or \f[CR]/$LIB/\f[R] are stripped of this segment automatically. -So e.g.\ \f[V]cgi-bin:/cgi-bin/script-name\f[R] becomes -\f[V]cgi-bin:script-name\f[R]. +So e.g.\ \f[CR]cgi\-bin:/cgi\-bin/script\-name\f[R] becomes +\f[CR]cgi\-bin:script\-name\f[R]. .IP \[bu] 2 -If \f[V]external.w3m-cgi-compat\f[R] is true, file: URLs are converted -to cgi-bin: URLs if the path name starts with \f[V]/cgi-bin/\f[R], -\f[V]/$LIB/\f[R], or the path of a local CGI script. +If \f[CR]external.w3m\-cgi\-compat\f[R] is true, file: URLs are +converted to cgi\-bin: URLs if the path name starts with +\f[CR]/cgi\-bin/\f[R], \f[CR]/$LIB/\f[R], or the path of a local CGI +script. Note: this is unsafe, please do not use it unless you must. .IP \[bu] 2 Absolute paths are accepted as -e.g.\ \f[V]cgi-bin:/path/to/cgi/dir/script-name\f[R]. -Note however, that this only works if \f[V]/path/to/cgi/dir\f[R] has -already been specified as a CGI directory in \f[V]external.cgi-dir\f[R]. +e.g.\ \f[CR]cgi\-bin:/path/to/cgi/dir/script\-name\f[R]. +Note however, that this only works if \f[CR]/path/to/cgi/dir\f[R] has +already been specified as a CGI directory in +\f[CR]external.cgi\-dir\f[R]. .PP -Note that this is different from w3m\[cq]s cgi-bin functionality, in +Note that this is different from w3m\[cq]s cgi\-bin functionality, in that we use a custom scheme for local CGI instead of interpreting all requests to a designated path as a CGI request. (This incompatibility is bridged over when -\f[V]external.w3m-cgi-compat\f[R] is true.) +\f[CR]external.w3m\-cgi\-compat\f[R] is true.) .SS Headers -.PP Local CGI scripts may send some headers that Chawan will interpret specially (and thus will not pass forward to e.g.\ the fetch API, etc): .IP \[bu] 2 -\f[V]Status\f[R]: interpreted as the HTTP status code. +\f[CR]Status\f[R]: interpreted as the HTTP status code. .IP \[bu] 2 -\f[V]Cha-Control\f[R]: special header, see below. +\f[CR]Cha\-Control\f[R]: special header, see below. .PP Note that these headers MUST be sent before any regular headers. Headers received after a regular header or a -\f[V]Cha-Control: ControlDone\f[R] header will be treated as regular +\f[CR]Cha\-Control: ControlDone\f[R] header will be treated as regular headers. .PP -The \f[V]Cha-Control\f[R] header\[cq]s value is parsed as follows: +The \f[CR]Cha\-Control\f[R] header\[cq]s value is parsed as follows: .IP -.nf -\f[C] -Cha-Control-Value = Command *Parameter +.EX +Cha\-Control\-Value = Command *Parameter Command = ALPHA *ALPHA Parameter = SPACE *CHAR -\f[R] -.fi +.EE .PP -In other words, it is \f[V]Command [Param1] [Param2] ...\f[R]. +In other words, it is \f[CR]Command [Param1] [Param2] ...\f[R]. .PP Currently available commands are: .IP \[bu] 2 -\f[V]Connected\f[R]: Takes no parameters. +\f[CR]Connected\f[R]: Takes no parameters. Must be the first reported header; it means that connection to the server has been successfully established, but no data has been received yet. When any other header is sent first, Chawan will act as if a -\f[V]Cha-Control: Connected\f[R] header had been implicitly sent before -that. +\f[CR]Cha\-Control: Connected\f[R] header had been implicitly sent +before that. .IP \[bu] 2 -\f[V]ConnectionError\f[R]: Must be the first reported header. +\f[CR]ConnectionError\f[R]: Must be the first reported header. Parameter 1 is the error code, see below. If any following parameters are given, they are concatenated to form a custom error message. @@ -103,234 +87,222 @@ Note: short but descriptive error messages are preferred, messages that do not fit on the screen are currently truncated. (TODO fix this somehow :P) .IP \[bu] 2 -\f[V]ControlDone\f[R]: Signals that no more special headers will be -sent; this means that \f[V]Cha-Control\f[R] and \f[V]Status\f[R] headers -sent after this must be interpreted as regular headers (and thus +\f[CR]ControlDone\f[R]: Signals that no more special headers will be +sent; this means that \f[CR]Cha\-Control\f[R] and \f[CR]Status\f[R] +headers sent after this must be interpreted as regular headers (and thus e.g.\ will be available for JS code calling the script using the fetch API). -WARNING: this header must be sent before any non-hardcoded headers that +WARNING: this header must be sent before any non\-hardcoded headers that take external input. For example, an HTTP client would have to send -\f[V]Cha-Control: ControlDone\f[R] before returning the retrieved +\f[CR]Cha\-Control: ControlDone\f[R] before returning the retrieved headers. .PP List of public error codes: .IP \[bu] 2 -\f[V]1 internal error\f[R]: An internal error prevented the script from +\f[CR]1 internal error\f[R]: An internal error prevented the script from retrieving the requested resource. CGI scripts can also use this to signal that they have no information on what went wrong. .IP \[bu] 2 -\f[V]2 invalid method\f[R]: The client requested data using a method not -supported by this protocol. +\f[CR]2 invalid method\f[R]: The client requested data using a method +not supported by this protocol. .IP \[bu] 2 -\f[V]3 invalid URL\f[R]: The request URL could not be interpreted as a +\f[CR]3 invalid URL\f[R]: The request URL could not be interpreted as a valid URL for this format. .IP \[bu] 2 -\f[V]4 file not found\f[R]: No file was found at the requested address, +\f[CR]4 file not found\f[R]: No file was found at the requested address, and thus the request is meaningless. Note: this should only be used by protocols that do not rely on a -client-server architecture, e.g.\ local file access, local databases, or -peer-to-peer file retrieval mechanisms. +client\-server architecture, e.g.\ local file access, local databases, +or peer\-to\-peer file retrieval mechanisms. A server responding with \[lq]no file found\[rq] is NOT a connection error, and is better represented as a response with a 404 status code. .IP \[bu] 2 -\f[V]5 failed to resolve host\f[R]: The hostname could not be resolved. +\f[CR]5 failed to resolve host\f[R]: The hostname could not be resolved. .IP \[bu] 2 -\f[V]6 failed to resolve proxy\f[R]: The proxy could not be resolved. +\f[CR]6 failed to resolve proxy\f[R]: The proxy could not be resolved. .IP \[bu] 2 -\f[V]7 connection refused\f[R]: The server refused to establish a +\f[CR]7 connection refused\f[R]: The server refused to establish a connection. .IP \[bu] 2 -\f[V]8 proxy refused to connect\f[R]: The proxy refused to establish a +\f[CR]8 proxy refused to connect\f[R]: The proxy refused to establish a connection. .SS Environment variables -.PP Chawan sets the following environment variables: .IP \[bu] 2 -\f[V]SERVER_SOFTWARE=\[dq]Chawan\[dq]\f[R] +\f[CR]SERVER_SOFTWARE=\[dq]Chawan\[dq]\f[R] .IP \[bu] 2 -\f[V]SERVER_PROTOCOL=\[dq]HTTP/1.0\[dq]\f[R] +\f[CR]SERVER_PROTOCOL=\[dq]HTTP/1.0\[dq]\f[R] .IP \[bu] 2 -\f[V]SERVER_NAME=\[dq]localhost\[dq]\f[R] +\f[CR]SERVER_NAME=\[dq]localhost\[dq]\f[R] .IP \[bu] 2 -\f[V]SERVER_PORT=\[dq]80\[dq]\f[R] +\f[CR]SERVER_PORT=\[dq]80\[dq]\f[R] .IP \[bu] 2 -\f[V]REMOTE_HOST=\[dq]localhost\[dq]\f[R] +\f[CR]REMOTE_HOST=\[dq]localhost\[dq]\f[R] .IP \[bu] 2 -\f[V]REMOTE_ADDR=\[dq]127.0.0.1\[dq]\f[R] +\f[CR]REMOTE_ADDR=\[dq]127.0.0.1\[dq]\f[R] .IP \[bu] 2 -\f[V]GATEWAY_INTERFACE=\[dq]CGI/1.1\[dq]\f[R] +\f[CR]GATEWAY_INTERFACE=\[dq]CGI/1.1\[dq]\f[R] .IP \[bu] 2 -\f[V]SCRIPT_NAME=\[dq]/cgi-bin/script-name\[dq]\f[R] if called with a -relative path, and \f[V]\[dq]/path/to/script/script-name\[dq]\f[R] if +\f[CR]SCRIPT_NAME=\[dq]/cgi\-bin/script\-name\[dq]\f[R] if called with a +relative path, and \f[CR]\[dq]/path/to/script/script\-name\[dq]\f[R] if called with an absolute path. .IP \[bu] 2 -\f[V]SCRIPT_FILENAME=\[dq]/path/to/script/script-name\[dq]\f[R] +\f[CR]SCRIPT_FILENAME=\[dq]/path/to/script/script\-name\[dq]\f[R] .IP \[bu] 2 -\f[V]QUERY_STRING=\f[R] the query string (i.e.\ \f[V]URL.search\f[R]). -Note that this variable is percent-encoded. +\f[CR]QUERY_STRING=\f[R] the query string (i.e.\ \f[CR]URL.search\f[R]). +Note that this variable is percent\-encoded. .IP \[bu] 2 -\f[V]PATH_INFO=\f[R] everything after the script\[cq]s path name, -e.g.\ for \f[V]cgi-bin:script-name/abcd/efgh\f[R] -\f[V]\[dq]/abcd/efgh\[dq]\f[R]. -Note that this variable is NOT percent-encoded. +\f[CR]PATH_INFO=\f[R] everything after the script\[cq]s path name, +e.g.\ for \f[CR]cgi\-bin:script\-name/abcd/efgh\f[R] +\f[CR]\[dq]/abcd/efgh\[dq]\f[R]. +Note that this variable is NOT percent\-encoded. .IP \[bu] 2 -\f[V]REQUEST_URI=\[dq]$SCRIPT_NAME/$PATH_INFO?$QUERY_STRING\f[R] +\f[CR]REQUEST_URI=\[dq]$SCRIPT_NAME/$PATH_INFO?$QUERY_STRING\f[R] .IP \[bu] 2 -\f[V]REQUEST_METHOD=\f[R] HTTP method used for making the request, +\f[CR]REQUEST_METHOD=\f[R] HTTP method used for making the request, e.g.\ GET or POST .IP \[bu] 2 -\f[V]REQUEST_HEADERS=\f[R] A newline-separated list of all headers for +\f[CR]REQUEST_HEADERS=\f[R] A newline\-separated list of all headers for this request. .IP \[bu] 2 -\f[V]CHA_LIBEXEC_DIR=\f[R] The libexec directory Chawan was configured +\f[CR]CHA_LIBEXEC_DIR=\f[R] The libexec directory Chawan was configured to use at compile time. See the tools section below for details of why this is useful. .IP \[bu] 2 -\f[V]CONTENT_TYPE=\f[R] for POST requests, the Content-Type header. +\f[CR]CONTENT_TYPE=\f[R] for POST requests, the Content\-Type header. Not set for other request types (e.g.\ GET). .IP \[bu] 2 -\f[V]CONTENT_LENGTH=\f[R] the content length, if $CONTENT_TYPE has been +\f[CR]CONTENT_LENGTH=\f[R] the content length, if $CONTENT_TYPE has been set. .IP \[bu] 2 -\f[V]ALL_PROXY=\f[R] if a proxy has been set, the proxy URL. +\f[CR]ALL_PROXY=\f[R] if a proxy has been set, the proxy URL. WARNING: for security reasons, this MUST be respected when making external connections. If a CGI script does not support proxies, it must never make any -external connections when the \f[V]ALL_PROXY\f[R] variable is set, even +external connections when the \f[CR]ALL_PROXY\f[R] variable is set, even if this results in it returning an error. .IP \[bu] 2 -\f[V]HTTP_COOKIE=\f[R] if set, the Cookie header. +\f[CR]HTTP_COOKIE=\f[R] if set, the Cookie header. .IP \[bu] 2 -\f[V]HTTP_REFERER=\f[R] if set, the Referer header. +\f[CR]HTTP_REFERER=\f[R] if set, the Referer header. .PP For requests originating from a urimethodmap rewrite, Chawan will also set the parsed URL\[cq]s parts as environment variables. Use of these is highly encouraged, to avoid exploits originating from -double-parsing of URLs. +double\-parsing of URLs. .PP e.g.\ if example://username:password\[at]example.org:1234/path/name.html?example is the original URL, then: .IP \[bu] 2 -\f[V]MAPPED_URI_SCHEME=\f[R] the scheme of the original URL, in this -case \f[V]example\f[R]. +\f[CR]MAPPED_URI_SCHEME=\f[R] the scheme of the original URL, in this +case \f[CR]example\f[R]. .IP \[bu] 2 -\f[V]MAPPED_URI_USERNAME=\f[R] the username part, in this case -\f[V]username\f[R]. +\f[CR]MAPPED_URI_USERNAME=\f[R] the username part, in this case +\f[CR]username\f[R]. If no username was specified, the variable is set to the empty string. .IP \[bu] 2 -\f[V]MAPPED_URI_PASSWORD=\f[R] the password part, in this case -\f[V]password\f[R]. +\f[CR]MAPPED_URI_PASSWORD=\f[R] the password part, in this case +\f[CR]password\f[R]. If no password was specified, the variable is set to the empty string. .IP \[bu] 2 -\f[V]MAPPED_URI_HOST=\f[R] the host part, in this case -\f[V]host.org\f[R] If no host was specified, the variable is set to the +\f[CR]MAPPED_URI_HOST=\f[R] the host part, in this case +\f[CR]host.org\f[R] If no host was specified, the variable is set to the empty string. -(An example of a URL with no host: \f[V]about:blank\f[R], here -\f[V]blank\f[R] is the path name.) +(An example of a URL with no host: \f[CR]about:blank\f[R], here +\f[CR]blank\f[R] is the path name.) .IP \[bu] 2 -\f[V]MAPPED_URI_PORT=\f[R] the port, in this case \f[V]1234\f[R]. +\f[CR]MAPPED_URI_PORT=\f[R] the port, in this case \f[CR]1234\f[R]. If no port was specified, the variable is set to the empty string. (In this case, the CGI script is expected to use the default port for the scheme, if any.) .IP \[bu] 2 -\f[V]MAPPED_URI_PATH=\f[R] the path name, in this case -\f[V]/path/name.html?example\f[R]. +\f[CR]MAPPED_URI_PATH=\f[R] the path name, in this case +\f[CR]/path/name.html?example\f[R]. If no path was specified, the variable is set to the empty string. -Note: the path name is percent-encoded. +Note: the path name is percent\-encoded. .IP \[bu] 2 -\f[V]MAPPED_URI_QUERY=\f[R] the query string, in this case -\f[V]example\f[R]. +\f[CR]MAPPED_URI_QUERY=\f[R] the query string, in this case +\f[CR]example\f[R]. Note that, unlike in JavaScript, no question mark is prepended to the string. -The query string is percent-encoded as well. +The query string is percent\-encoded as well. .PP Note: the fragment part is omitted intentionally. .SS Request body -.PP If the request body is not empty, it is streamed into the program through the standard input. .PP -Note that this may be both an application/x-www-form-urlencoded or a -multipart/form-data request; \f[V]CONTENT_TYPE\f[R] stores information +Note that this may be both an application/x\-www\-form\-urlencoded or a +multipart/form\-data request; \f[CR]CONTENT_TYPE\f[R] stores information about the request type, and in case of a multipart request, the boundary as well. .SS Tools -.PP Chawan provides certain helper binaries that may be useful for CGI scripts. These can be portably accessed by executing -\f[V]\[dq]$CHA_LIBEXEC_DIR\[dq]/[program name]\f[R]. +\f[CR]\[dq]$CHA_LIBEXEC_DIR\[dq]/[program name]\f[R]. .PP Currently, the following tools are available: .IP \[bu] 2 -\f[V]urldec\f[R]: percent-decode strings passed on standard input. +\f[CR]urldec\f[R]: percent\-decode strings passed on standard input. .IP \[bu] 2 -\f[V]urlenc\f[R]: percent-encode strings passed on standard input, -taking a percent-encode set as the first parameter. +\f[CR]urlenc\f[R]: percent\-encode strings passed on standard input, +taking a percent\-encode set as the first parameter. .SS Troubleshooting -.PP Note that standard error is redirected to the browser console (by -default, M-cM-c). +default, M\-cM\-c). This makes it easy to debug a misbehaving CGI script, but may also slow down the browser in case of excessive logging. If this is not the desired behavior, we recommend wrapping your script into a shell script that redirects stderr to /dev/null. -.SS My script is returning a \[lq]no local-CGI directory configured\[rq] error message. -.PP -Currently, the default setting includes a cgi-bin directory at -\f[V]$(which cha)/../libexec/chawan/cgi-bin\f[R], which usually looks -something like \f[V]/usr/local/libexec/chawan/cgi-bin\f[R]. -You only get the above message if you intentionally set the cgi-dir +.SS My script is returning a \[lq]no local\-CGI directory configured\[rq] error message. +Currently, the default setting includes a cgi\-bin directory at +\f[CR]$(which cha)/../libexec/chawan/cgi\-bin\f[R], which usually looks +something like \f[CR]/usr/local/libexec/chawan/cgi\-bin\f[R]. +You only get the above message if you intentionally set the cgi\-dir setting to an empty array. (This will likely break everything else too, so do not.) .PP -To change the default local-CGI directory, use the -\f[V]external.cgi-dir\f[R] option. +To change the default local\-CGI directory, use the +\f[CR]external.cgi\-dir\f[R] option. .PP e.g.\ you could add this to your config.toml: .IP -.nf -\f[C] -[external] -cgi-dir = [\[dq]\[ti]/cgi-bin\[dq], \[dq]${%CHA_LIBEXEC_DIR}/cgi-bin\[dq]] -\f[R] -.fi +.EX +\f[B][external]\f[R] +cgi\-dir = [\[dq]\[ti]/cgi\-bin\[dq], \[dq]${%CHA_LIBEXEC_DIR}/cgi\-bin\[dq]] +.EE .PP -and then put your script in \f[V]$HOME/cgi-bin\f[R]. +and then put your script in \f[CR]$HOME/cgi\-bin\f[R]. Note the second element in the array; if you don\[cq]t add it, the default CGI scripts (including http, https, etc\&...) will not work. .SS My script is returning a \[lq]Failed to execute script\[rq] error message. -.PP -This means the \f[V]execl\f[R] call to the script failed. +This means the \f[CR]execl\f[R] call to the script failed. Make sure that your CGI script\[cq]s executable bit is set, i.e.\ run -\f[V]chmod +x /path/to/cgi/script\f[R]. +\f[CR]chmod +x /path/to/cgi/script\f[R]. .SS My script is returning an \[lq]invalid CGI path\[rq] error message. -.PP Make sure that you did not include leading slashes. -Reminder: \f[V]cgi-bin://script-name\f[R] does not work, use -\f[V]cgi-bin:script-name\f[R]. +Reminder: \f[CR]cgi\-bin://script\-name\f[R] does not work, use +\f[CR]cgi\-bin:script\-name\f[R]. .SS My script is returning a \[lq]CGI file not found\[rq] error message. -.PP Double check that your CGI script is in the correct location. Also, make sure that you are not accidentally calling the script with an -absolute path via \f[V]cgi-bin:/script-name\f[R] (instead of the correct -\f[V]cgi-bin:script-name\f[R]). +absolute path via \f[CR]cgi\-bin:/script\-name\f[R] (instead of the +correct \f[CR]cgi\-bin:script\-name\f[R]). .PP -It is also possible that \f[V]external.cgi-dir\f[R] is not really set to -the directory your script is in. +It is also possible that \f[CR]external.cgi\-dir\f[R] is not really set +to the directory your script is in. Note that by default, this depends on the binary\[cq]s path, so e.g.\ if -your binary is in \f[V]\[ti]/src/chawan/target/release/bin/cha\f[R], but -you put your CGI script to \f[V]/usr/local/libexec/chawan/cgi-bin\f[R], -then it will not work. +your binary is in \f[CR]\[ti]/src/chawan/target/release/bin/cha\f[R], +but you put your CGI script to +\f[CR]/usr/local/libexec/chawan/cgi\-bin\f[R], then it will not work. .SS My script is returning a \[lq]failed to set up CGI script\[rq] error message. -.PP -This means that either \f[V]pipe\f[R] or \f[V]fork\f[R] failed. +This means that either \f[CR]pipe\f[R] or \f[CR]fork\f[R] failed. Something strange is going on with your system; we recommend exorcism. (Maybe you are running out of memory?) .SS See also -.PP \f[B]cha\f[R](1) diff --git a/doc/cha-mailcap.5 b/doc/cha-mailcap.5 index 9972b63a..7b95864c 100644 --- a/doc/cha-mailcap.5 +++ b/doc/cha-mailcap.5 @@ -1,64 +1,47 @@ -.\" Automatically generated by Pandoc 2.17.1.1 +.\" Automatically generated by Pandoc 3.2 .\" -.\" 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-mailcap" "5" "" "" "Mailcap support in Chawan" -.hy +.TH "cha\-mailcap" "5" "" "" "Mailcap support in Chawan" .SH Mailcap -.PP Chawan\[cq]s buffers can only handle HTML and plain text. To make Chawan recognize other file formats, the mailcap file format can be used. .PP Note that Chawan\[cq]s default mime.types file only recognizes a few file extensions, which may result in your entries not being executed. -Please consult the \f[B]cha-mime.types\f[R](5) documentation for +Please consult the \f[B]cha\-mime.types\f[R](5) documentation for details. .PP -For an exact description of the mailcap format, see RFC -1524 (https://www.rfc-editor.org/rfc/rfc1524). +For an exact description of the mailcap format, see \c +.UR https://www.rfc-editor.org/rfc/rfc1524 +RFC 1524 +.UE \c +\&. .SS Search path -.PP The search path for mailcap files can be overridden using the -configuration variable \f[V]external.mailcap\f[R]. +configuration variable \f[CR]external.mailcap\f[R]. .PP -By default, the only file checked by Chawan is \f[V]$HOME/.mailcap\f[R]. +By default, the only file checked by Chawan is +\f[CR]$HOME/.mailcap\f[R]. .PP In the past, the full path from the specification was used. This was changed because mailcap files shipped with various systems are usually incompatible with the assumptions Chawan makes about mailcap file contents. -You can restore the old/standard-recommended behavior by adding this to +You can restore the old/standard\-recommended behavior by adding this to your config.toml: .IP -.nf -\f[C] +.EX mailcap = [ \[dq]\[ti]/.mailcap\[dq], \[dq]/etc/mailcap\[dq], \[dq]/usr/etc/mailcap\[dq], \[dq]/usr/local/etc/mailcap\[dq] ] -\f[R] -.fi +.EE .SS Format -.PP Chawan tries to adhere to the format described in RFC 1524, with a few extensions. .SS Templating -.PP %s, %t works as described in the standard. However, named content type fields (%{\&...}) only work with %{charset} as of now. @@ -69,92 +52,86 @@ If no quoting is applied, Chawan will quote the templates automatically. .PP DEPRECATED: .PP -Also, the non-standard template %u may be specified to get the original +Also, the non\-standard template %u may be specified to get the original URL of the resource. Note that this is no longer recommended; instead, use the $MAILCAP_URL environment variable which is set to the same value before the execution of every mailcap command. .SS Fields -.PP -The \f[V]test\f[R], \f[V]nametemplate\f[R], \f[V]needsterminal\f[R] and -\f[V]copiousoutput\f[R] fields are recognized. -Additionally, the non-standard \f[V]x-htmloutput\f[R] and -\f[V]x-ansioutput\f[R] extension fields are recognized too. +The \f[CR]test\f[R], \f[CR]nametemplate\f[R], \f[CR]needsterminal\f[R] +and \f[CR]copiousoutput\f[R] fields are recognized. +Additionally, the non\-standard \f[CR]x\-htmloutput\f[R] and +\f[CR]x\-ansioutput\f[R] extension fields are recognized too. .IP \[bu] 2 -When the \f[V]test\f[R] named field is specified, the mailcap entry is +When the \f[CR]test\f[R] named field is specified, the mailcap entry is only used if the test command returns 0. -Warning: as of now, \f[V]%s\f[R] does not work with \f[V]test\f[R]; -\f[V]test\f[R] named fields with a \f[V]%s\f[R] template are skipped. -Additionally, no data is piped into \f[V]test\f[R] either. +Warning: as of now, \f[CR]%s\f[R] does not work with \f[CR]test\f[R]; +\f[CR]test\f[R] named fields with a \f[CR]%s\f[R] template are skipped. +Additionally, no data is piped into \f[CR]test\f[R] either. .IP \[bu] 2 -\f[V]copiousoutput\f[R] makes Chawan redirect the output of the external -command into a new buffer. -If either x-htmloutput or x-ansioutput is defined too, then it is +\f[CR]copiousoutput\f[R] makes Chawan redirect the output of the +external command into a new buffer. +If either x\-htmloutput or x\-ansioutput is defined too, then it is ignored. .IP \[bu] 2 -The \f[V]x-htmloutput\f[R] extension field behaves the same as -\f[V]copiousoutput\f[R], but makes Chawan interpret the command\[cq]s +The \f[CR]x\-htmloutput\f[R] extension field behaves the same as +\f[CR]copiousoutput\f[R], but makes Chawan interpret the command\[cq]s output as HTML. .IP \[bu] 2 -\f[V]x-ansioutput\f[R] makes Chawan pipe the output through the default -\[lq]text/x-ansi\[rq] content type handler. +\f[CR]x\-ansioutput\f[R] makes Chawan pipe the output through the +default \[lq]text/x\-ansi\[rq] content type handler. This means that you get colors, formatting, etc. displayed with ANSI escape sequences. .IP \[bu] 2 -\f[V]needsterminal\f[R] hands over control of the terminal to the +\f[CR]needsterminal\f[R] hands over control of the terminal to the command while it is running. -Note: as of now, \f[V]needsterminal\f[R] does nothing if either -\f[V]copiousoutput\f[R] or \f[V]x-htmloutput\f[R] is specified. +Note: as of now, \f[CR]needsterminal\f[R] does nothing if either +\f[CR]copiousoutput\f[R] or \f[CR]x\-htmloutput\f[R] is specified. .IP \[bu] 2 -For a description of \f[V]nametemplate\f[R], see the RFC. +For a description of \f[CR]nametemplate\f[R], see the RFC. Note however, that it does not work with test (since %s is not supported there). .SS Environment variables -.PP As noted above, the $MAILCAP_URL variable is set to the URL of the target resource before the execution of the mailcap command. Backwards compatibility with mailcap agents that do not support this variable can be achieved through shell substitution, -e.g.\ ${MAILCAP_URL:-string for when it is unsupported}. +e.g.\ ${MAILCAP_URL:\-string for when it is unsupported}. .PP Note that it is not recommended to set %s as the fallback, because it will force Chawan to download the entire file before displaying it even if it could have been piped into the command. .SS Note -.PP Entries with a content type of text/html or text/plain are ignored. .SS Examples .IP -.nf -\f[C] +.EX # Note: these examples require an entry in mime.types that sets e.g. md as # the markdown content type. # Handle markdown files using pandoc. -text/markdown; pandoc - -f markdown -t html -o -; x-htmloutput +text/markdown; pandoc \- \-f markdown \-t html \-o \-; x\-htmloutput # Show syntax highlighting for JavaScript source files using bat. -text/javascript; bat -f -l es6 --file-name ${MAILCAP_URL:-STDIN} -; x-ansioutput +text/javascript; bat \-f \-l es6 \-\-file\-name ${MAILCAP_URL:\-STDIN} \-; x\-ansioutput # Play music using mpv, and hand over control of the terminal until mpv exits. -audio/*; mpv -; needsterminal +audio/*; mpv \-; needsterminal # Play videos using mpv in the background, redirecting its standard output # and standard error to /dev/null. -video/*; mpv - +video/*; mpv \- # Open docx files using LibreOffice Writer. -application/vnd.openxmlformats-officedocument.wordprocessingml.document;lowriter %s +application/vnd.openxmlformats\-officedocument.wordprocessingml.document;lowriter %s # (Wow that was ugly.) # Display manpages using pandoc. (Make sure the mime type matches the one # set in your mime.types file for extensions .1, .2, .3, ...) -application/x-troff-man;pandoc - -f man -t html -o -; x-htmloutput +application/x\-troff\-man;pandoc \- \-f man \-t html \-o \-; x\-htmloutput # Following entry will be ignored, as text/html is supported natively by Chawan. -text/html; cha -dT text/html -I %{charset}; copiousoutput -\f[R] -.fi +text/html; cha \-dT text/html \-I %{charset}; copiousoutput +.EE .SS See also -.PP \f[B]cha\f[R](1) diff --git a/doc/cha-mime.types.5 b/doc/cha-mime.types.5 index c0f9aa14..ffe7d1cc 100644 --- a/doc/cha-mime.types.5 +++ b/doc/cha-mime.types.5 @@ -1,44 +1,24 @@ -.\" Automatically generated by Pandoc 2.17.1.1 +.\" Automatically generated by Pandoc 3.2 .\" -.\" 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" "" "" "MIME type detection in Chawan" -.hy +.TH "cha\-config" "5" "" "" "MIME type detection in Chawan" .SH mime.types -.PP Chawan uses the mime.types file to recognize certain file extensions for matching mailcap entries. -See the \f[B]cha-mailcap\f[R](5) documentation for a description of +See the \f[B]cha\-mailcap\f[R](5) documentation for a description of mailcap. .SS Search path -.PP Chawan parses all mime.types files defined in -\f[V]external.mime-types\f[R]. -If no mime.types file was found, the built-in mime type associations are -used. +\f[CR]external.mime\-types\f[R]. +If no mime.types file was found, the built\-in mime type associations +are used. .PP The default search path for mime.types files is: .IP -.nf -\f[C] +.EX $HOME/.mime.types:/etc/mime.types:/usr/etc/mime.types:/usr/local/etc/mime.types -\f[R] -.fi +.EE .SS Format -.PP -The mime.types file is a list of whitespace-separated columns. +The mime.types file is a list of whitespace\-separated columns. The first column represents the mime type, all following columns are file extensions. .PP @@ -47,18 +27,15 @@ are ignored. .PP Example: .IP -.nf -\f[C] +.EX # comment -application/x-example exmpl ex -\f[R] -.fi +application/x\-example exmpl ex +.EE .PP This mime.types file would register the file extensions \[lq]exmpl\[rq] and \[lq]ex\[rq] to be recognized as the mime type -\f[V]application/x-example\f[R]. +\f[CR]application/x\-example\f[R]. .SS Note -.PP Chawan only uses mime.types files for finding mailcap entries; buffers use an internal mime.types file for content type detection instead. .PP @@ -68,5 +45,4 @@ formats). Therefore it is highly recommended to configure at least one external mime.types file if you use mailcap. .SS See also -.PP \f[B]cha\f[R](1) diff --git a/doc/cha-protocols.5 b/doc/cha-protocols.5 index a5299ea9..1f75b4f4 100644 --- a/doc/cha-protocols.5 +++ b/doc/cha-protocols.5 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" .TH "cha\-protocols" "5" "" "" "Protocol support in Chawan" .SH Protocols diff --git a/doc/cha-urimethodmap.5 b/doc/cha-urimethodmap.5 index 98dd6dbe..df03b508 100644 --- a/doc/cha-urimethodmap.5 +++ b/doc/cha-urimethodmap.5 @@ -1,62 +1,40 @@ -.\" Automatically generated by Pandoc 2.17.1.1 +.\" Automatically generated by Pandoc 3.2 .\" -.\" 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-urimethodmap" "5" "" "" "URI method map support in Chawan" -.hy +.TH "cha\-urimethodmap" "5" "" "" "URI method map support in Chawan" .SH URI method map support in Chawan -.PP Chawan can be used to map unrecognized protocols to known protocols -using the \f[V]urimethodmap\f[R] format. +using the \f[CR]urimethodmap\f[R] format. .PP The main use case for this is implementing handlers to protocols unknown to Chawan through a protocol that the browser \f[I]does\f[R] understand. .SS Search path -.PP The search path for urimethodmap files can be overridden using the -configuration variable \f[V]external.urimethodmap\f[R]. +configuration variable \f[CR]external.urimethodmap\f[R]. .PP The default search path for urimethodmap files is: .IP -.nf -\f[C] +.EX $HOME/.urimethodmap:$HOME/.w3m/urimethodmap:/etc/urimethodmap:/usr/local/etc/urimethodmap -\f[R] -.fi +.EE .SS Format -.PP The urimethodmap format is taken 1:1 from w3m, with only some modifications to the interpretation of templates. .PP A rough attempt at the formal description of this: .IP -.nf -\f[C] -URIMethodMap-File = *URIMethodMap-line +.EX +URIMethodMap\-File = *URIMethodMap\-line -URIMethodMap-Line = Comment / URIMethodMap-Entry +URIMethodMap\-Line = Comment / URIMethodMap\-Entry -URIMethodMap-Entry = Protocol *WHITESPACE Template *WHITESPACE CR +URIMethodMap\-Entry = Protocol *WHITESPACE Template *WHITESPACE CR Protocol = 1*CHAR COLON Template = [see below] Comment = *WHITESPACE CR / \[dq]#\[dq] *CHAR CR -\f[R] -.fi +.EE .PP Note that an ASCII colon sign (:) must be present after the protocol name. @@ -64,100 +42,89 @@ However, the whitespace may be omitted. .PP Examples: .IP -.nf -\f[C] +.EX # This is ok: -protocol: /cgi-bin/interpret-protocol?%s +protocol: /cgi\-bin/interpret\-protocol?%s # This is ok too: -protocol:/cgi-bin/interpret-protocol?%s +protocol:/cgi\-bin/interpret\-protocol?%s # Spaces and tabs are both allowed, so this is also ok: -protocol: /cgi-bin/interpret-protocol?%s +protocol: /cgi\-bin/interpret\-protocol?%s # However, this is incorrect, because the colon sign is missing: -protocol /cgi-bin/interpret-protocol?%s -\f[R] -.fi +protocol /cgi\-bin/interpret\-protocol?%s +.EE .PP The redirection template is the target URL. -If the string \f[V]%s\f[R] is contained in the template, it will be +If the string \f[CR]%s\f[R] is contained in the template, it will be replaced by the target URL. .PP -Note: Chawan used to URL-encode the substituted URL in the past, but +Note: Chawan used to URL\-encode the substituted URL in the past, but this is no longer the case. .PP -For compatibility with w3m, templates starting with \f[V]/cgi-bin/\f[R] -and \f[V]file:/cgi-bin/\f[R] are special-cased and the starting string -is replaced with \f[V]cgi-bin:\f[R]. -So for example, the template \f[V]/cgi-bin/w3mdict.cgi\f[R] is the same -as \f[V]cgi-bin:w3mdict.cgi\f[R] (and so is -\f[V]file:/cgi-bin/w3mdict.cgi\f[R]). +For compatibility with w3m, templates starting with +\f[CR]/cgi\-bin/\f[R] and \f[CR]file:/cgi\-bin/\f[R] are special\-cased +and the starting string is replaced with \f[CR]cgi\-bin:\f[R]. +So for example, the template \f[CR]/cgi\-bin/w3mdict.cgi\f[R] is the +same as \f[CR]cgi\-bin:w3mdict.cgi\f[R] (and so is +\f[CR]file:/cgi\-bin/w3mdict.cgi\f[R]). .PP Example: .IP -.nf -\f[C] +.EX # The following are the same in Chawan -protocol: /cgi-bin/interpret-protocol?%s -protocol: file:/cgi-bin/interpret-protocol?%s +protocol: /cgi\-bin/interpret\-protocol?%s +protocol: file:/cgi\-bin/interpret\-protocol?%s # Note: this last entry does not work in w3m. -protocol: cgi-bin:interpret-protocol?%s -\f[R] -.fi +protocol: cgi\-bin:interpret\-protocol?%s +.EE .PP Note however that absolute paths to cgi scripts are NOT special cased, -so e.g.\ \f[V]file:///usr/local/libexec/w3m/cgi-bin/w3mdict.cgi\f[R] +so e.g.\ \f[CR]file:///usr/local/libexec/w3m/cgi\-bin/w3mdict.cgi\f[R] will simply open w3mdict.cgi in the file viewer. -(Unlike in w3m, where it could run \f[V]w3mdict.cgi\f[R] depending on +(Unlike in w3m, where it could run \f[CR]w3mdict.cgi\f[R] depending on the user\[cq]s configuration.) .SS Examples .SS In config.toml .IP -.nf -\f[C] +.EX # Following sets the urimethodmap search path to the path relative to the # configuration file. So if your configuration file is in # \[ti]/.config/chawan/config.toml, Chawan will use \[ti]/.config/chawan/urimethodmap. # in the same directory. [external] urimethodmap = \[dq]urimethodmap\[dq] -\f[R] -.fi +.EE .SS In urimethodmap .SS magnet.cgi .IP -.nf -\f[C] +.EX # Use the \[ga]magnet.cgi\[ga] CGI shell script to pass magnet links to Transmission. -magnet: /cgi-bin/magnet.cgi?%s -\f[R] -.fi +magnet: /cgi\-bin/magnet.cgi?%s +.EE .PP -\f[V]magnet.cgi\f[R] can be found in the \f[V]bonus/\f[R] directory. +\f[CR]magnet.cgi\f[R] can be found in the \f[CR]bonus/\f[R] directory. You can also write a local CGI wrapper to pass the links to your BitTorrent client of choice. .SS dict -.PP In w3m, urimethodmap is commonly (ab)used to define shorthands for CGI scripts. .PP This works in Chawan too; for an example, you could define a -\f[V]tl:\f[R] shorthand like this: +\f[CR]tl:\f[R] shorthand like this: .IP -.nf -\f[C] +.EX # (trans.cgi is a script you can find and study in the bonus/ directory.) -tl: /cgi-bin/trans.cgi?%s -\f[R] -.fi +tl: /cgi\-bin/trans.cgi?%s +.EE .PP Then, you could open the translation of any word using -\f[V]tl:word\f[R]. +\f[CR]tl:word\f[R]. .PP Note however that Chawan has a more powerful facility for substitution -shorthands like this in the form of omni-rules. -So if you want to redirect to an on-line dictionary site with tl:word +shorthands like this in the form of omni\-rules. +So if you want to redirect to an on\-line dictionary site with tl:word instead of providing a local CGI interface, it is probably easier to -just use omni-rules instead of urimethodmap + local CGI redirection. +just use omni\-rules instead of urimethodmap + local CGI redirection. .PP Rule of thumb: if you find yourself writing local CGI scripts that just -send a \f[V]Location:\f[R] header, maybe consider just using an -omni-rule. +send a \f[CR]Location:\f[R] header, maybe consider just using an +omni\-rule. |