aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorbptato <nincsnevem662@gmail.com>2025-01-15 22:34:47 +0100
committerbptato <nincsnevem662@gmail.com>2025-01-15 22:34:47 +0100
commit5361862155de853f905cb25a2377f6503912f0da (patch)
treebbcf7318b35aeed2dd774dc89880b4187bf1fd7e
parente925590a56998942c8e4d2ce3c56665719f75947 (diff)
downloadchawan-5361862155de853f905cb25a2377f6503912f0da.tar.gz
Update docs
-rw-r--r--Makefile39
-rw-r--r--README.md11
-rw-r--r--doc/build.md4
-rw-r--r--doc/cha-api.7 (renamed from doc/cha-api.5)0
-rw-r--r--doc/cha-css.7117
-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.14
-rw-r--r--doc/css.md116
-rw-r--r--doc/image.md2
-rw-r--r--doc/protocols.md2
-rw-r--r--doc/troubleshooting.md2
13 files changed, 274 insertions, 29 deletions
diff --git a/Makefile b/Makefile
index 82165728..c9460d9b 100644
--- a/Makefile
+++ b/Makefile
@@ -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
diff --git a/README.md b/README.md
index b7aca1c2..e19ddf4b 100644
--- a/README.md
+++ b/README.md
@@ -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?
diff --git a/doc/cha.1 b/doc/cha.1
index 6f506bf5..338ea0b5 100644
--- a/doc/cha.1
+++ b/doc/cha.1
@@ -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