Update docs

1 files changed, 117 insertions, 0 deletions

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)