Add documentation for control sequence matcher.

doc/ctlseqs.texi

@@ -64,10 +64,8 @@ version.
 * Example Programs::           Example programs using ctlseqs.
 
 Appendices
-
 * API Reference::                   C API reference for ctlseqs.
 * GNU Free Documentation License::  Copying conditions of this manual.
-
 @end menu
 
 
@@ -218,7 +216,73 @@ if (0 == strcmp(str, CTLSEQS_XTVERSION())) @{
 However, as the number of possible matches grows, this naive implementation
 becomes less efficient and harder to maintain.
 
-The control sequence matcher provided by ctlseqs aims at solving such problems.
+Such problems can be easily solved by using the control sequence matcher
+provided by ctlseqs.
+
+The @code{struct ctlseqs_matcher *} is a pointer to an opaque type which
+represents an instance of control sequence matcher. Before using, the matcher
+should be initialized with @code{ctlseqs_matcher_init}. After using, it should
+be deallocated with @code{ctlseqs_matcher_free}.
+
+@cindex Control sequence matcher initialization example
+@example
+struct ctlseqs_matcher *matcher = ctlseqs_matcher_init();
+// ...
+ctlseqs_matcher_free(matcher);
+@end example
+
+On rare occurences when ctlseqs fail to allocate enough memory, function
+@code{ctlseqs_matcher_init} may return @code{NULL}. However, it is okay to pass
+null pointers to @code{ctlseqs_matcher_free}, which in turn does nothing.
+
+@menu
+* Matcher Configuration::  Configuring a control sequence matcher
+* Matching String::        Matching a string with control sequence matcher
+@end menu
+
+
+@node Matcher Configuration
+@section Matcher Configuration
+
+Matcher configuration consists of two parts: the number of matching patterns,
+and the patterns themselves. Invoke function @code{ctlseqs_matcher_config} to
+configure a matcher.
+
+@cindex Control sequence matcher configuration example
+@example
+struct ctlseqs_matcher *matcher /* = ... */;
+char const *patterns[] = @{
+    CTLSEQS_XTVERSION(),
+    CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM),
+    // ...
+@};
+struct ctlseqs_matcher_options options = @{
+    .patterns  = patterns,
+    .npatterns = sizeof(patterns) / sizeof(char const *),
+@};
+int result = ctlseqs_matcher_config(matcher, &options);
+// ...
+@end example
+
+Each invocation of @code{ctlseqs_matcher_config} on the same matcher overwrites
+the data generated from the last invocation. Upon success, the function returns
+@code{CTLSEQS_OK}. If the function fails to allocate enough memory, returns
+@code{CTLSEQS_NOMEM}.
+
+If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
+invalid, function behaviour is undefined. See @ref{Patterns} for details.
+
+@menu
+* Patterns::  Supported control squence pattern formats
+@end menu
+
+
+@node Patterns
+@subsection Patterns
+
+
+@node Matching String
+@section Matching String
 
 
 @node Control Sequence Reading