Sync library documentation with reality.

Split mandoc_escape(3), mandoc_malloc(3), and mchars_alloc(3)
out of mandoc(3), adding lots of new information.

1 files changed, 91 insertions, 179 deletions

diff --git a/mandoc.3 b/mandoc.3
index f110a805..9a99f9c2 100644
--- a/mandoc.3
+++ b/mandoc.3
@@ -20,21 +20,11 @@
 .Os
 .Sh NAME
 .Nm mandoc ,
-.Nm mandoc_calloc ,
-.Nm mandoc_escape ,
-.Nm mandoc_malloc ,
-.Nm mandoc_realloc ,
-.Nm mandoc_strdup ,
-.Nm mandoc_strndup ,
+.Nm man_deroff ,
 .Nm man_meta ,
 .Nm man_mparse ,
 .Nm man_node ,
-.Nm mchars_alloc ,
-.Nm mchars_free ,
-.Nm mchars_num2char ,
-.Nm mchars_num2uc ,
-.Nm mchars_spec2cp ,
-.Nm mchars_spec2str ,
+.Nm mdoc_deroff ,
 .Nm mdoc_meta ,
 .Nm mdoc_node ,
 .Nm mparse_alloc ,
@@ -50,57 +40,17 @@
 .Sh LIBRARY
 .Lb libmandoc
 .Sh SYNOPSIS
+.In sys/types.h
 .In mandoc.h
 .Fd "#define ASCII_NBRSP"
 .Fd "#define ASCII_HYPH"
 .Fd "#define ASCII_BREAK"
-.Ft "void *"
-.Fo mandoc_calloc
-.Fa "size_t nmemb"
-.Fa "size_t size"
-.Fc
-.Ft "enum mandoc_esc"
-.Fo mandoc_escape
-.Fa "const char **end"
-.Fa "const char **start"
-.Fa "int *sz"
-.Fc
-.Ft "void *"
-.Fn mandoc_malloc "size_t size"
-.Ft "struct mchars *"
-.Fo mandoc_realloc
-.Fa "void *ptr"
-.Fa "size_t size"
-.Fc
-.Ft "char *"
-.Fn mandoc_strdup
-.Fn mchars_alloc "void"
-.Ft void
-.Fn mchars_free "struct mchars *p"
-.Ft char
-.Fn mchars_num2char "const char *cp" "size_t sz"
-.Ft int
-.Fn mchars_num2uc "const char *cp" "size_t sz"
-.Ft "const char *"
-.Fo mchars_spec2str
-.Fa "const struct mchars *p"
-.Fa "const char *cp"
-.Fa "size_t sz"
-.Fa "size_t *rsz"
-.Fc
-.Ft int
-.Fo mchars_spec2cp
-.Fa "const struct mchars *p"
-.Fa "const char *cp"
-.Fa "size_t sz"
-.Fc
-.Ft void
+.Ft struct mparse *
 .Fo mparse_alloc
-.Fa "enum mparset inttype"
+.Fa "int options"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"
 .Fa "char *defos"
-.Fa "int quick"
 .Fc
 .Ft void
 .Fo (*mandocmsg)
@@ -138,6 +88,7 @@
 .Fa "struct mparse *parse"
 .Fa "struct mdoc **mdoc"
 .Fa "struct man **man"
+.Fa "char **sodest"
 .Fc
 .Ft "const char *"
 .Fo mparse_strerror
@@ -147,8 +98,14 @@
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc
+.In sys/types.h
 .In mandoc.h
 .In mdoc.h
+.Ft void
+.Fo mdoc_deroff
+.Fa "char **dest"
+.Fa "const struct mdoc_node *node"
+.Fc
 .Ft "const struct mdoc_meta *"
 .Fo mdoc_meta
 .Fa "const struct mdoc *mdoc"
@@ -159,8 +116,14 @@
 .Fc
 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;
+.In sys/types.h
 .In mandoc.h
 .In man.h
+.Ft void
+.Fo man_deroff
+.Fa "char **dest"
+.Fa "const struct man_node *node"
+.Fc
 .Ft "const struct man_meta *"
 .Fo man_meta
 .Fa "const struct man *man"
@@ -215,37 +178,22 @@ or invoke
 .Fn mparse_reset
 and parse new files.
 .El
-.Pp
-The
-.Nm
-library also contains routines for translating character strings into glyphs
-.Pq see Fn mchars_alloc
-and parsing escape sequences from strings
-.Pq see Fn mandoc_escape .
 .Sh REFERENCE
 This section documents the functions, types, and variables available
 via
-.In mandoc.h .
+.In mandoc.h ,
+with the exception of those documented in
+.Xr mandoc_escape 3
+and
+.Xr mchars_alloc 3 .
 .Ss Types
 .Bl -ohang
-.It Vt "enum mandoc_esc"
-An escape sequence classification.
 .It Vt "enum mandocerr"
 A fatal error, error, or warning message during parsing.
 .It Vt "enum mandoclevel"
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.
-.It Vt "struct mchars"
-An opaque pointer to an object allowing for translation between
-character strings and glyphs.
-See
-.Fn mchars_alloc .
-.It Vt "enum mparset"
-The type of parser when reading input.
-This should usually be
-.Dv MPARSE_AUTO
-for auto-detection.
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with
@@ -261,38 +209,20 @@ messages emitted by the parser.
 .El
 .Ss Functions
 .Bl -ohang
-.It Fn mandoc_escape
-Scan an escape sequence, i.e., a character string beginning with
-.Sq \e .
-Pass a pointer to the character after the
-.Sq \e
-as
-.Va end ;
-it will be set to the supremum of the parsed escape sequence unless
-returning
-.Dv ESCAPE_ERROR ,
-in which case the string is bogus and should be
-thrown away.
-If not
-.Dv ESCAPE_ERROR
-or
-.Dv ESCAPE_IGNORE ,
-.Va start
-is set to the first relevant character of the substring (font, glyph,
-whatever) of length
-.Va sz .
-Both
-.Va start
-and
-.Va sz
-may be
-.Dv NULL .
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa mandoc.c .
+.It Fn man_deroff
+Obtain a text-only representation of a
+.Vt struct man_node ,
+including text contained in its child nodes.
+To be used on children of the pointer returned from
+.Fn man_node .
+When it is no longer needed, the pointer returned from
+.Fn man_deroff
+can be passed to
+.Xr free 3 .
 .It Fn man_meta
-Obtain the meta-data of a successful parse.
+Obtain the meta-data of a successful
+.Xr man 7
+parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
@@ -306,67 +236,29 @@ Declared in
 implemented in
 .Pa man.c .
 .It Fn man_node
-Obtain the root node of a successful parse.
+Obtain the root node of a successful
+.Xr man 7
+parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .
-.It Fn mchars_alloc
-Allocate an
-.Vt "struct mchars *"
-object for translating special characters into glyphs.
-See
-.Xr mandoc_char 7
-for an overview of special characters.
-The object must be freed with
-.Fn mchars_free .
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_free
-Free an object created with
-.Fn mchars_alloc .
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_num2char
-Convert a character index (e.g., the \eN\(aq\(aq escape) into a
-printable ASCII character.
-Returns \e0 (the nil character) if the input sequence is malformed.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_num2uc
-Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
-a Unicode codepoint.
-Returns \e0 (the nil character) if the input sequence is malformed.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_spec2cp
-Convert a special character into a valid Unicode codepoint.
-Returns \-1 on failure or a non-zero Unicode codepoint on success.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
-.It Fn mchars_spec2str
-Convert a special character into an ASCII string.
-Returns
-.Dv NULL
-on failure.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa chars.c .
+.It Fn mdoc_deroff
+Obtain a text-only representation of a
+.Vt struct mdoc_node ,
+including text contained in its child nodes.
+To be used on children of the pointer returned from
+.Fn mdoc_node .
+When it is no longer needed, the pointer returned from
+.Fn mdoc_deroff
+can be passed to
+.Xr free 3 .
 .It Fn mdoc_meta
-Obtain the meta-data of a successful parse.
+Obtain the meta-data of a successful
+.Xr mdoc
+parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
@@ -374,7 +266,9 @@ Declared in
 implemented in
 .Pa mdoc.c .
 .It Fn mdoc_node
-Obtain the root node of a successful parse.
+Obtain the root node of a successful
+.Xr mdoc
+parse.
 This may only be used on a pointer returned by
 .Fn mparse_result .
 Declared in
@@ -385,15 +279,33 @@ implemented in
 Allocate a parser.
 The arguments have the following effect:
 .Bl -tag -offset 5n -width inttype
-.It Ar inttype
-When set to
+.It Ar options
+When the
 .Dv MPARSE_MDOC
 or
-.Dv MPARSE_MAN ,
-only that parser will be used.
-With
-.Dv MPARSE_AUTO ,
-the document type will be automatically detected.
+.Dv MPARSE_MAN
+bit is set, only that parser is used.
+Otherwise, the document type is automatically detected.
+.Pp
+When the
+.Dv MPARSE_SO
+bit is set,
+.Xr roff 7
+.Ic \&so
+file inclusion requests are always honoured.
+Otherwise, if the request is the only content in an input file,
+only the file name is remembered, to be returned in the
+.Fa sodest
+argument of
+.Fn mparse_result .
+.Pp
+When the
+.Dv MPARSE_QUICK
+bit is set, parsing is aborted after the NAME section.
+This is for example useful in
+.Xr makewhatis 8
+.Fl Q
+to quickly build minimal databases.
 .It Ar wlevel
 Can be set to
 .Dv MANDOCLEVEL_FATAL ,
@@ -414,9 +326,6 @@ macro, overriding the
 .Dv OSNAME
 preprocessor definition and the results of
 .Xr uname 3 .
-.It Ar quick
-When set, parsing is aborted after the NAME section.
-This is for example useful to quickly build minimal databases.
 .El
 .Pp
 The same parser may be used for multiple files so long as
@@ -486,7 +395,7 @@ i.e., those where
 .Fn mparse_readfd
 returned less than MANDOCLEVEL_FATAL
 .Pc
-should invoke this function, in which case one of the two pointers will
+should invoke this function, in which case one of the three pointers will
 be filled in.
 Declared in
 .In mandoc.h ,
@@ -540,6 +449,8 @@ The following non-printing characters may be embedded in text strings:
 A non-breaking space character.
 .It Dv ASCII_HYPH
 A soft hyphen.
+.It Dv ASCII_BREAK
+A breakable zero-width space.
 .El
 .Pp
 Escape characters are also passed verbatim into text strings.
@@ -547,11 +458,9 @@ An escape character is a sequence of characters beginning with the
 backslash
 .Pq Sq \e .
 To construct human-readable text, these should be intercepted with
-.Fn mandoc_escape
-and converted with one of
-.Fn mchars_num2char ,
-.Fn mchars_spec2str ,
-and so on.
+.Xr mandoc_escape 3
+and converted with one the functions described in
+.Xr mchars_alloc 3 .
 .Ss Man Abstract Syntax Tree
 This AST is governed by the ontological rules dictated in
 .Xr man 7
@@ -596,7 +505,7 @@ where capitalised non-terminals represent nodes.
 .El
 .Pp
 The only elements capable of nesting other elements are those with
-next-lint scope as documented in
+next-line scope as documented in
 .Xr man 7 .
 .Ss Mdoc Abstract Syntax Tree
 This AST is governed by the ontological
@@ -732,10 +641,13 @@ front-ends to
 .Xr mandoc 1
 are unable to render them in any meaningful way.
 Furthermore, behaviour when encountering badly-nested blocks is not
-consistent across troff implementations, especially when using  multiple
+consistent across troff implementations, especially when using multiple
 levels of badly-nested blocks.
 .Sh SEE ALSO
 .Xr mandoc 1 ,
+.Xr mandoc_escape 3 ,
+.Xr mandoc_malloc 3 ,
+.Xr mchars_alloc 3 ,
 .Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,