diff options
| author | bptato <nincsnevem662@gmail.com> | 2025-01-15 22:34:47 +0100 |
|---|---|---|
| committer | bptato <nincsnevem662@gmail.com> | 2025-01-15 22:34:47 +0100 |
| commit | 5361862155de853f905cb25a2377f6503912f0da (patch) | |
| tree | bbcf7318b35aeed2dd774dc89880b4187bf1fd7e /doc | |
| parent | e925590a56998942c8e4d2ce3c56665719f75947 (diff) | |
| download | chawan-5361862155de853f905cb25a2377f6503912f0da.tar.gz | |
Update docs
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.md | 4 | ||||
| -rw-r--r-- | doc/cha-api.7 (renamed from doc/cha-api.5) | 0 | ||||
| -rw-r--r-- | doc/cha-css.7 | 117 | ||||
| -rw-r--r-- | doc/cha-image.7 (renamed from doc/cha-image.5) | 2 | ||||
| -rw-r--r-- | doc/cha-protocols.7 (renamed from doc/cha-protocols.5) | 2 | ||||
| -rw-r--r-- | doc/cha-troubleshooting.7 (renamed from doc/cha-troubleshooting.5) | 2 | ||||
| -rw-r--r-- | doc/cha.1 | 4 | ||||
| -rw-r--r-- | doc/css.md | 116 | ||||
| -rw-r--r-- | doc/image.md | 2 | ||||
| -rw-r--r-- | doc/protocols.md | 2 | ||||
| -rw-r--r-- | doc/troubleshooting.md | 2 |
11 files changed, 242 insertions, 11 deletions
diff --git a/doc/build.md b/doc/build.md index be32ffe0..35d8f74b 100644 --- a/doc/build.md +++ b/doc/build.md @@ -37,9 +37,7 @@ also override them by setting an environment variable with the same name. * `CURLLIBNAME`: Change the name of the libcurl shared object file. * `LIBEXECDIR`: Path to your libexec directory; by default, it is relative to wherever the binary is placed when it is executed. (i.e. - after installation it would resolve to `/usr/local/libexec`.)<BR> - WARNING: Unlike other path names, this must be quoted if your path contains - spaces. + after installation it would resolve to `/usr/local/libexec`.) * `DANGER_DISABLE_SANDBOX`: Set it to 1 to forcibly disable syscall filtering. Note that this is *not* taken from the environment variables, and you must use it like `make DANGER_DISABLE_SANDBOX=1`. diff --git a/doc/cha-api.5 b/doc/cha-api.7 index 86906378..86906378 100644 --- a/doc/cha-api.5 +++ b/doc/cha-api.7 diff --git a/doc/cha-css.7 b/doc/cha-css.7 new file mode 100644 index 00000000..9e1b5d69 --- /dev/null +++ b/doc/cha-css.7 @@ -0,0 +1,117 @@ +.\" Automatically generated by Pandoc 3.6.1 +.\" +.TH "cha\-css" "7" "" "" "Image support in Chawan" +.SH CSS in Chawan +This document describes some proprietary CSS extensions supported by +Chawan, as well as its intentional deviations from standards. +.PP +If you discover a deviation that is not covered by this document, then +please open a ticket at \c +.UR https://todo.sr.ht/~bptato/chawan +.UE \c +\&. +.SS Proprietary extensions +.IP \[bu] 2 +\f[CR]text\-align\f[R] accepts the values \f[CR]\-cha\-center\f[R], +\f[CR]\-cha\-left\f[R], and \f[CR]\-cha\-right\f[R] to support the HTML +\f[CR]<center>\f[R], \f[CR]<div align=left>\f[R] and +\f[CR]<div align=right>\f[R] elements. +(Analogous to \f[CR]\-moz\-center\f[R] etc.) +.IP \[bu] 2 +Properties with a \f[CR]<color>\f[R] value accept the function +\f[CR]\-cha\-ansi()\f[R], which takes one parameter that is either: +.IP \[bu] 2 +An 8\-bit integer, indicating a color value as set by XTerm\[cq]s +indexed color feature. +.IP \[bu] 2 +One of the strings \[lq]black\[rq], \[lq]red\[rq], \[lq]green\[rq], +\[lq]yellow\[rq], \[lq]blue\[rq], \[lq]magenta\[rq], \[lq]cyan\[rq], +\[lq]white\[rq] for an ANSI color, possibly prefixed by the string +\[lq]bright\-\[rq] to indicate an aixterm 16\-color value. +.PP +The actual palette in use is specified by the user/terminal. +.IP \[bu] 2 +\f[CR]text\-decoration\f[R] accepts the keyword +\f[CR]\-cha\-reverse\f[R], which sets the \f[I]reverse video\f[R] +parameter on the text. +(This is used by the UA style sheet to highlight text in +\f[CR]<code>\f[R] tags.) +.IP \[bu] 2 +\f[CR]text\-transform\f[R] accepts the keyword +\f[CR]\-cha\-half\-width\f[R], which has the opposite effect as +\f[CR]full\-width\f[R]. +This can be used in user style sheets to compress distracting ruby text: +\f[CR]rt{text\-transform: \-cha\-half\-width}\f[R]. +Characters without half\-width counterparts are left intact, except +hiragana is treated as katakana. +.IP \[bu] 2 +The \f[CR]\-cha\-colspan\f[R] and \f[CR]\-cha\-rowspan\f[R] properties +have the same effect as the \f[CR]colspan\f[R] and \f[CR]rowspan\f[R] +attributes on tables. +.IP \[bu] 2 +The \f[CR]\-cha\-first\-node\f[R] and \f[CR]\-cha\-last\-node\f[R] +selectors apply to elements that have no preceding/subsequent sibling +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].) +.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 +screen. +.SS User agent style sheet +The user agent style sheet is a combination of the styles suggested by +the HTML standard and a CSS port of w3m\[cq]s rendering. +In general, faithfulness to w3m is preferred over the standard, unless +it breaks existing websites. +.PP +Link colors differ depending on the terminal\[cq]s color scheme. +.SS Sizing and positioning +Layout is performed on a finite canvas of coordinates represented by a +32\-bit fixed\-point number with 6 bits of precision. +After layout, these positions are divided by the cell width and/or +height, with the fractional part truncated. +(This is subject to change.) +.PP +In case of Kitty images, the fractional part is preserved, and is used +as an in\-cell offset. +.PP +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. +This does not apply to blockified inline boxes. +.PP +When calculating clip boxes (\f[CR]overflow: hidden\f[R] or +\f[CR]clip\f[R]), the clip box\[cq]s offset is floored, and its size is +ceiled to the nearest cell\[cq]s boundaries. +This means that \[lq]width: 1px; overflow: hidden\[rq] will still +display the first character of a text box. +.SS Scroll bars +Chawan does not have scroll bars, as they would complicate on\-page +navigation and would not work in dump mode. +Instead, the \[lq]overflow\-x/y\[rq] properties are handled as follows. +.IP "1." 3 +If \f[CR]overflow\f[R] is \f[CR]auto\f[R] or \f[CR]scroll\f[R], and the +intrinsic minimum size of the box is greater than its specified size, +then the former overrides the latter. +.IP "2." 3 +Content that spills out of a scroll container on the X axis is +displayed, while content that spills out of a scroll container on the Y +axis is clipped. +.SS Color correction +Some authors only specify one of the foreground or the background color, +assuming a black\-on\-white canvas. +The \f[CR]display.minimum\-contrast\f[R] option adjusts the foreground +color so that text remains readable even if the terminal background does +not match this expectation. +(The exact algorithm is unspecified and subject to change.) +.PP +This unfortunately breaks spoiler mechanisms that rely on \[lq]black on +black\[rq] text not being visible. +The issue disappears when \f[CR]visibility: hidden\f[R] is applied to +the text as well. +.SS See also +\f[B]cha\f[R](1) diff --git a/doc/cha-image.5 b/doc/cha-image.7 index ed4c2ffe..3b726418 100644 --- a/doc/cha-image.5 +++ b/doc/cha-image.7 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.6.1 .\" -.TH "cha\-image" "5" "" "" "Image support in Chawan" +.TH "cha\-image" "7" "" "" "Image support in Chawan" .SH Inline images On terminals that support images, Chawan can display various bit\-mapped image formats. diff --git a/doc/cha-protocols.5 b/doc/cha-protocols.7 index 66876a95..b388681a 100644 --- a/doc/cha-protocols.5 +++ b/doc/cha-protocols.7 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.6.1 .\" -.TH "cha\-protocols" "5" "" "" "Protocol support in Chawan" +.TH "cha\-protocols" "7" "" "" "Protocol support in Chawan" .SH Protocols Chawan supports downloading resources from various protocols: HTTP, FTP, Gopher, Gemini, and Finger. diff --git a/doc/cha-troubleshooting.5 b/doc/cha-troubleshooting.7 index 45921b37..0e04b37b 100644 --- a/doc/cha-troubleshooting.5 +++ b/doc/cha-troubleshooting.7 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.6.1 .\" -.TH "cha\-troubleshooting" "5" "" "" "Troubleshooting Chawan" +.TH "cha\-troubleshooting" "7" "" "" "Troubleshooting Chawan" .SH Troubleshooting Chawan This document lists common problems you may run into when using Chawan. .SS I can\[cq]t select/copy text with my mouse? @@ -140,6 +140,6 @@ Configuration options are described in \fBcha-config\fR(5). .SH SEE ALSO \fBmancha\fR(1), \fBcha-mailcap\fR(5), \fBcha-mime.types\fR(5), \fBcha-config\fR(5), .br -\fBcha-localcgi\fR(5), \fBcha-urimethodmap\fR(5), \fBcha-protocols\fR(5), +\fBcha-localcgi\fR(5), \fBcha-urimethodmap\fR(5), \fBcha-protocols\fR(7), .br -\fBcha-image\fR(5), \fBcha-troubleshooting\fR(5) +\fBcha-image\fR(7), \fBcha-css\fR(7), \fBcha-troubleshooting\fR(7) diff --git a/doc/css.md b/doc/css.md new file mode 100644 index 00000000..1d3feaea --- /dev/null +++ b/doc/css.md @@ -0,0 +1,116 @@ +<!-- MANON +% cha-css(7) | Image support in Chawan +MANOFF --> + +# CSS in Chawan + +This document describes some proprietary CSS extensions supported by +Chawan, as well as its intentional deviations from standards. + +If you discover a deviation that is not covered by this document, then +please open a ticket at <https://todo.sr.ht/~bptato/chawan>. + +## Proprietary extensions + +* `text-align` accepts the values `-cha-center`, `-cha-left`, and + `-cha-right` to support the HTML `<center>`, `<div align=left>` + and `<div align=right>` elements. (Analogous to `-moz-center` etc.) + +* Properties with a `<color>` value accept the function `-cha-ansi()`, + which takes one parameter that is either: + + - An 8-bit integer, indicating a color value as set by XTerm's + indexed color feature. + - One of the strings "black", "red", "green", "yellow", "blue", + "magenta", "cyan", "white" for an ANSI color, possibly + prefixed by the string "bright-" to indicate an aixterm + 16-color value. + + The actual palette in use is specified by the user/terminal. + +* `text-decoration` accepts the keyword `-cha-reverse`, which sets + the *reverse video* parameter on the text. (This is used by the UA + style sheet to highlight text in `<code>` tags.) + +* `text-transform` accepts the keyword `-cha-half-width`, which has the + opposite effect as `full-width`.<br> + This can be used in user style sheets to compress distracting ruby + text: `rt{text-transform: -cha-half-width}`. Characters without + half-width counterparts are left intact, except hiragana is treated as + katakana. + +* The `-cha-colspan` and `-cha-rowspan` properties have the same effect + as the `colspan` and `rowspan` attributes on tables. + +* The `-cha-first-node` and `-cha-last-node` selectors apply to elements + that have no preceding/subsequent sibling node that is either an + element node or a text node with non-whitespace contents. (Modeled + after `-moz-first-node` and `-moz-last-node`.) + +## 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 screen. + +### User agent style sheet + +The user agent style sheet is a combination of the styles suggested by +the HTML standard and a CSS port of w3m's rendering. In general, +faithfulness to w3m is preferred over the standard, unless it breaks +existing websites. + +Link colors differ depending on the terminal's color scheme. + +### Sizing and positioning + +Layout is performed on a finite canvas of coordinates represented by a +32-bit fixed-point number with 6 bits of precision. After layout, these +positions are divided by the cell width and/or height, with the +fractional part truncated. (This is subject to change.) + +In case of Kitty images, the fractional part is preserved, and is used +as an in-cell offset. + +The lengths `1em` and `1ch` compute to the cell height and cell width +respectively. + +In outer inline boxes (`inline-block`, `inline-flex`), margins and +padding that are smaller than one cell (on the respective axis) are +ignored. This does not apply to blockified inline boxes. + +When calculating clip boxes (`overflow: hidden` or `clip`), the clip +box's offset is floored, and its size is ceiled to the nearest cell's +boundaries. This means that "width: 1px; overflow: hidden" will still +display the first character of a text box. + +### Scroll bars + +Chawan does not have scroll bars, as they would complicate on-page +navigation and would not work in dump mode. Instead, the "overflow-x/y" +properties are handled as follows. + +1. If `overflow` is `auto` or `scroll`, and the intrinsic minimum size + of the box is greater than its specified size, then the former + overrides the latter. +2. Content that spills out of a scroll container on the X axis is + displayed, while content that spills out of a scroll container on the + Y axis is clipped. + +### Color correction + +Some authors only specify one of the foreground or the background color, +assuming a black-on-white canvas. The `display.minimum-contrast` option +adjusts the foreground color so that text remains readable even if the +terminal background does not match this expectation. (The exact +algorithm is unspecified and subject to change.) + +This unfortunately breaks spoiler mechanisms that rely on "black on +black" text not being visible. The issue disappears when `visibility: +hidden` is applied to the text as well. + +<!-- MANON + +## See also + +**cha**(1) +MANOFF --> diff --git a/doc/image.md b/doc/image.md index cad44a9d..e2665f73 100644 --- a/doc/image.md +++ b/doc/image.md @@ -1,5 +1,5 @@ <!-- MANON -% cha-image(5) | Image support in Chawan +% cha-image(7) | Image support in Chawan MANOFF --> # Inline images diff --git a/doc/protocols.md b/doc/protocols.md index 4b3064eb..e927d01e 100644 --- a/doc/protocols.md +++ b/doc/protocols.md @@ -1,5 +1,5 @@ <!-- MANON -% cha-protocols(5) | Protocol support in Chawan +% cha-protocols(7) | Protocol support in Chawan MANOFF --> # Protocols diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md index baf8feaf..6fce6fe7 100644 --- a/doc/troubleshooting.md +++ b/doc/troubleshooting.md @@ -1,5 +1,5 @@ <!-- MANON -% cha-troubleshooting(5) | Troubleshooting Chawan +% cha-troubleshooting(7) | Troubleshooting Chawan MANOFF --> # Troubleshooting Chawan |