.\" Automatically generated by Pandoc 3.7.0.1
.\"
.TH "CHA-TERMINAL" "7"
.SH Chawan terminal compatibility
Chawan does not use termcap, terminfo, or ncurses; it relies solely on
built\-in terminal handling routines, mostly inspired by notcurses.
.SS XTerm compatibility
In general, Chawan assumes an XTerm\-compatible environment where XTerm
means the current XTerm version as developed and maintained by Thomas
E.\ Dickey.
This means that Chawan is compatible with any given terminal if:
.IP \(bu 2
the terminal is actually compatible with XTerm, OR
.IP \(bu 2
the terminal isn\(cqt compatible with XTerm, but reports its
capabilities via terminal queries correctly, OR
.IP \(bu 2
the terminal isn\(cqt compatible with XTerm, but its \f[CR]TERM\f[R]
value is hardcoded in Chawan.
.PP
Terminals pretending to be XTerm (\f[CR]TERM=xterm\f[R]) which are not
actually XTerm might malfunction.
.PP
(In practice, I have tested dozens of terminal emulators and haven\(cqt
encountered any major issues; in all likelihood, yours will work too.
If it doesn\(cqt, please \c
.UR https://todo.sr.ht/~bptato/chawan
open a ticket
.UE \c
\&.)
.SS Queries
Queries are preferred to hardcoded terminal descriptions because they
are forward\-compatible.
On startup, Chawan queries:
.IP \(bu 2
Whether the terminal has true color, with XTGETTCAP rgb.
.IP \(bu 2
The default background, foreground, and 16 ANSI(\-ish) colors with
\f[CR]OSC 1 0 ; ? ST\f[R], \f[CR]OSC 1 1 ; ? ST\f[R], and
\f[CR]OSC 4 ; {0..15} ; ? ST\f[R].
.IP \(bu 2
Whether the terminal can use the Kitty image protocol, by sending an
incorrectly encoded image and listening for an error.
.IP \(bu 2
The number of Sixel color registers (\f[CR]CSI ? 1 ; 1 ; 0 $\f[R]).
.IP \(bu 2
Text area, cell, and window size using \f[CR]CSI 1 4 t\f[R],
\f[CR]CSI 1 6 t\f[R], \f[CR]CSI 1 8 t\f[R].
(Cell size, \f[CR]1 6\f[R], beats the other two as it is more reliable.)
.IP \(bu 2
Primary device attributes.
.PP
Primary device attributes (henceforth DA1) are queried last, and most
terminals respond to this, so Chawan should never hang on startup.
If it \f[I]isn\(cqt\f[R] implemented (as on the FreeBSD console), the
user can hit any key to break out of the state machine and set
\f[CR]display.query\-da1 = false\f[R] as instructed by the browser.
On known terminals with this issue which set \f[CR]TERM\f[R] correctly,
DA1 is omitted.
.PP
Some terminals bleed the APC sequence used to recognize kitty image
support.
If the terminal also supports the alternate screen (ti/smcup), the
sequence may end up inside the shell prompt.
On known terminals with this issue which set \f[CR]TERM\f[R] correctly,
the kitty query is omitted.
.SS Ancient terminals
Pre\-ECMA\-48 terminals are generally not expected to work.
.PP
There is some degree of ADM\-3A support, tested in Kragen Javier
Sitaker\(cqs \f[I]admu\f[R] emulator.
The VT100 has also been tested in Lars Brinkhoff\(cqs
\f[I]terminal\-simulator\f[R].
.PP
Patches for other terminals (hardware or software alike) are welcome.
.SS Ancient character encodings
For ASCII\-only terminals, don\(cqt forget to
\f[CR]export LC_ALL=C\f[R].
For terminals supporting other legacy encodings, you may also have some
luck with \f[CR]language.charset\f[R], such as
\f[CR]export LC_ALL=ja_JP.ISO\-2022\-JP\f[R].
.PP
Note that Chawan uses its own encoding library instead of the
notoriously broken C locale facility, and the two sets of supported
charsets may not fully overlap.
You can test whether a charset is supported using
\f[CR]cha \-O {charset name} \-V\f[R].
.SS See also
\f[B]cha\f[R](1)