From 4e72aeb8d7431b9b18406fdc9f700e3beeb3205f Mon Sep 17 00:00:00 2001
From: CismonX <admin@cismon.net>
Date: Fri, 12 Nov 2021 17:42:39 +0800
Subject: [PATCH] Update documentation.

---
 doc/ctlseqs.texi | 51 +++++++++++++++++++++++++-----------------------
 1 file changed, 27 insertions(+), 24 deletions(-)

diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi
index 644d825..0fb61b6 100644
--- a/doc/ctlseqs.texi
+++ b/doc/ctlseqs.texi
@@ -65,6 +65,7 @@ version.
 
 Appendices
 * API Reference::                   C API reference for ctlseqs.
+* General Index::                   Index of general concepts of ctlseqs.
 * GNU Free Documentation License::  Copying conditions of this manual.
 @end menu
 
@@ -173,7 +174,7 @@ printf(CTLSEQS_XTVERSION());
 printf(CTLSEQS_CUP("%d", "%d"), 3, 4);
 @end example
 
-Rememeber that the standard output stream is line buffered within a terminal.
+Keep in mind that the standard output stream is line buffered in a terminal.
 Either @code{fflush(stdout)} after printing, or disable output buffering with
 @code{setvbuf(stdout, NULL, _IONBF, 0)}.
 
@@ -191,7 +192,9 @@ if (0 == strcmp(str, CTLSEQS_XTVERSION())) @{
     // ...
 @} else if (2 == sscanf(str, CTLSEQS_CUP("%d", "%d"), &row, &col)) @{
     // ...
-@} else /* ... */
+@} else @{
+    // ...
+@}
 @end example
 
 However, as the number of possible matches grows, this naive implementation
@@ -369,9 +372,9 @@ the first character of the string stored in field @code{str}.
 The following code is an example of invoking @code{ctlseqs_match}:
 
 @example
+union ctlseqs_value     buffer[4];
 struct ctlseqs_matcher *matcher /* = ... */;
 // ...
-union ctlseqs_value buffer[4];
 char const *str     = "foo" CTLSEQS_CUP("2", "4");
 size_t      str_len = sizeof("foo" CTLSEQS_CUP("2", "4")) - 1;
 ssize_t     result  = ctlseqs_match(matcher, str, str_len, buffer);
@@ -402,7 +405,16 @@ unspecified which one of them will be the final match result.
 @node Example Programs
 @chapter Example Programs
 
-There are a few example programs which may shed some light on using ctlseqs.
+In the source code repository of ctlseqs, there are a few programs that
+demonstrates the basic usage of ctlseqs.
+
+See ``example/sixdraw.c'' for a simple TUI program in which you can draw lines
+on the terminal window using a mouse.
+
+See ``tests/tcsgrep.c'' for a program which parses control functions into
+human-readable text. It was originally written as a tool to run tests for
+ctlseqs, but can also be considered as a crude alternative of
+@url{https://www.gnu.org/software/teseq/, GNU Teseq}.
 
 @node API Reference
 @appendix API Reference
@@ -413,15 +425,13 @@ meant for a TL;DR purpose. See the corresponding man(3) pages for details.
 Initialize matcher:
 
 @example
-struct ctlseqs_matcher *
-ctlseqs_matcher_init(void);
+struct ctlseqs_matcher *ctlseqs_matcher_init(void);
 @end example
 
 Configure matcher:
 
 @example
-int
-ctlseqs_matcher_config(
+int ctlseqs_matcher_config(
     struct ctlseqs_matcher               *matcher,
     struct ctlseqs_matcher_options const *options
 );
@@ -430,8 +440,7 @@ ctlseqs_matcher_config(
 Match string:
 
 @example
-ssize_t
-ctlseqs_match(
+ssize_t ctlseqs_match(
     struct ctlseqs_reader const *matcher,
     char                  const *str,
     size_t                       str_len,
@@ -442,8 +451,7 @@ ctlseqs_match(
 Destroy matcher:
 
 @example
-void
-ctlseqs_matcher_free(
+void ctlseqs_matcher_free(
     struct ctlseqs_matcher *matcher
 );
 @end example
@@ -451,15 +459,13 @@ ctlseqs_matcher_free(
 Initialize reader:
 
 @example
-struct ctlseqs_reader *
-ctlseqs_reader_init(void);
+struct ctlseqs_reader *ctlseqs_reader_init(void);
 @end example
 
 Configure reader:
 
 @example
-int
-ctlseqs_reader_config(
+int ctlseqs_reader_config(
     struct ctlseqs_reader               *reader,
     struct ctlseqs_reader_options const *options
 );
@@ -468,8 +474,7 @@ ctlseqs_reader_config(
 Read and match:
 
 @example
-ssize_t
-ctlseqs_read(
+ssize_t ctlseqs_read(
     struct ctlseqs_reader        *reader,
     struct ctlseqs_matcher const *matcher,
     int                           timeout
@@ -479,8 +484,7 @@ ctlseqs_read(
 Purge reader:
 
 @example
-void
-ctlseqs_purge(
+void ctlseqs_purge(
     struct ctlseqs_reader *reader,
     size_t                 nbytes
 );
@@ -489,15 +493,14 @@ ctlseqs_purge(
 Destroy reader:
 
 @example
-void
-ctlseqs_reader_free(
+void ctlseqs_reader_free(
     struct ctlseqs_reader *reader
 );
 @end example
 
 
-@node Indices
-@appendix Indices
+@node General Index
+@appendix General Index
 
 @printindex cp