Clean-up: new-sentence, new-line for mdoc.3.

Clean-up: removed CAVEATS section (this should be either in the TODO
file or in mdoc.7 documenting mandoc incompatibilities).

Clean-up: alpha-ordered `Nm' and section headers.

1 files changed, 59 insertions, 105 deletions

diff --git a/mdoc.3 b/mdoc.3
index 68fcc7e2..845faac6 100644
--- a/mdoc.3
+++ b/mdoc.3
@@ -17,45 +17,41 @@
 .Dd $Mdocdate$
 .Dt MDOC 3
 .Os
-.\" SECTION
 .Sh NAME
 .Nm mdoc_alloc ,
-.Nm mdoc_parseln ,
 .Nm mdoc_endparse ,
-.Nm mdoc_node ,
-.Nm mdoc_meta ,
 .Nm mdoc_free ,
+.Nm mdoc_meta ,
+.Nm mdoc_node ,
+.Nm mdoc_parseln ,
 .Nm mdoc_reset
 .Nd mdoc macro compiler library
-.\" SECTION
 .Sh SYNOPSIS
+.In mandoc.h
 .In mdoc.h
 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"
-.Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
+.Fn mdoc_alloc "void *data" "int pflags" "mandocmsg msgs"
 .Ft int
-.Fn mdoc_reset "struct mdoc *mdoc"
+.Fn mdoc_endparse "struct mdoc *mdoc"
 .Ft void
 .Fn mdoc_free "struct mdoc *mdoc"
-.Ft int
-.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
-.Ft "const struct mdoc_node *"
-.Fn mdoc_node "const struct mdoc *mdoc"
 .Ft "const struct mdoc_meta *"
 .Fn mdoc_meta "const struct mdoc *mdoc"
+.Ft "const struct mdoc_node *"
+.Fn mdoc_node "const struct mdoc *mdoc"
 .Ft int
-.Fn mdoc_endparse "struct mdoc *mdoc"
-.\" SECTION
+.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
+.Ft int
+.Fn mdoc_reset "struct mdoc *mdoc"
 .Sh DESCRIPTION
 The
 .Nm mdoc
 library parses lines of
 .Xr mdoc 7
-input (and
-.Em only
-mdoc) into an abstract syntax tree (AST).
-.\" PARAGRAPH
+input
+into an abstract syntax tree (AST).
 .Pp
 In general, applications initiate a parsing sequence with
 .Fn mdoc_alloc ,
@@ -72,20 +68,20 @@ then free all allocated memory with
 The
 .Fn mdoc_reset
 function may be used in order to reset the parser for another input
-sequence.  See the
+sequence.
+See the
 .Sx EXAMPLES
-section for a full example.
-.\" PARAGRAPH
+section for a simple example.
 .Pp
 This section further defines the
 .Sx Types ,
 .Sx Functions
 and
 .Sx Variables
-available to programmers.  Following that, the
+available to programmers.
+Following that, the
 .Sx Abstract Syntax Tree
 section documents the output tree.
-.\" SUBSECTION
 .Ss Types
 Both functions (see
 .Sx Functions )
@@ -93,30 +89,27 @@ and variables (see
 .Sx Variables )
 may use the following types:
 .Bl -ohang
-.\" LIST-ITEM
 .It Vt struct mdoc
 An opaque type defined in
 .Pa mdoc.c .
 Its values are only used privately within the library.
-.\" LIST-ITEM
-.It Vt struct mdoc_cb
-A set of message callbacks defined in
-.Pa mdoc.h .
-.\" LIST-ITEM
 .It Vt struct mdoc_node
-A parsed node.  Defined in
+A parsed node.
+Defined in
 .Pa mdoc.h .
 See
 .Sx Abstract Syntax Tree
 for details.
+.It Vt mandocmsg
+A function callback type defined in
+.Pa mandoc.h .
 .El
-.\" SUBSECTION
 .Ss Functions
 Function descriptions follow:
 .Bl -ohang
-.\" LIST-ITEM
 .It Fn mdoc_alloc
-Allocates a parsing structure.  The
+Allocates a parsing structure.
+The
 .Fa data
 pointer is passed to callbacks in
 .Fa cb ,
@@ -125,63 +118,62 @@ The
 .Fa pflags
 arguments are defined in
 .Pa mdoc.h .
-Returns NULL on failure.  If non-NULL, the pointer must be freed with
+Returns NULL on failure.
+If non-NULL, the pointer must be freed with
 .Fn mdoc_free .
-.\" LIST-ITEM
 .It Fn mdoc_reset
-Reset the parser for another parse routine.  After its use,
+Reset the parser for another parse routine.
+After its use,
 .Fn mdoc_parseln
-behaves as if invoked for the first time.  If it returns 0, memory could
-not be allocated.
-.\" LIST-ITEM
+behaves as if invoked for the first time.
+If it returns 0, memory could not be allocated.
 .It Fn mdoc_free
-Free all resources of a parser.  The pointer is no longer valid after
-invocation.
-.\" LIST-ITEM
+Free all resources of a parser.
+The pointer is no longer valid after invocation.
 .It Fn mdoc_parseln
-Parse a nil-terminated line of input.  This line should not contain the
-trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
+Parse a nil-terminated line of input.
+This line should not contain the trailing newline.
+Returns 0 on failure, 1 on success.
+The input buffer
 .Fa buf
 is modified by this function.
-.\" LIST-ITEM
 .It Fn mdoc_endparse
-Signals that the parse is complete.  Note that if
+Signals that the parse is complete.
+Note that if
 .Fn mdoc_endparse
 is called subsequent to
 .Fn mdoc_node ,
-the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
-.\" LIST-ITEM
+the resulting tree is incomplete.
+Returns 0 on failure, 1 on success.
 .It Fn mdoc_node
-Returns the first node of the parse.  Note that if
+Returns the first node of the parse.
+Note that if
 .Fn mdoc_parseln
 or
 .Fn mdoc_endparse
 return 0, the tree will be incomplete.
 .It Fn mdoc_meta
-Returns the document's parsed meta-data.  If this information has not
-yet been supplied or
+Returns the document's parsed meta-data.
+If this information has not yet been supplied or
 .Fn mdoc_parseln
 or
 .Fn mdoc_endparse
 return 0, the data will be incomplete.
 .El
-.\" SUBSECTION
 .Ss Variables
 The following variables are also defined:
 .Bl -ohang
-.\" LIST-ITEM
 .It Va mdoc_macronames
 An array of string-ified token names.
-.\" LIST-ITEM
 .It Va mdoc_argnames
 An array of string-ified token argument names.
 .El
-.\" SUBSECTION
 .Ss Abstract Syntax Tree
 The
 .Nm
 functions produce an abstract syntax tree (AST) describing input in a
-regular form.  It may be reviewed at any time with
+regular form.
+It may be reviewed at any time with
 .Fn mdoc_nodes ;
 however, if called before
 .Fn mdoc_endparse ,
@@ -190,7 +182,6 @@ or after
 or
 .Fn mdoc_parseln
 fail, it may be incomplete.
-.\" PARAGRAPH
 .Pp
 This AST is governed by the ontological
 rules dictated in
@@ -201,14 +192,14 @@ elements described in
 .Xr mdoc 7
 are described simply as
 .Qq elements .
-.\" PARAGRAPH
 .Pp
 The AST is composed of
 .Vt struct mdoc_node
 nodes with block, head, body, element, root and text types as declared
 by the
 .Va type
-field.  Each node also provides its parse point (the
+field.
+Each node also provides its parse point (the
 .Va line ,
 .Va sec ,
 and
@@ -220,13 +211,11 @@ fields), its position in the tree (the
 and
 .Va prev
 fields) and some type-specific data.
-.\" PARAGRAPH
 .Pp
 The tree itself is arranged according to the following normal form,
 where capitalised non-terminals represent nodes.
 .Pp
 .Bl -tag -width "ELEMENTXX" -compact
-.\" LIST-ITEM
 .It ROOT
 \(<- mnode+
 .It mnode
@@ -244,17 +233,16 @@ where capitalised non-terminals represent nodes.
 .It TAIL
 \(<- mnode+
 .It TEXT
-\(<- [[:alpha:]]*
+\(<- [[:printable:],0x1e]*
 .El
-.\" PARAGRAPH
 .Pp
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
-the BLOCK production.  These refer to punctuation marks.  Furthermore,
-although a TEXT node will generally have a non-zero-length string, in
-the specific case of
+the BLOCK production.
+These refer to punctuation marks.
+Furthermore, although a TEXT node will generally have a non-zero-length
+string, in the specific case of
 .Sq \&.Bd \-literal ,
 an empty line will produce a zero-length string.
-.\" SECTION
 .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating
 on the finished parse tree with
@@ -288,49 +276,15 @@ if (NULL == (node = mdoc_node(mdoc)))
 parsed(mdoc, node);
 mdoc_free(mdoc);
 .Ed
-.\" SECTION
+.Pp
+Please see
+.Pa main.c
+in the source archive for a rigorous reference.
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr mdoc 7
-.\" SECTION
 .Sh AUTHORS
 The
 .Nm
-utility was written by
+library was written by
 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
-.\" SECTION
-.Sh CAVEATS
-.Bl -dash -compact
-.\" LIST-ITEM
-.It
-The
-.Sq \&.Xc
-and
-.Sq \&.Xo
-macros aren't handled when used to span lines for the
-.Sq \&.It
-macro.
-.\" LIST-ITEM
-.It
-The
-.Sq \&.Bsx
-macro family doesn't yet understand version arguments.
-.\" LIST-ITEM
-.It
-If not given a value, the \-offset argument to
-.Sq \&.Bd
-and
-.Sq \&.Bl
-should be the width of
-.Qq <string> ;
-instead, a value of
-.Li 10n
-is provided.
-.\" LIST-ITEM
-.It
-Columns widths in
-.Sq \&.Bl \-column
-should default to width
-.Qq <stringx>
-if not included.
-.El