update documentation

README.md

@@ -10,8 +10,7 @@ ctlseqs
 =======
 
   The ctlseqs library provides C API for handling ECMA-35/ECMA-48 compatible
-  control functions, which is commonly used for communication between terminal
-  emulators and text-based programs.
+  control functions.
 
   ctlseqs is free software, licensed under the terms of the GNU General Public
   License, either version 3, or any later version of the license. See COPYING
@@ -19,8 +18,10 @@ ctlseqs
 
   See INSTALL.md for instructions on how to build and install ctlseqs.
 
-  Visit the [project homepage] for documentation, mailing lists, releases,
-  and everything else about ctlseqs.
+  See `info ctlseqs` for documentation.
+
+  Visit the [project homepage] for online documentation, mailing lists,
+  releases, and everything else about ctlseqs.
 
 
 <!-- Reference Links -->

doc/ctlseqs.texi

@@ -419,16 +419,18 @@ ctlseqs, but can also be considered as a crude alternative of
 @node API Reference
 @appendix API Reference
 
-This section contains a complete list of functions exposed by ctlseqs, which is
-meant for a TL;DR purpose. See the corresponding man(3) pages for details.
+@set url-man-pages https://nongnu.org/ctlseqs/man-pages/man3
 
-Initialize matcher:
+This section contains a complete list of functions exposed by ctlseqs.  See the
+corresponding man pages for details.
+
+@url{@value{url-man-pages}/ctlseqs_matcher_init.3.html, Initialize matcher}:
 
 @example
 struct ctlseqs_matcher *ctlseqs_matcher_init(void);
 @end example
 
-Configure matcher:
+@url{@value{url-man-pages}/ctlseqs_matcher_config.3.html, Configure matcher}:
 
 @example
 int ctlseqs_matcher_config(
@@ -437,7 +439,7 @@ int ctlseqs_matcher_config(
 );
 @end example
 
-Match string:
+@url{@value{url-man-pages}/ctlseqs_match.3.html, Match string}:
 
 @example
 ssize_t ctlseqs_match(
@@ -448,7 +450,7 @@ ssize_t ctlseqs_match(
 );
 @end example
 
-Destroy matcher:
+@url{@value{url-man-pages}/ctlseqs_matcher_free.3.html, Destroy matcher}:
 
 @example
 void ctlseqs_matcher_free(
@@ -456,13 +458,13 @@ void ctlseqs_matcher_free(
 );
 @end example
 
-Initialize reader:
+@url{@value{url-man-pages}/ctlseqs_reader_init.3.html, Initialize reader}:
 
 @example
 struct ctlseqs_reader *ctlseqs_reader_init(void);
 @end example
 
-Configure reader:
+@url{@value{url-man-pages}/ctlseqs_reader_config.3.html, Configure reader}:
 
 @example
 int ctlseqs_reader_config(
@@ -471,7 +473,7 @@ int ctlseqs_reader_config(
 );
 @end example
 
-Read and match:
+@url{@value{url-man-pages}/ctlseqs_read.3.html, Read and match}:
 
 @example
 ssize_t ctlseqs_read(
@@ -481,7 +483,7 @@ ssize_t ctlseqs_read(
 );
 @end example
 
-Purge reader:
+@url{@value{url-man-pages}/ctlseqs_purge.3.html, Purge reader}:
 
 @example
 void ctlseqs_purge(
@@ -490,7 +492,7 @@ void ctlseqs_purge(
 );
 @end example
 
-Destroy reader:
+@url{@value{url-man-pages}/ctlseqs_reader_free.3.html, Destroy reader}:
 
 @example
 void ctlseqs_reader_free(

include/ctlseqs.h

@@ -327,8 +327,8 @@
 // Restore DEC Private Mode Values
 #define CTLSEQS_XTRESTORE(is)                      CTLSEQS_CSI "?" is "r"
 // Change Attributes in Rectangular Area
-#define CTLSEQS_DECCARA(t, l, b, r, i)             \
-    CTLSEQS_CSI t ";" l ";" b ";" r ";" i "$r"
+#define CTLSEQS_DECCARA(t, l, b, r, is)            \
+    CTLSEQS_CSI t ";" l ";" b ";" r ";" is "$r"
 // Save cursor
 #define CTLSEQS_SCOSC()                            CTLSEQS_CSI "s"
 // Set left and right margins
@@ -342,8 +342,8 @@
 // Set warning-bell volume
 #define CTLSEQS_DECSWBV(i)                         CTLSEQS_CSI i " t"
 // Reverse Attributes in Rectangular Area
-#define CTLSEQS_DECRARA(t, l, b, r, i)             \
-    CTLSEQS_CSI t ";" l ";" b ";" r ";" i "$t"
+#define CTLSEQS_DECRARA(t, l, b, r, is)            \
+    CTLSEQS_CSI t ";" l ";" b ";" r ";" is "$t"
 // Restore cursor
 #define CTLSEQS_SCORC()                            CTLSEQS_CSI "u"
 // Set margin-bell volume

man/ctlseqs_match.3

@@ -35,7 +35,8 @@ Argument
 is the buffer where the function stores match results.
 If
 .I str
-contains a control sequence (or part of a control sequence), the length of the sequence is stored in
+contains a control sequence (or part of a control sequence), the length of the
+sequence is stored in
 .I buffer
 at offset 0, and the pointer to the starting ESC character at offset 1.
 Otherwise,
@@ -44,11 +45,13 @@ value at offset 0 and 1 is unspecified.
 .SS Match results
 If the control sequence matches a pattern in
 .IR matcher ,
-a group of values is extracted from the sequence for each placeholder, and stored into
+a group of values is extracted from the sequence for each placeholder, and
+stored into
 .I result
 sequentially, starting at offset 2.
 .PP
-An extracted value can be either a string (not guaranteed to be NUL-terminated), or an unsigned integer, as in
+An extracted value can be either a string (not guaranteed to be
+NUL-terminated), or an unsigned integer, as in
 .BR "union ctlseqs_value" :
 .PP
 .nf
@@ -63,7 +66,8 @@ union ctlseqs_value {
 .in
 .fi
 .PP
-A group can contain one or multiple values, depending on different placeholders:
+A group can contain one or multiple values, depending on different
+placeholders:
 .TP
 .BR CTLSEQS_PH_NUM ", " CTLSEQS_PH_HEXNUM
 The integer is stored in field
@@ -75,7 +79,8 @@ The number of integers is stored in field
 followed by that many integers stored in field
 .IR num .
 .TP
-.BR CTLSEQS_PH_STR ", " CTLSEQS_PH_CMDSTR ", " CTLSEQS_PH_CSI_PARAM ", " CTLSEQS_PH_CSI_INTMD ", " CTLSEQS_PH_CHRSTR
+.BR CTLSEQS_PH_STR ", " CTLSEQS_PH_CMDSTR ", " CTLSEQS_PH_CSI_PARAM ", " \
+    CTLSEQS_PH_CSI_INTMD ", " CTLSEQS_PH_CHRSTR
 The length of the string is stored in field
 .IR len ,
 followed by a pointer to the first character of the string stored in field
@@ -95,7 +100,8 @@ A valid control sequence is found, but fails to match any pattern in
 .IR matcher .
 .TP
 .B CTLSEQS_PARTIAL
-The string can be recognized as part of a control sequence, but is not yet terminated.
+The string can be recognized as part of a control sequence, but is not yet
+terminated.
 .TP
 .B CTLSEQS_NOSEQ
 No valid control sequence is found in the given string.
@@ -103,8 +109,9 @@ No valid control sequence is found in the given string.
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_matcher_config (3)

man/ctlseqs_matcher_config.3

@@ -36,7 +36,8 @@ struct ctlseqs_matcher_options {
 .PP
 Field
 .I patterns
-is an array of pointers to NUL-terminated strings, each of which represents a pattern of control sequences.
+is an array of pointers to NUL-terminated strings, each of which represents a
+pattern of control sequences.
 .PP
 Field
 .I npatterns
@@ -47,7 +48,9 @@ Multiple calls on the same
 .I matcher
 will discard all data from previous calls.
 .SS Placeholders
-A pattern may contain zero to multiple placeholders, where a placeholder indicates that when matching a string against the pattern, the value at the placeholder's location should conform to its rules.
+A pattern may contain zero to multiple placeholders, where a placeholder
+indicates that when matching a string against the pattern, the value at the
+placeholder's location should conform to its rules.
 .PP
 Currently supported placeholders:
 .TP
@@ -55,7 +58,8 @@ Currently supported placeholders:
 An unsigned integer.
 .TP
 .B CTLSEQS_PH_NUMS
-Multiple unsigned integers separated with the semicolon ASCII character (value 0x3b).
+Multiple unsigned integers separated with the semicolon ASCII character
+(value 0x3b).
 .TP
 .B CTLSEQS_PH_STR
 A string of printable characters.
@@ -86,16 +90,18 @@ Fails to allocate sufficient memory.
 .SH NOTES
 Any value in
 .I patterns
-must correspond to an ECMA-35/ECMA-48 conformant escape sequence, and should also be supported by the matcher.
-Otherwise, function behaviour is undefined.
+must correspond to an ECMA-35/ECMA-48 conformant escape sequence, and should
+also be supported by the matcher.  Otherwise, function behaviour is undefined.
 .PP
 Currently supported escape sequences:
 .TP
 .B CSI [param...] [intmd...] final
-Parameter bytes are of range 0x30\(ti0x3f, intermediate bytes 0x20\(ti0x2f, and final byte 0x40\(ti0x7e.
+Parameter bytes are of range 0x30\(ti0x3f, intermediate bytes 0x20\(ti0x2f, and
+final byte 0x40\(ti0x7e.
 .TP
 .B (APC|DCS|OSC|PM) [cmdstr] ST
-Command string consists of bytes of printable characters and characters of range 0x08\(ti0x0d.
+Command string consists of bytes of printable characters and characters of
+range 0x08\(ti0x0d.
 .TP
 .B (SS2|SS3) ch
 The byte following a single-shift should be a printable character.
@@ -106,8 +112,9 @@ Character string can be any bit combination which does not represent SOS or ST.
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_match (3),

man/ctlseqs_matcher_free.3

@@ -29,8 +29,9 @@ This function has no return values.
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_matcher_init (3)

man/ctlseqs_matcher_init.3

@@ -27,8 +27,9 @@ If the function fails to allocate sufficient memory, returns NULL.
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_matcher_config (3),

man/ctlseqs_purge.3

@@ -35,8 +35,9 @@ whose future completion is not desired.
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_read (3)

man/ctlseqs_read.3

@@ -33,7 +33,8 @@ is enabled, also save those values when the match is successful.
 .PP
 Argument
 .I timeout
-is the maximum duration of time (in milliseconds) to wait until any data can be read.
+is the maximum duration of time (in milliseconds) to wait until any data can be
+read.
 If
 .I timeout
 is -1, the function blocks indefinitely. If option
@@ -60,11 +61,13 @@ A control sequence is successfully read, but fails to match any pattern in
 .IR matcher .
 .TP
 .B CTLSEQS_PARTIAL
-Data is read successfully and can be recognized as part of a control sequence, but is not yet terminated.
-Partial sequence is not consumed from the read buffer.
+Data is read successfully and can be recognized as part of a control sequence,
+but is not yet terminated.  Partial sequence is not consumed from the read
+buffer.
 .TP
 .B CTLSEQS_NOSEQ
-Data is read successfully, but cannot be recognized as a valid control sequence.
+Data is read successfully, but cannot be recognized as a valid control
+sequence.
 .TP
 .B CTLSEQS_TIMEOUT
 The specified
@@ -83,13 +86,15 @@ End-of-file is encountered, and no data is read.
 An unexpected error occurs during a system call within the function.
 .TP
 .B CTLSEQS_INTR
-A system call within the function is interrupted by a signal, and no data is read.
+A system call within the function is interrupted by a signal, and no data is
+read.
 .
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_match (3),

man/ctlseqs_reader_config.3

@@ -38,13 +38,15 @@ struct ctlseqs_reader_options {
 .PP
 Field
 .I result
-is the pointer to the buffer where the values extracted from the matching sequence of
+is the pointer to the buffer where the values extracted from the matching
+sequence of
 .B ctlseqs_read
 will be stored.
 .PP
 Field
 .I maxlen
-specifies the maximum possible length (in bytes) of control sequence to be read.
+specifies the maximum possible length (in bytes) of control sequence to be
+read.
 .PP
 Field
 .I fd
@@ -84,13 +86,15 @@ Fails to allocate sufficient memory.
 .B CTLSEQS_ERROR
 Attempts to change
 .I maxlen
-value, but data in the internal read buffer will be lost due to truncation, if done so.
+value, but data in the internal read buffer will be lost due to truncation, if
+done so.
 .
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_match (3),

man/ctlseqs_reader_free.3

@@ -29,8 +29,9 @@ This function has no return values.
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_reader_init (3)

man/ctlseqs_reader_init.3

@@ -27,8 +27,9 @@ If the function fails to allocate sufficient memory, returns NULL.
 .SH COPYRIGHT
 Copyright (c)  2020,2021  CismonX <admin@cismon.net>
 .PP
-Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
-This file is offered as-is, without any warranty.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty, provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any warranty.
 .
 .SH SEE ALSO
 .BR ctlseqs_reader_config (3),