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 | |
| parent | e925590a56998942c8e4d2ce3c56665719f75947 (diff) | |
| download | chawan-5361862155de853f905cb25a2377f6503912f0da.tar.gz | |
Update docs
| -rw-r--r-- | Makefile | 39 | ||||
| -rw-r--r-- | README.md | 11 | ||||
| -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 |
13 files changed, 274 insertions, 29 deletions
@@ -1,3 +1,4 @@ +# Public variables. NIM ?= nim NIMC ?= $(NIM) c OBJDIR ?= .obj @@ -7,16 +8,25 @@ PREFIX ?= /usr/local MANPREFIX ?= $(PREFIX)/share/man MANPREFIX1 ?= $(MANPREFIX)/man1 MANPREFIX5 ?= $(MANPREFIX)/man5 +MANPREFIX7 ?= $(MANPREFIX)/man7 TARGET ?= release -# This must be single-quoted, because it is not a real shell substitution. + +# Note: this is not a real shell substitution. # The default setting is at {the binary's path}/../libexec/chawan. # You may override it with any path if your system does not have a libexec -# directory, but make sure to surround it with quotes if it contains spaces. -# (This way, the cha binary can be directly executed without installation.) -LIBEXECDIR ?= '$$CHA_BIN_DIR/../libexec/chawan' +# directory. +# (This way, `cha' can be directly executed without installation.) +LIBEXECDIR ?= \$$CHA_BIN_DIR/../libexec/chawan + +# I won't take this from the environment for obvious reasons. Please override it +# in the make command if you must, or (preferably) fix your environment so it's +# not needed. +DANGER_DISABLE_SANDBOX = 0 + +# Private variables. # If overridden, take libexecdir that was specified. # Otherwise, just install to libexec/chawan. -ifeq ($(LIBEXECDIR),'$$CHA_BIN_DIR/../libexec/chawan') +ifeq ($(LIBEXECDIR),\$$CHA_BIN_DIR/../libexec/chawan) LIBEXECDIR_CHAWAN = "$(DESTDIR)$(PREFIX)/libexec/chawan" else LIBEXECDIR_CHAWAN = $(LIBEXECDIR) @@ -29,11 +39,6 @@ OUTDIR_LIBEXEC = $(OUTDIR_TARGET)/libexec/chawan OUTDIR_CGI_BIN = $(OUTDIR_LIBEXEC)/cgi-bin OUTDIR_MAN = $(OUTDIR_TARGET)/share/man -# I won't take this from the environment for obvious reasons. Please override it -# in the make command if you must, or (preferably) fix your environment so it's -# not needed. -DANGER_DISABLE_SANDBOX = 0 - # Nim compiler flags ifeq ($(TARGET),debug) FLAGS += -d:debug --debugger:native @@ -171,6 +176,9 @@ $(OBJDIR)/man/cha-%.md: doc/%.md md2manpreproc doc/cha-%.5: $(OBJDIR)/man/cha-%.md pandoc --standalone --to man $< -o $@ +doc/cha-%.7: $(OBJDIR)/man/cha-%.md + pandoc --standalone --to man $< -o $@ + .PHONY: clean clean: rm -rf "$(OBJDIR)/$(TARGET)" @@ -182,10 +190,10 @@ distclean: clean manpages1 = cha.1 mancha.1 manpages5 = cha-config.5 cha-mailcap.5 cha-mime.types.5 cha-localcgi.5 \ - cha-urimethodmap.5 cha-protocols.5 cha-api.5 cha-troubleshooting.5 \ - cha-image.5 + cha-urimethodmap.5 +manpages7 = cha-protocols.7 cha-api.7 cha-troubleshooting.7 cha-image.7 cha-css.7 -manpages = $(manpages1) $(manpages5) +manpages = $(manpages1) $(manpages5) $(manpages7) .PHONY: manpage manpage: $(manpages:%=doc/%) @@ -214,6 +222,8 @@ install: for f in $(manpages1); do install -m644 "doc/$$f" "$(DESTDIR)$(MANPREFIX1)"; done mkdir -p "$(DESTDIR)$(MANPREFIX5)" for f in $(manpages5); do install -m644 "doc/$$f" "$(DESTDIR)$(MANPREFIX5)"; done + mkdir -p "$(DESTDIR)$(MANPREFIX7)" + for f in $(manpages7); do install -m644 "doc/$$f" "$(DESTDIR)$(MANPREFIX7)"; done .PHONY: uninstall uninstall: @@ -235,7 +245,10 @@ uninstall: # urldec is just a symlink to urlenc rm -f $(LIBEXECDIR_CHAWAN)/urldec rmdir $(LIBEXECDIR_CHAWAN) || true + for f in $(manpages7); do rm -f "$(DESTDIR)$(MANPREFIX7)/$$f"; done for f in $(manpages5); do rm -f "$(DESTDIR)$(MANPREFIX5)/$$f"; done +# moved to section 7 + for f in cha-protocols.7 cha-api.7 cha-troubleshooting.7 cha-image.7; do rm -f "$(DESTDIR)$(MANPREFIX5)/$ff"; done for f in $(manpages1); do rm -f "$(DESTDIR)$(MANPREFIX1)/$$f"; done .PHONY: submodule @@ -62,20 +62,21 @@ Currently implemented features are: * multi-processing, incremental loading of documents * multi-charset, double-width aware text display (but no bi-di yet) * HTML5 support, forms, cookies -* CSS-based layout engine: supports flow layout, table layout, flexbox layout +* [CSS](doc/css.md)-based layout engine: supports flow layout, table + layout, flexbox layout * user-programmable keybindings (defaults are vi(m)-like) * basic JavaScript support in documents (disabled by default for security reasons) +* inline image support with sixel/kitty protocols (disabled by default; + see [doc/image.md](doc/image.md) on how to enable) * supports several [protocols](doc/protocols.md): HTTP(S), FTP, Gopher, Gemini, Finger, etc. * [user-defined](doc/urimethodmap.md) protocols and [file formats](doc/mailcap.md) * markdown viewer, man page viewer -* sixel/kitty image support (disabled by default; see - [doc/image.md](doc/image.md) on how to enable) * mouse support -* syscall sandboxing on FreeBSD, OpenBSD and Linux (through capsicum, pledge - and seccomp-bpf) +* syscall filter based sandboxing on FreeBSD, OpenBSD and Linux (through + capsicum, pledge and seccomp-bpf) * bookmarks ...with a lot more [planned](todo). 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 |