aboutsummaryrefslogtreecommitdiffstats
path: root/doc/css.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/css.md')
-rw-r--r--doc/css.md116
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 -->