From c564a74ff686e65d3cd36c3111766d7005e45356 Mon Sep 17 00:00:00 2001 From: CismonX Date: Mon, 22 Feb 2021 03:05:58 +0800 Subject: [PATCH] Add documentation for helper macros. --- doc/ctlseqs.texi | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index b252185..6382ca7 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -57,6 +57,7 @@ version. @menu * Overview:: Brief overview of ctlseqs. +* Helper Macros:: Helper macros provided by ctlseqs. * Control Sequence Matching:: Using ctlseqs for matching control sequences. * Control Sequence Reading:: Using ctlseqs for reading control sequences. * Tips:: Tips & hints for using ctlseqs. @@ -155,6 +156,49 @@ terminal emulators. @end itemize +@node Helper Macros +@chapter Helper Macros + +A helper macro in ctlseqs is a C preprocessor macro representing a control +function, which expands to a C string literal. + +@cindex List of control function types in ctlseqs helper macros +The control function can be one of the following three types: + +@itemize @bullet +@item Elements from the C0 or C1 set. +@item Control Sequences. +@item Other control functions (such as device control functions). +@end itemize + +Name of a helper macro is the function name with @code{CTLSEQS_} as prefix. +For a control function other than elements from the C0 or C1 set, the +corresponding helper macro is a function-like macro which may or may not take +arguments. + +Control sequences listed in the helper macros are primarily exerpted from +@url{https://invisible-island.net/xterm/ctlseqs/ctlseqs.html, XTerm's manual}, +which may differ across implementations. + +As ctlseqs does not currently support 8-bit controls, 2-character 7-bit codes +from the C1 set are used instead of their 1-character 8-bit representation. +For example, @code{CTLSEQS_CSI} expands to @code{"\x1b["}. + +@cindex Helper macro usage example +The following code snippet is an example usage of helper macros: + +@example +#include +#include +int main() @{ + printf(CTLSEQS_BEL); + printf(CTLSEQS_XTVERSION()); + printf(CTLSEQS_CUP("%d", "%d"), 3, 4); + fflush(stdout); +@} +@end example + + @node Control Sequence Matching @chapter Control Sequence Matching