.\" Automatically generated by Pandoc 3.6.4
.\"
.TH "cha\-terminal" "7" "" "" "Chawan terminal compatibility"
.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\[cq]t compatible with XTerm, but reports its
capabilities via terminal queries correctly, OR
.IP \[bu] 2
the terminal isn\[cq]t 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\[cq]t
encountered any major issues; in all likelihood, yours will work too.
Still, if it doesn\[cq]t, please \c
.UR https://tickets.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
The maximum Sixel image dimensions (\f[CR]CSI ? 2 ; 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\[cq]t\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\[cq]s \f[CR]admu\f[R] emulator.
However, a real ADM\-3A would likely be confused by non\-ASCII
characters.
.PP
Patches for other terminals (hardware or software alike) are welcome.
.SS See also
\f[B]cha\f[R](1)