===================================================================
RCS file: /cvs/mandoc/mandoc_headers.3,v
retrieving revision 1.19
retrieving revision 1.22
diff -u -p -r1.19 -r1.22
--- mandoc/mandoc_headers.3	2018/08/24 23:12:33	1.19
+++ mandoc/mandoc_headers.3	2018/12/13 03:40:13	1.22
@@ -1,4 +1,4 @@
-.Dd $Mdocdate: August 24 2018 $
+.Dd $Mdocdate: December 13 2018 $
 .Dt MANDOC_HEADERS 3
 .Os
 .Sh NAME
@@ -25,15 +25,15 @@ separate from each other:
 .Pp
 .Bl -dash -offset indent -compact
 .It
+.Xr roff 7
+parser
+.It
 .Xr mdoc 7
 parser
 .It
 .Xr man 7
 parser
 .It
-.Xr roff 7
-parser
-.It
 .Xr tbl 7
 parser
 .It
@@ -45,6 +45,8 @@ terminal formatters
 HTML formatters
 .It
 search tools
+.It
+main programs
 .El
 .Pp
 Note that mere usage of an opaque struct type does
@@ -56,14 +58,18 @@ any other mandoc header.
 These headers should be included before any other mandoc headers.
 .Bl -tag -width Ds
 .It Qq Pa mandoc_aux.h
+Memory allocation utility functions; can be used everywhere.
+.Pp
 Requires
 .In sys/types.h
 for
 .Vt size_t .
 .Pp
-Provides the utility functions documented in
+Provides the functions documented in
 .Xr mandoc_malloc 3 .
 .It Qq Pa mandoc_ohash.h
+Hashing utility functions; can be used everywhere.
+.Pp
 Requires
 .In stddef.h
 for
@@ -78,6 +84,9 @@ Includes
 and provides
 .Fn mandoc_ohash_init .
 .It Qq Pa mandoc.h
+Error handling utilities and top level parser interface;
+can be used everywhere.
+.Pp
 Requires
 .In sys/types.h
 for
@@ -88,18 +97,10 @@ Provides
 .Vt enum mandocerr ,
 .Vt enum mandoclevel ,
 .Vt enum mandoc_os ,
-.Vt enum tbl_cellt ,
-.Vt enum tbl_datt ,
-.Vt enum tbl_spant ,
 .Vt enum eqn_boxt ,
 .Vt enum eqn_fontt ,
 .Vt enum eqn_pilet ,
 .Vt enum eqn_post ,
-.Vt struct tbl_opts ,
-.Vt struct tbl_cell ,
-.Vt struct tbl_row ,
-.Vt struct tbl_dat ,
-.Vt struct tbl_span ,
 .Vt struct eqn_box ,
 the function prototype typedef
 .Fn mandocmsg ,
@@ -122,7 +123,30 @@ Uses the type
 from
 .Pa roff.h
 as an opaque type for function prototypes.
+.It Qq Pa tbl.h
+Data structures for the
+.Xr tbl 7
+parse tree; can be used everywhere.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides
+.Vt enum tbl_cellt ,
+.Vt enum tbl_datt ,
+.Vt enum tbl_spant ,
+.Vt struct tbl_opts ,
+.Vt struct tbl_cell ,
+.Vt struct tbl_row ,
+.Vt struct tbl_dat ,
+and
+.Vt struct tbl_span .
 .It Qq Pa mandoc_xr.h
+Cross reference validation; intended for use in the main program
+and in parsers, but not in formatters.
+.Pp
 Provides
 .Vt struct mandoc_xr
 and the functions
@@ -207,9 +231,7 @@ from
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa libman.h
-or
-.Pa libroff.h .
+internals of different parsers.
 .It Qq Pa man.h
 Provides the functions
 .Fn man_*
@@ -228,12 +250,10 @@ from
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa libmdoc.h
-or
-.Pa libroff.h .
+internals of different parsers.
 .El
 .Ss Parser internals
-The following headers require inclusion of a parser interface header
+Most of the following headers require inclusion of a parser interface header
 before they can be included.
 All parser interface headers should precede all parser internal headers.
 When any parser internal headers are included, the same file should
@@ -327,10 +347,7 @@ from
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa man.h ,
-.Pa libman.h ,
-or
-.Pa libroff.h .
+interfaces of different parsers.
 .It Qq Pa libman.h
 Requires
 .Qq Pa roff.h
@@ -352,44 +369,113 @@ from
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa mdoc.h ,
-.Pa libmdoc.h ,
-or
-.Pa libroff.h .
-.It Qq Pa libroff.h
+interfaces of different parsers.
+.It Qq Pa eqn_parse.h
+External interface of the
+.Xr eqn 7
+parser, for use in the
+.Xr roff 7
+and
+.Xr eqn 7
+parsers only.
+.Pp
 Requires
 .In sys/types.h
 for
-.Vt size_t
+.Vt size_t .
+.Pp
+Provides
+.Vt struct eqn_node
+and the functions
+.Fn eqn_alloc ,
+.Fn eqn_box_free ,
+.Fn eqn_free ,
+.Fn eqn_parse ,
+.Fn eqn_read ,
 and
-.Qq Pa mandoc.h
-for
-.Vt struct tbl_*
+.Fn eqn_reset .
+.Pp
+Uses the opaque type
+.Vt struct mparse
+from
+.Pa read.c
+for function prototypes.
+Uses the type
+.Vt struct eqn_box
+from
+.Pa mandoc.h
+as an opaque type for function prototypes.
+Uses the types
+.Vt struct roff_node
+from
+.Pa roff.h
 and
-.Vt struct eqn_box .
+.Vt struct eqn_def
+from
+.Pa eqn.c
+as opaque struct members.
 .Pp
-Provides
-.Vt enum tbl_part ,
-.Vt struct tbl_node ,
-.Vt struct eqn_def ,
-.Vt struct eqn_node ,
-and many functions internal to the
+When this header is included, the same file should not include
+internals of different parsers.
+.It Qq Pa tbl_parse.h
+External interface of the
 .Xr tbl 7
+parser, for use in the
+.Xr roff 7
 and
-.Xr eqn 7
-parsers.
+.Xr tbl 7
+parsers only.
 .Pp
+Provides the functions documented in
+.Xr tbl 3 .
+.Pp
 Uses the opaque type
 .Vt struct mparse
 from
 .Pa read.c .
+Uses the types
+.Vt struct tbl_span
+from
+.Pa tbl.h
+and
+.Vt struct tbl_node
+from
+.Pa tbl_int.h
+as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa man.h ,
-.Pa mdoc.h ,
-.Pa libman.h ,
-or
-.Pa libmdoc.h .
+internals of different parsers.
+.It Qq Pa tbl_int.h
+Internal interfaces of the
+.Xr tbl 7
+parser, for use inside the
+.Xr tbl 7
+parser only.
+.Pp
+Requires
+.Qq Pa tbl.h
+for
+.Vt struct tbl_opts .
+.Pp
+Provides
+.Vt enum tbl_part ,
+.Vt struct tbl_node ,
+and the functions
+.Fn tbl_option ,
+.Fn tbl_layout ,
+.Fn tbl_data ,
+.Fn tbl_cdata ,
+and
+.Fn tbl_reset .
+.Pp
+Uses a pointer to the opaque type
+.Vt struct mparse
+from
+.Pa read.c
+as an opaque struct member.
+.Pp
+When this header is included, the same file should not include
+interfaces of different parsers.
 .El
 .Ss Formatter interface
 These headers should be included after any parser interface headers.