aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDaniel Eklöf <daniel@ekloef.se>2021-02-23 08:32:04 +0000
committerDaniel Eklöf <daniel@ekloef.se>2021-02-23 08:32:04 +0000
commit313431800e75785d597ee1a13319d2eb6b98648d (patch)
treed3940b3a641841883d5d76d2651f8d0fe479233e /doc
parentMerge branch 'dracula-theme' (diff)
parentdoc: ctlseq: replace ‘ST’ with the actual characters, ‘\E\’ (diff)
Merge branch 'document-control-sequences'
Closes #235
Diffstat (limited to 'doc')
-rw-r--r--doc/foot-ctlseqs.5.scd628
-rw-r--r--doc/meson.build3
2 files changed, 630 insertions, 1 deletions
diff --git a/doc/foot-ctlseqs.5.scd b/doc/foot-ctlseqs.5.scd
new file mode 100644
index 00000000..49187eb2
--- /dev/null
+++ b/doc/foot-ctlseqs.5.scd
@@ -0,0 +1,628 @@
+foot-ctlseqs(5)
+
+# DESCRIPTION
+
+This document describes all the control sequences supported by foot.
+
+- Control characters
+- Sequences beginning with ESC
+- CSI - Control Sequence Introducer
+ - SGR
+ - Indexed and RGB colors (256-color palette and 24-bit colors)
+ - Private modes
+ - Window manipulation
+ - Other
+- OSC - Operating System Command
+- DCS - Device Control String
+
+# Control characters
+
+[[ *Sequence*
+:[ *Name*
+:[ *Description*
+| \\a
+: BEL
+: Depends on what *bell* in *foot.ini*(5) is set to.
+| \\b
+: BS
+: Backspace; move the cursor left one step. Wrap if _bw_ is enabled.
+| \\t
+: HT
+: Horizontal tab; move the cursor to the next tab stop.
+| \\n
+: LF
+: Line feed; move the cursor down one step, or scroll content up if
+ at the bottom line.
+| \\v
+: VT
+: Vertical tab; identical to _LF_.
+| \\f
+: FF
+: Form feed; identical to _LF_.
+| \\r
+: CR
+: Carriage ret; move the cursor to the leftmost column.
+| \\x0E
+: SS0
+: Shift out; select the _G1_ character set.
+| \\x0F
+: SS1
+: Shift in; select the _G0_ character set.
+
+# Sequences beginning with ESC
+
+Note: this table excludes sequences where ESC is part of a 7-bit
+equivalent to 8-bit C1 controls.
+
+[[ *Sequence*
+:[ *Name*
+:[ *Origin*
+:[ *Description*
+| \\E 7
+: DECSC
+: VT100
+: Save cursor position.
+| \\E 8
+: DECRC
+: VT100
+: Restore cursor position.
+| \\E c
+: RIS
+: VT100
+: Reset terminal to initial state.
+| \\E D
+: IND
+: VT100
+: Line feed; move the cursor down one step, or scroll content up if
+ at the bottom margin.
+| \\E E
+: NEL
+: VT100
+: Next line; move the cursor down one step, and to the first
+ column. Content is scrolled up if at the bottom line.
+| \\E H
+: HTS
+: VT100
+: Set one horizontal tab stop at the current position.
+| \\E M
+: RI
+: VT100
+: Reverse index; move the cursor up one step, or scroll content down
+ if at the top margin.
+| \\E N
+: SS2
+: VT220
+: Single shift G2; select the _G2_ character set.
+| \\E O
+: SS3
+: VT220
+: Single shift G3; select the _G3_ character set.
+| \\E =
+: DECKPAM
+: VT100
+: Switch keypad to _application_ mode.
+| \\E >
+: DECKPNM
+: VT100
+: Switch keypad to _numeric_ mode.
+| \\E ( _C_
+: SCS
+: VT100
+: Designate G0 character set. Supported values for _C_ are: *0* (DEC
+ Special Character and Line Drawing Set), and *B* (USASCII).
+| \\E ) _C_
+: SCS
+: VT100
+: Designate G1 character set. Same supported values for _C_ as in _G0_.
+| \\E \* _C_
+: SCS
+: VT220
+: Designate G2 character set. Same supported values for _C_ as in _G0_.
+| \\E + _C_
+: SCS
+: VT220
+: Designate G3 character set. Same supported values for _C_ as in _G0_.
+
+# CSI
+
+All sequences begin with *\\E[*, sometimes abbreviated _CSI_. Spaces
+are used in the sequence strings to make them easier to read, but are
+not actually part of the string. I.e. *\\E[ 1 m* is really *\\E[1m*.
+
+## SGR
+
+All SGR sequences are on the form *\\E[ <N> m*, where _N_ is a decimal
+number - the _parameter_. Multiple parameters can be combined in a
+single CSI sequence by separating them with semicolons: *\\E[ 1;2;3
+m*.
+
+[[ *Sequence*
+:[ *Description*
+| 0
+: Reset all attributes
+| 1
+: Bold
+| 2
+: Dim
+| 3
+: Italic
+| 4
+: Underline
+| 5
+: Blink
+| 7
+: Reverse video; swap foreground and background colors
+| 8
+: Conceal; text is not visible, but is copiable
+| 9
+: Crossed-out/strike
+| 22
+: Disable *bold* and *dim*
+| 23
+: Disable italic
+| 24
+: Disable underline
+| 25
+: Disable blink
+| 27
+: Disable reverse video
+| 28
+: Disable conceal
+| 29
+: Disable crossed-out
+| 30-37
+: Select foreground color (using *regularN* in *foot.ini*(5))
+| 38
+: See "indexed and RGB colors" below
+| 39
+: Use the default foreground color (*foreground* in *foot.ini*(5))
+| 40-47
+: Select background color (using *regularN* in *foot.ini*(5))
+| 48
+: See "indexed and RGB colors" below
+| 49
+: Use the default background color (*background* in *foot.ini*(5))
+| 90-97
+: Select foreground color (using *brightN* in *foot.ini*(5))
+| 100-107
+: Select background color (using *brightN* in *foot.ini*(5))
+
+## Indexed and RGB colors (256-color palette and 24-bit colors)
+
+Foot supports both the new sub-parameter based variants, and the older
+parameter based variants for setting foreground and background colors.
+
+Indexed colors:
+
+- *\\E[ 38:5:<idx> m*
+- *\\E[ 38;5;<idx> m*
+
+RGB colors:
+
+- *\\E[ 38:2:<cs>:<r>:<g>:<b> m*
+- *\\E[ 38:2:<r>:<g>:<b> m*
+- *\\E[ 38;2;<r>;<g>;<b> m*
+
+The first variant is the "correct" one (and foot also recognizes, but
+ignores, the optional _tolerance_ parameters).
+
+The second one is allowed since many programs "forget" the color space
+ID, _cs_.
+
+The sub-parameter based variants are preferred, and what foot's
+terminfo uses.
+
+## Private Modes
+
+There are several Boolean-like "modes" that affect certain aspects
+of the terminal's behavior. These modes can be manipulated with the
+following 4 escape sequences:
+
+[[ *Sequence*
+:[ *Name*
+:[ *Description*
+| \\E[ ? _Pm_ h
+: DECSET
+: Enable private mode
+| \\E[ ? _Pm_ l
+: DECRST
+: Disable private mode
+| \\E[ ? _Pm_ s
+: XTSAVE
+: Save private mode
+| \\E[ ? _Pm_ r
+: XTRESTORE
+: Restore private mode
+
+
+The _Pm_ parameter in the above sequences denotes a numerical ID
+that corresponds to one of the following modes:
+
+[[ *Parameter*
+:[ *Origin*
+:[ *Description*
+| 1
+: VT100
+: Cursor keys mode (DECCKM)
+| 5
+: VT100
+: Reverse video (DECSCNM)
+| 6
+: VT100
+: Origin mode (DECOM)
+| 7
+: VT100
+: Auto-wrap mode (DECAWM)
+| 12
+: AT&T 610
+: Cursor blink
+| 25
+: VT220
+: Cursor visibility (DECTCEM)
+| 45
+: xterm
+: Reverse-wraparound mode
+| 47
+: xterm
+: Same as 1047 (see below)
+| 1000
+: xterm
+: Send mouse x/y on button press/release
+| 1001
+: xterm
+: Use hilite mouse tracking
+| 1002
+: xterm
+: Use cell motion mouse tracking
+| 1003
+: xterm
+: Use all motion mouse tracking
+| 1004
+: xterm
+: Send FocusIn/FocusOut events
+| 1006
+: xterm
+: SGR mouse mode
+| 1007
+: xterm
+: Alternate scroll mode
+| 1015
+: urxvt
+: urxvt mouse mode
+| 1034
+: xterm
+: 8-bit Meta mode
+| 1035
+: xterm
+: Num Lock modifier (see xterm numLock option)
+| 1036
+: xterm
+: Send ESC when Meta modifies a key (see xterm metaSendsEscape option)
+| 1042
+: xterm
+: Perform action for BEL character (see *bell* in *foot.ini*(5))
+| 1047
+: xterm
+: Use alternate screen buffer
+| 1048
+: xterm
+: Save/restore cursor (DECSET=save, DECRST=restore)
+| 1049
+: xterm
+: Equivalent to 1048 and 1047 combined
+| 2004
+: xterm
+: Wrap pasted text with start/end delimiters (bracketed paste mode)
+| 737769
+: foot
+: Input Method Editor (IME) mode
+
+## Window manipulation
+
+Foot implements a sub-set of XTerm's (originally dtterm's) window
+manipulation sequences. The generic format is:
+
+*\\E[ *_Ps_* ; *_Ps_* ; *_Ps_* t*
+
+[[ *Parameter 1*
+:[ *Parameter 2*
+:[ *Description*
+| 11
+: -
+: Report if window is iconified. Foot always reports *1* - not iconified.
+| 13
+: -
+: Report window position. Foot always reports (0,0), due to Wayland
+ limitations.
+| 13
+: 2
+: Report text area position. Foot always reports (0,0) due to Wayland
+ limitations.
+| 14
+: -
+: Report text area size, in pixels. Foot reports the grid size,
+ excluding the margins.
+| 14
+: 2
+: Report window size, in pixels. Foot reports the grid size plus the
+ margins.
+| 15
+: -
+: Report the screen size, in pixels.
+| 16
+: -
+: Report the cell size, in pixels.
+| 18
+: -
+: Report text area size, in characters.
+| 19
+: -
+: Report screen size, in characters.
+| 22
+: -
+: Push window title+icon. Foot does not support pushing the icon.
+| 22
+: 2
+: Push window title.
+| 23
+: -
+: Pop window title+icon. Foot does not support popping the icon.
+| 23
+: 2
+: Pop window title.
+
+## Other
+
+[[ *Parameter*
+:[ *Name*
+:[ *Origin*
+:[ *Description*
+| \\E[ _Ps_ c
+: DA
+: VT100
+: Send primary device attributes. Foot responds with "I'm a VT220 with
+ sixel and ANSI color support".
+| \\E[ _Ps_ A
+: CUU
+: VT100
+: Cursor up - move cursor up _Ps_ times.
+| \\E[ _Ps_ B
+: CUD
+: VT100
+: Cursor down - move cursor down _Ps_ times.
+| \\E[ _Ps_ C
+: CUF
+: VT100
+: Cursor forward - move cursor to the right _Ps_ times.
+| \\E[ _Ps_ D
+: CUB
+: VT100
+: Cursor backward - move cursor to the left _Ps_ times.
+| \\E[ _Ps_ g
+: TBC
+: VT100
+: Tab clear. _Ps_=0 -> clear current column. _Ps_=3 -> clear all.
+| \\E[ _Ps_ ; _Ps_ f
+: HVP
+: VT100
+: Horizontal and vertical position - move cursor to _row_ ; _column_.
+| \\E[ _Ps_ ; _Ps_ H
+: CUP
+: VT100
+: Cursor position - move cursor to _row_ ; _column_.
+| \\E[ _Ps_ J
+: ED
+: VT100
+: Erase in display. _Ps_=0 -> below cursor. _Ps_=1 -> above
+| \\E[ _Ps_ K
+: EL
+: VT100
+: Erase in line. _Ps_=0 -> right of cursor. _Ps_=1 -> left of
+ cursor. _Ps_=2 -> all.
+| \\E[ _Pm_ h
+: SM
+: VT100
+: Set mode. _Pm_=4 -> enable IRM (insert mode). All other values of
+ _Pm_ are unsupported.
+| \\E[ _Pm_ l
+: RM
+: VT100
+: Reset mode. _Pm_=4 -> disable IRM (insert mode). All other values of
+ _Pm_ are unsupported.
+| \\E[ _Ps_ n
+: DSR
+: VT100
+: Device status report. _Ps_=5 -> device status. _Ps_=6 -> cursor
+ position.
+| \\E[ _Ps_ L
+: IL
+: VT220
+: Insert _Ps_ lines.
+| \\E[ _Ps_ M
+: DL
+: VT220
+: Delete _Ps_ lines.
+| \\E[ _Ps_ P
+: DCH
+: VT220
+: Delete _Ps_ characters.
+| \\E[ _Ps_ @
+: ICH
+: VT220
+: Insert _Ps_ blank characters.
+| \\E[ _Ps_ X
+: ECH
+: VT220
+: Erase _Ps_ characters.
+| \\E[ > c
+: DA2
+: VT220
+: Send secondary device attributes. Foot responds with "I'm a VT220
+ and here's my version number".
+| \\E[ ! p
+: DECSTR
+: VT220
+: Soft terminal reset.
+| \\E[ ? _Ps_ $ p
+: DECRQM
+: VT320
+: Request DEC private mode.
+| \\E[ _Ps_ T
+: SD
+: VT420
+: Scroll down _Ps_ lines.
+| \\E[ s
+: SCOSC
+: SCO, VT510
+: Save cursor position.
+| \\E[ u
+: SCORC
+: SCO, VT510
+: Restore cursor position.
+| \\E[ _Ps_ SP q
+: DECSCUSR
+: VT510
+: Set cursor style. In foot, _Ps_=0 means "use style from foot.ini".
+| \\E[ = _Ps_ c
+: DA3
+: VT510
+: send tertiary device attributes. Foot responds with "FOOT", in
+ hexadecimal.
+| \\E[ _Pm_ d
+: VPA
+: ECMA-48
+: Line position absolute - move cursor to line _Pm_.
+| \\E[ _Pm_ e
+: VPR
+: ECMA-48
+: Line position relative - move cursor down _Pm_ lines.
+| \\E[ _Pm_ a
+: HPR
+: ECMA-48
+: Character position relative - move cursor to the right _Pm_ times.
+| \\E[ _Ps_ E
+: CNL
+: ECMA-48
+: Cursor next line - move the cursor down _Ps_ times.
+| \\E[ _Ps_ F
+: CPL
+: ECMA-48
+: Cursor preceding line - move the cursor up _Ps_ times.
+| \\E[ _Pm_ `
+: HPA
+: ECMA-48
+: Character position absolute - move cursor to column _Pm_.
+| \\E[ _Ps_ G
+: CHA
+: ECMA-48
+: Cursor character absolute - move cursor to column _Ps_.
+ cursor. _Ps_=2 -> all. _Ps_=3 -> saved lines.
+| \\E[ _Ps_ S
+: SU
+: ECMA-48
+: Scroll up _Ps_ lines.
+| \\E[ _Ps_ I
+: CHT
+: ECMA-48
+: Cursor forward tabulation _Ps_ tab stops.
+| \\E[ _Ps_ Z
+: CBT
+: ECMA-48
+: Cursor backward tabulation _Ps_ tab stops.
+| \\E[ _Ps_ b
+: REP
+: ECMA-48
+: Repeat the preceding printable character _Ps_ times.
+| \\E[ ? _Pi_ ; _Pa_ ; _Pv_ S
+: XTSMGRAPHICS
+: xterm
+: Set or request sixel attributes.
+
+# OSC
+
+All _OSC_ sequences begin with *\\E]*, sometimes abbreviated _OSC_.
+
+[[ *Sequence*
+:[ *Origin*
+:[ *Description*
+| \\E] 0 ; _Pt_ \\E\\
+: xterm
+: Set window icon and title to _Pt_ (foot does not support setting the
+ icon)
+| \\E] 2 ; _Pt_ \\E\\
+: xterm
+: Set window title to _Pt_
+| \\E] 4 ; _c_ ; _spec_ \\E\\
+: xterm
+: Change color number _c_ to _spec_, where _spec_ is a color in
+ *XParseColor* format. foot only supports RGB colors; either
+ *rgb:<red>/<green>/<blue>*, or the legacy format (*#rgb*).
+| \\E] 7 ; _Uri_ \\E\\
+: iTerm2
+: Update the terminal's current working directory. Newly spawned
+ terminals will launch in this directory. _Uri_ must be on the format
+ *file://<hostname>/<path>*. *hostname* must refer to your local host.
+| \\E] 8 ; _id_=*ID* ; _Uri_ \\E\\
+: VTE+iTerm2
+: Hyperlink (a.k.a HTML-like anchors). _id_ is optional; if assigned,
+ all URIs with the same *ID* will be treated as a single
+ hyperlink. An empty URI closes the hyperlink.
+| \\E] 10 ; _spec_ \\E\\
+: xterm
+: Change the default foreground color to _spec_, a color in
+ *XParseColor* format.
+| \\E] 11 ; _spec_ \\E\\
+: xterm
+: Change the default background color to _spec_, a color in
+ *XParseColor* format.
+| \\E] 12 ; _spec_ \\E\\
+: xterm
+: Change cursor color to _spec_, a color in *XParseColor* format.
+| \\E] 52 ; _Pc_ ; ? \\E\\
+: xterm
+: Send clipboard data. _Pc_ can be either *c*, *s* or *p*. *c* uses
+ the clipboard as source, and *s* and *p* uses the primary
+ selection. The response is *OSC 52 ; Pc ; <base64-encoded data>*,
+ where _Pc_ indicates the source used.
+| \\E] 52 ; _Pc_ ; _Pd_ \\E\\
+: xterm
+: Copy _Pd_ (base64 encoded text) to the clipboard. _Pc_ indicates the
+ target: *c* targets the clipboard and *s* and *p* the primary
+ selection.
+| \\E] 104 [; _c_] \\E\\
+: xterm
+: Reset color number _c_, or all colors (excluding the default
+ foreground/background colors) if _c_ is omitted.
+| \\E] 110 \\E\\
+: xterm
+: Reset default foreground color
+| \\E] 111 \\E\\
+: xterm
+: Reset default background color
+| \\E] 112 \\E\\
+: xterm
+: Reset cursor color
+| \\E] 555 \\E\\
+: foot
+: Flash the entire terminal (foot extension)
+| \\E] 777;notify;_title_;_msg_ \\E\\
+: urxvt
+: Desktop notification, uses *notify* in *foot.ini*(5).
+
+# DCS
+
+All _DCS_ sequences begin with *\\EP* (sometimes abbreviated _DCS_),
+and are terminated by *\\E\\* (ST).
+
+[[ *Sequence*
+:[ *Description*
+| \\EP q <sixel data> \\E\\
+: Emit a sixel image at the current cursor position
+| \\EP = 1 s \\E\\
+: Begin application synchronized updates
+| \\EP = 2 s \\E\\
+: End application synchronized updates
+
+# FOOTNOTE
+
+Foot does not support 8-bit control characters ("CC1").
diff --git a/doc/meson.build b/doc/meson.build
index 1f017db4..4d5c7118 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -5,7 +5,8 @@ scdoc_prog = find_program(scdoc.get_pkgconfig_variable('scdoc'), native: true)
foreach man_src : [{'name': 'foot', 'section' : 1},
{'name': 'foot.ini', 'section': 5},
- {'name': 'footclient', 'section': 1}]
+ {'name': 'footclient', 'section': 1},
+ {'name': 'foot-ctlseqs', 'section': 5}]
name = man_src['name']
section = man_src['section']
out = '@0@.@1@'.format(name, section)