diff options
Diffstat (limited to 'doc/css.md')
| -rw-r--r-- | doc/css.md | 116 |
1 files changed, 116 insertions, 0 deletions
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 --> |