diff options
| author | bptato <nincsnevem662@gmail.com> | 2025-02-20 19:15:12 +0100 |
|---|---|---|
| committer | bptato <nincsnevem662@gmail.com> | 2025-02-20 19:29:54 +0100 |
| commit | 377e85f29cbcd251c97882c271530396c7a9fbd8 (patch) | |
| tree | 4c4a5dcb2d922f180ad0ab0405c057a3954fe9c4 /doc | |
| parent | a1b027140bde18a6d47ad863c92bbbf189243d8b (diff) | |
| download | chawan-377e85f29cbcd251c97882c271530396c7a9fbd8.tar.gz | |
Update docs
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/cha-config.5 | 71 | ||||
| -rw-r--r-- | doc/cha-css.7 | 17 | ||||
| -rw-r--r-- | doc/cha-protocols.7 | 40 | ||||
| -rw-r--r-- | doc/config.md | 60 |
4 files changed, 118 insertions, 70 deletions
diff --git a/doc/cha-config.5 b/doc/cha-config.5 index 3026a56f..df468d21 100644 --- a/doc/cha-config.5 +++ b/doc/cha-config.5 @@ -27,8 +27,6 @@ the search path accomodates XDG basedirs as well: config file specified through \-C switch \-> use that .IP "2." 3 \f[CR]$CHA_DIR\f[R] is set \-> use \f[CR]$CHA_DIR\f[R]/config.toml -(\f[CR]$CHA_CONFIG_DIR\f[R] is a deprecated alias for -\f[CR]$CHA_DIR\f[R].) .IP "3." 3 \f[CR]$XDG_CONFIG_HOME\f[R] is set \-> use \f[CR]$XDG_CONFIG_HOME\f[R]/chawan/config.toml @@ -82,12 +80,21 @@ T} T{ headless T}@T{ -boolean +boolean / \[lq]dump\[rq] T}@T{ false T}@T{ -Whether Chawan should always start in headless mode. -Automatically enabled when Chawan is called with \-r. +When set to true or \[lq]dump\[rq], the browser does not take input; +instead, it prints a rendered version of all buffers in order, then +exits. +The difference between \f[CR]true\f[R] and \[lq]dump\[rq] is that +\f[CR]true\f[R] first waits for all scripts and network requests to run +to completion, while \[lq]dump\[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].) +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 +\[lq]dump\[rq]. T}@T{ T} T{ @@ -241,6 +248,17 @@ T}@T{ Whether or not browsing history should be saved to the disk. T}@T{ 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{ +T} .TE .SS Search Search options are to be placed in the \f[CR][search]\f[R] section. @@ -1245,6 +1263,16 @@ Whether or not browsing history should be saved to the disk for this URL. T}@T{ T} +T{ +mark\-links +T}@T{ +boolean +T}@T{ +\f[CR]buffer.history\f[R] +T}@T{ +Add numeric markers before links. +T}@T{ +T} .TE .SS Stylesheets User stylesheets are to be placed in the \f[CR][css]\f[R] section. @@ -2024,15 +2052,15 @@ characters, or any single non\-alphanumeric character. .EE .SS Appendix .SS Regex handling -Regular expressions are currently handled using libregexp which is -included in QuickJS. +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: -\[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 +\[lq]search\[rq] mode and \[lq]match\[rq] mode. +Match mode is used for configurations (meaning in all values in this +document described as \[lq]regex\[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 @@ -2055,7 +2083,8 @@ 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 -\[lq]Search\[rq] mode also has some other convenience transformations: +Search mode also has some other convenience transformations (these do +not work in match mode): .IP \[bu] 2 The string \f[CR]\[rs]c\f[R] (backslash + lower\-case c) inside a search\-mode regex enables case\-insensitive matching. @@ -2068,10 +2097,11 @@ default.) \f[CR]\[rs]<\f[R] and \f[CR]\[rs]>\f[R] is converted to \f[CR]\[rs]b\f[R] (as in vi, grep, etc.) .PP -Note that none of these work in \[lq]match\[rq] mode. +Like match mode, search mode operates on 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 strings in the shell are -handled. +Rules for path handling are similar to how the shell handles strings. .IP \[bu] 2 Tilde\-expansion is used to determine the user\[cq]s home directory. So e.g.\ \f[CR]\[ti]/whatever\f[R] works. @@ -2108,12 +2138,13 @@ Big words 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 alphanumeric characters, OR a sequence of -symbols. +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, symbolic and -alphanumeric vi words do not have to be whitespace\-separated. -e.g.\ following character sequence contains two words: +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]! diff --git a/doc/cha-css.7 b/doc/cha-css.7 index a5dae13b..b141e39a 100644 --- a/doc/cha-css.7 +++ b/doc/cha-css.7 @@ -33,10 +33,14 @@ clear color (hex values and functions \f[CR]rgb\f[R], \f[CR]rgba\f[R], \f[CR]hsl\f[R], \f[CR]hsla\f[R]) .IP \[bu] 2 -content +content (string, (no\-)open/close\-quote, counter()) +.IP \[bu] 2 +counter\-increment .IP \[bu] 2 counter\-reset .IP \[bu] 2 +counter\-set +.IP \[bu] 2 display (\f[CR]block\f[R], \f[CR]inline\-block\f[R], \f[CR]list\-item\f[R], \f[CR]table\f[R], \f[CR]table\-*\f[R], \f[CR]flex\f[R], \f[CR]inline\-flex\f[R], \f[CR]flow\-root\f[R]) @@ -123,7 +127,7 @@ width .IP \[bu] 2 word\-break .IP \[bu] 2 -z\-index (negative values are not respected yet) +z\-index .PP Shorthands: .IP \[bu] 2 @@ -194,6 +198,10 @@ node that is either an element node or a text node with non\-whitespace contents. (Modeled after \f[CR]\-moz\-first\-node\f[R] and \f[CR]\-moz\-last\-node\f[R].) +.IP \[bu] 2 +If \f[CR]buffer.mark\-links\f[R] is set, the +\f[CR]::\-cha\-link\-marker\f[R] pseudo\-element will be generated on +all anchor elements. .SS Rendering quirks These are willful violations of the standard, usually made to better fit the display model inherent to projecting the web to a cell\-based @@ -219,8 +227,9 @@ The lengths \f[CR]1em\f[R] and \f[CR]1ch\f[R] compute to the cell height and cell width respectively. .PP In outer inline boxes (\f[CR]inline\-block\f[R], -\f[CR]inline\-flex\f[R]), margins and padding that are smaller than one -cell (on the respective axis) are ignored. +\f[CR]inline\-flex\f[R]) and \f[CR]list\-item\f[R] boxes, margins and +padding that are smaller than one cell (on the respective axis) are +ignored. This does not apply to blockified inline boxes. .PP When calculating clip boxes (\f[CR]overflow: hidden\f[R] or diff --git a/doc/cha-protocols.7 b/doc/cha-protocols.7 index b388681a..7aae3b95 100644 --- a/doc/cha-protocols.7 +++ b/doc/cha-protocols.7 @@ -91,7 +91,7 @@ protocol\-specific line type. This is sort of supported through a sed filter for gemtext outputs in the CGI script (in other words, no modification to gmi2html was done to support this). -.SS Local schemes: file:, about:, man: +.SS Local schemes: file:, man: While these are not necessarily \f[I]protocols\f[R], they are implemented similarly to the protocols listed above (and thus can also be replaced, if the user wishes; see below). @@ -100,11 +100,6 @@ be replaced, if the user wishes; see below). In case of directories, it shows the directory listing like the FTP protocol does. .PP -\f[CR]about:\f[R] contains informational pages about the browser. -At the time of writing, the following pages are available: -\f[CR]about:chawan\f[R], \f[CR]about:blank\f[R] and -\f[CR]about:license\f[R]. -.PP \f[CR]man:\f[R], \f[CR]man\-k:\f[R] and \f[CR]man\-l:\f[R] are wrappers around the commands \f[CR]man\f[R], \f[CR]man \-k\f[R] and \f[CR]man \-l\f[R]. @@ -114,9 +109,9 @@ A wrapper command \f[CR]mancha\f[R] also exists; this has an interface similar to \f[CR]man\f[R]. Note: this used to be based on w3mman2html.cgi, but it has been rewritten in Nim (and therefore no longer depends on Perl either). -.SS Internal schemes: cgi\-bin:, stream:, cache:, data: -Four internal protocols exist: \f[CR]cgi\-bin:\f[R], \f[CR]stream:\f[R], -\f[CR]cache:\f[R] and \f[CR]data:\f[R]. +.SS Internal schemes: cgi\-bin:, stream:, cache:, data:, about: +Five internal protocols exist: \f[CR]cgi\-bin:\f[R], \f[CR]stream:\f[R], +\f[CR]cache:\f[R], \f[CR]data:\f[R] and \f[CR]about:\f[R]. These are the basic building blocks for the implementation of every protocol mentioned above; for this reason, these can \f[I]not\f[R] be replaced, and are implemented in the main browser binary. @@ -127,32 +122,39 @@ protocols mentioned above. Local CGI scripts can also be used to implement wrappers of other programs inside Chawan (e.g.\ dictionaries). .PP -\f[CR]stream:\f[R] is used for reading in streams returned by external -programs or passed to Chawan via standard input. +\f[CR]stream:\f[R] is used for streams returned by external programs. It differs from \f[CR]cgi\-bin:\f[R] in that it does not cooperate with the external process, and that the loader does not keep track of where the stream originally comes from. Therefore it is suitable for reading in the output of mailcap entries, or for turning stdin into a URL. .PP -Since Chawan does not keep track of the origin of \f[CR]stream:\f[R] -URLs, it is not possible to reload them. -(For that matter, reloading stdin does not make much sense anyway.) +It is not possible to reload \f[CR]stream:\f[R] URLs. To support rewinding and \[lq]view source\[rq], the output of -\f[CR]stream:\f[R]\[cq]s is stored in a temporary file until the buffer -is discarded. +\f[CR]stream:\f[R]\[cq]s is stored in a cache file until the buffer is +discarded. .PP \f[CR]cache:\f[R] is not something an end user would normally see; it\[cq]s used for rewinding or re\-interpreting streams already downloaded. -Note that this is not a real cache; files are deterministically loaded -from the \[lq]cache\[rq] upon certain actions, and from the network upon -others, but neither is used as a fallback to the other. +.PP +Caching works differently than in most other browsers; files are +deterministically loaded from the cache upon certain actions, and from +the network upon others, but neither is used as a fallback to the other. .PP \f[CR]data:\f[R] decodes a data URL as defined in RFC 2397. This used to be a CGI module, but has been moved back into the loader process because these URLs can get so long that they no longer fit into the environment. +.PP +\f[CR]about:\f[R] is inside the loader to allow for an implementation of +the download list panel. +It should be turned into a CGI module once the loader gets RPC +capabilities. +.PP +The following about pages are available: \f[CR]about:chawan\f[R], +\f[CR]about:blank\f[R], \f[CR]about:license\f[R], +\f[CR]about:download\f[R]. .SS Custom protocols Chawan is protocol\-agnostic. This means that the \f[CR]cha\f[R] binary itself does not know much diff --git a/doc/config.md b/doc/config.md index b4707043..72900a1c 100644 --- a/doc/config.md +++ b/doc/config.md @@ -24,7 +24,6 @@ the search path accomodates XDG basedirs as well: 1. config file specified through -C switch -> use that 2. `$CHA_DIR` is set -> use `$CHA_DIR`/config.toml - (`$CHA_CONFIG_DIR` is a deprecated alias for `$CHA_DIR`.) 3. `$XDG_CONFIG_HOME` is set -> use `$XDG_CONFIG_HOME`/chawan/config.toml 4. ~/.config/chawan/config.toml exists -> use that 5. ~/.chawan/config.toml exists -> use that @@ -102,7 +101,7 @@ for all scripts and network requests to run to completion, while "dump" does not. This means that `true` may never exit when scripting is enabled (e.g. if a script sets `setInterval`.)<br> Piping `cha` to an external program or passing the `-d` switch has the -same effect as passing this option. +same effect as setting this option to "dump". </td> </tr> @@ -1632,18 +1631,20 @@ character. (This means that e.g. `https://` consists of four words: `https`, ### Regex handling -Regular expressions are currently handled using libregexp which is included in -QuickJS. This means that all regular expressions work as in JavaScript. +Regular expressions are currently handled using the libregexp library +from QuickJS. This means that all regular expressions work as in +JavaScript. -There are two different modes of regex preprocessing in Chawan: "search" mode, -and "match" mode. "match" mode is used for configurations (meaning in all values -in this document described as "regex"). "search" mode is used for the on-page -search function (using searchForward/isearchForward etc.) +There are two different modes of regex preprocessing in Chawan: "search" +mode and "match" mode. Match mode is used for configurations (meaning +in all values in this document described as "regex"). Search mode is +used for the on-page search function (using searchForward/isearchForward +etc.) #### Match mode -Regular expressions are assumed to be exact matches, except when they start -with a caret (^) sign or end with an unescaped dollar ($) sign. +Regular expressions are assumed to be exact matches, except when they +start with a caret (^) sign or end with an unescaped dollar ($) sign. In other words, the following transformations occur: @@ -1658,22 +1659,25 @@ Match mode has no way to toggle JavaScript regex flags like `i`. #### Search mode -For on-page search, the above transformations do not apply; the search `/abcd` -searches for the string `abcd` inside all lines. +For on-page search, the above transformations do not apply; the search +`/abcd` searches for the string `abcd` inside all lines. -"Search" mode also has some other convenience transformations: +Search mode also has some other convenience transformations (these do +not work in match mode): -* The string `\c` (backslash + lower-case c) inside a search-mode regex enables - case-insensitive matching. -* Conversely, `\C` (backslash + capital C) disables case-insensitive matching. - (Useful if you have `ignore-case` set to true, which is the default.) +* The string `\c` (backslash + lower-case c) inside a search-mode regex + enables case-insensitive matching. +* Conversely, `\C` (backslash + capital C) disables case-insensitive + matching. (Useful if you have `ignore-case` set to true, which is + the default.) * `\<` and `\>` is converted to `\b` (as in vi, grep, etc.) -Note that none of these work in "match" mode. +Like match mode, search mode operates on individual lines. This means +that search patterns do not match text wrapped over multiple lines. ### Path handling -Rules for path handling are similar to how strings in the shell are handled. +Rules for path handling are similar to how the shell handles strings. * Tilde-expansion is used to determine the user's home directory. So e.g. `~/whatever` works. @@ -1702,16 +1706,18 @@ words. Currently, these are: #### w3m word -A w3m word is a sequence of alphanumeric characters. Symbols are treated -in the same way as whitespace. +A w3m word is a sequence of alphanumeric characters. Symbols are +treated in the same way as whitespace. #### vi word -A vi word is a sequence of alphanumeric characters, OR a sequence of symbols. +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. -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: +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: ``` hello[]+{}@`! @@ -1721,8 +1727,8 @@ hello[]+{}@`! A big word is a sequence of non-whitespace characters. -It is essentially the same as a w3m word, but with symbols being defined as -non-whitespace. +It is essentially the same as a w3m word, but with symbols being defined +as non-whitespace. <!-- MANON |