update developer documentation

1 files changed, 86 insertions, 95 deletions

diff --git a/mandoc.3 b/mandoc.3
index 30135a26..d1471c97 100644
--- a/mandoc.3
+++ b/mandoc.3
@@ -20,13 +20,11 @@
 .Os
 .Sh NAME
 .Nm mandoc ,
-.Nm man_deroff ,
-.Nm man_meta ,
+.Nm deroff ,
+.Nm mandocmsg ,
 .Nm man_mparse ,
-.Nm man_node ,
-.Nm mdoc_deroff ,
-.Nm mdoc_meta ,
-.Nm mdoc_node ,
+.Nm man_validate ,
+.Nm mdoc_validate ,
 .Nm mparse_alloc ,
 .Nm mparse_free ,
 .Nm mparse_getkeep ,
@@ -91,8 +89,7 @@
 .Ft void
 .Fo mparse_result
 .Fa "struct mparse *parse"
-.Fa "struct mdoc **mdoc"
-.Fa "struct man **man"
+.Fa "struct roff_man **man"
 .Fa "char **sodest"
 .Fc
 .Ft "const char *"
@@ -103,45 +100,33 @@
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc
-.In sys/types.h
-.In mandoc.h
-.In mdoc.h
+.In roff.h
 .Ft void
-.Fo mdoc_deroff
+.Fo deroff
 .Fa "char **dest"
-.Fa "const struct mdoc_node *node"
-.Fc
-.Ft "const struct mdoc_meta *"
-.Fo mdoc_meta
-.Fa "const struct mdoc *mdoc"
-.Fc
-.Ft "const struct mdoc_node *"
-.Fo mdoc_node
-.Fa "const struct mdoc *mdoc"
+.Fa "const struct roff_node *node"
 .Fc
+.In sys/types.h
+.In mandoc.h
+.In mdoc.h
 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;
+.Ft void
+.Fo mdoc_validate
+.Fa "struct roff_man *mdoc"
+.Fc
 .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"
-.Fc
+.Vt extern const char * const * man_macronames;
 .Ft "const struct mparse *"
 .Fo man_mparse
-.Fa "const struct man *man"
+.Fa "const struct roff_man *man"
 .Fc
-.Ft "const struct man_node *"
-.Fo man_node
-.Fa "const struct man *man"
+.Ft void
+.Fo man_validate
+.Fa "struct roff_man *man"
 .Fc
-.Vt extern const char * const * man_macronames;
 .Sh DESCRIPTION
 The
 .Nm mandoc
@@ -182,10 +167,24 @@ close it with
 retrieve the syntax tree with
 .Fn mparse_result ;
 .It
-iterate over parse nodes with
-.Fn mdoc_node
+depending on whether the
+.Fa macroset
+member of the returned
+.Vt struct roff_man
+is
+.Dv MACROSET_MDOC
+or
+.Dv MACROSET_MAN ,
+validate it with
+.Fn mdoc_validate
 or
-.Fn man_node ;
+.Fn man_validate ,
+respectively;
+.It
+iterate over parse nodes with starting from the
+.Fa first
+member of the returned
+.Vt struct roff_man ;
 .It
 free all allocated memory with
 .Fn mparse_free
@@ -193,7 +192,7 @@ and
 .Xr mchars_free 3 ,
 or invoke
 .Fn mparse_reset
-and parse new files.
+and go back to step 2 to parse new files.
 .El
 .Sh REFERENCE
 This section documents the functions, types, and variables available
@@ -211,6 +210,9 @@ An error or warning message during parsing.
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.
+See the DIAGNOSTICS section in
+.Xr mandoc 1
+regarding the meanings of the levels.
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with
@@ -226,67 +228,37 @@ messages emitted by the parser.
 .El
 .Ss Functions
 .Bl -ohang
-.It Fn man_deroff
+.It Fn deroff
 Obtain a text-only representation of a
-.Vt struct man_node ,
+.Vt struct roff_node ,
 including text contained in its child nodes.
-To be used on children of the pointer returned from
-.Fn man_node .
+To be used on children of the
+.Fa first
+member of
+.Vt struct roff_man .
 When it is no longer needed, the pointer returned from
-.Fn man_deroff
+.Fn deroff
 can be passed to
 .Xr free 3 .
-.It Fn man_meta
-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
-.In man.h ,
-implemented in
-.Pa man.c .
 .It Fn man_mparse
 Get the parser used for the current output.
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .
-.It Fn man_node
-Obtain the root node of a successful
-.Xr man 7
-parse.
-This may only be used on a pointer returned by
+.It Fn man_validate
+Validate the
+.Dv MACROSET_MAN
+parse tree obtained with
 .Fn mparse_result .
 Declared in
 .In man.h ,
 implemented in
 .Pa man.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
-.Xr mdoc
-parse.
-This may only be used on a pointer returned by
-.Fn mparse_result .
-Declared in
-.In mdoc.h ,
-implemented in
-.Pa mdoc.c .
-.It Fn mdoc_node
-Obtain the root node of a successful
-.Xr mdoc
-parse.
-This may only be used on a pointer returned by
+.It Fn mdoc_validate
+Validate the
+.Dv MACROSET_MDOC
+parse tree obtained with
 .Fn mparse_result .
 Declared in
 .In mdoc.h ,
@@ -335,6 +307,9 @@ A callback function to handle errors and warnings.
 See
 .Pa main.c
 for an example.
+If printing of error messages is not desired,
+.Dv NULL
+may be passed.
 .It Ar defos
 A default string for the
 .Xr mdoc 7
@@ -343,6 +318,9 @@ macro, overriding the
 .Dv OSNAME
 preprocessor definition and the results of
 .Xr uname 3 .
+Passing
+.Dv NULL
+sets no default.
 .El
 .Pp
 The same parser may be used for multiple files so long as
@@ -421,7 +399,7 @@ implemented in
 .Pa read.c .
 .It Fn mparse_result
 Obtain the result of a parse.
-One of the three pointers will be filled in.
+One of the two pointers will be filled in.
 Declared in
 .In mandoc.h ,
 implemented in
@@ -442,13 +420,19 @@ implemented in
 .Ss Variables
 .Bl -ohang
 .It Va man_macronames
-The string representation of a man macro as indexed by
+The string representation of a
+.Xr man 7
+macro as indexed by
 .Vt "enum mant" .
 .It Va mdoc_argnames
-The string representation of a mdoc macro argument as indexed by
+The string representation of an
+.Xr mdoc 7
+macro argument as indexed by
 .Vt "enum mdocargt" .
 .It Va mdoc_macronames
-The string representation of a mdoc macro as indexed by
+The string representation of an
+.Xr mdoc 7
+macro as indexed by
 .Vt "enum mdoct" .
 .El
 .Sh IMPLEMENTATION NOTES
@@ -492,15 +476,15 @@ This AST is governed by the ontological rules dictated in
 and derives its terminology accordingly.
 .Pp
 The AST is composed of
-.Vt struct man_node
+.Vt struct roff_node
 nodes with element, root and text types as declared by the
 .Va type
 field.
 Each node also provides its parse point (the
 .Va line ,
-.Va sec ,
+.Va pos ,
 and
-.Va pos
+.Va sec
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,
@@ -544,16 +528,16 @@ are described simply as
 .Qq elements .
 .Pp
 The AST is composed of
-.Vt struct mdoc_node
+.Vt struct roff_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
 .Va line ,
-.Va sec ,
+.Va pos ,
 and
-.Va pos
+.Va sec
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,
@@ -670,9 +654,13 @@ consistent across troff implementations, especially when using multiple
 levels of badly-nested blocks.
 .Sh SEE ALSO
 .Xr mandoc 1 ,
+.Xr man.cgi 3 ,
 .Xr mandoc_escape 3 ,
+.Xr mandoc_headers 3 ,
 .Xr mandoc_malloc 3 ,
+.Xr mansearch 3 ,
 .Xr mchars_alloc 3 ,
+.Xr tbl 3 ,
 .Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,
@@ -680,7 +668,10 @@ levels of badly-nested blocks.
 .Xr roff 7 ,
 .Xr tbl 7
 .Sh AUTHORS
+.An -nosplit
 The
 .Nm
 library was written by
-.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
+and is maintained by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .