===================================================================
RCS file: /cvs/mandoc/mandoc_headers.3,v
retrieving revision 1.8
retrieving revision 1.20
diff -u -p -r1.8 -r1.20
--- mandoc/mandoc_headers.3	2016/07/07 19:19:01	1.8
+++ mandoc/mandoc_headers.3	2018/12/12 21:54:35	1.20
@@ -1,4 +1,4 @@
-.Dd December 1, 2014
+.Dd $Mdocdate: December 12 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,18 +58,35 @@ 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 .
-Provides the utility functions documented in
+.Pp
+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
+.Vt ptrdiff_t
+and
+.In stdint.h
+for
+.Vt uint32_t .
+.Pp
 Includes
 .In ohash.h
 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
@@ -77,20 +96,12 @@ Provides
 .Vt enum mandoc_esc ,
 .Vt enum mandocerr ,
 .Vt enum mandoclevel ,
-.Vt enum tbl_cellt ,
-.Vt enum tbl_datt ,
-.Vt enum tbl_spant ,
+.Vt enum mandoc_os ,
 .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 ,
-.Vt struct eqn ,
 the function prototype typedef
 .Fn mandocmsg ,
 the function
@@ -112,18 +123,67 @@ 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
+.Fn mandoc_xr_reset ,
+.Fn mandoc_xr_add ,
+.Fn mandoc_xr_get ,
+and
+.Fn mandoc_xr_free .
 .It Qq Pa roff.h
+Requires
+.Qq Pa mandoc_ohash.h
+for
+.Vt struct ohash
+and
+.Qq Pa mandoc.h
+for
+.Vt enum mandoc_os .
+.Pp
 Provides
 .Vt enum mdoc_endbody ,
 .Vt enum roff_macroset ,
 .Vt enum roff_next ,
 .Vt enum roff_sec ,
+.Vt enum roff_tok ,
 .Vt enum roff_type ,
 .Vt struct roff_man ,
 .Vt struct roff_meta ,
 .Vt struct roff_node ,
-and the function
-.Fn deroff .
+the constant array
+.Va roff_name
+and the functions
+.Fn deroff ,
+.Fn roffhash_alloc ,
+.Fn roffhash_find ,
+.Fn roffhash_free ,
+and
+.Fn roff_validate .
 .Pp
 Uses pointers to the types
 .Vt struct mdoc_arg
@@ -198,9 +258,10 @@ or
 .El
 .Ss Parser internals
 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 not include any formatter headers.
+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
+not include any formatter headers.
 .Bl -tag -width Ds
 .It Qq Pa libmandoc.h
 Requires
@@ -213,7 +274,6 @@ for
 .Vt enum mandocerr .
 .Pp
 Provides
-.Vt enum rofferr ,
 .Vt struct buf ,
 utility functions needed by multiple parsers,
 and the top-level functions to call the parsers.
@@ -227,17 +287,11 @@ and
 from
 .Pa roff.c
 for function prototypes.
-Uses the types
-.Vt struct tbl_span
-and
-.Vt struct eqn
-from
-.Pa mandoc.h
-and
+Uses the type
 .Vt struct roff_man
 from
 .Pa roff.h
-as opaque types for function prototypes.
+as an opaque type for function prototypes.
 .It Qq Pa roff_int.h
 Requires
 .Qq Pa roff.h
@@ -254,16 +308,11 @@ because the latter two are needed by
 .Qq Pa roff.c .
 .Pp
 Uses the types
-.Vt struct eqn
-and
-.Vt struct tbl_span
-from
-.Pa mandoc.h ,
 .Vt struct roff_man
 and
 .Vt struct roff_node
 from
-.Pa roff.h ,
+.Pa roff.h
 and
 .Vt struct mdoc_arg
 from
@@ -271,6 +320,10 @@ from
 as opaque types for function prototypes.
 .It Qq Pa libmdoc.h
 Requires
+.Qq Pa roff.h
+for
+.Vt enum roff_tok
+and
 .Qq Pa mdoc.h
 for
 .Vt enum mdoc_*
@@ -303,6 +356,11 @@ When this header is included, the same file should not
 or
 .Pa libroff.h .
 .It Qq Pa libman.h
+Requires
+.Qq Pa roff.h
+for
+.Vt enum roff_tok .
+.Pp
 Provides
 .Vt struct man_macro
 and some functions internal to the
@@ -326,16 +384,13 @@ or
 Requires
 .In sys/types.h
 for
-.Vt size_t ,
+.Vt size_t
+and
 .Qq Pa mandoc.h
 for
 .Vt struct tbl_*
 and
-.Vt struct eqn ,
-and
-.Qq Pa libmandoc.h
-for
-.Vt enum rofferr .
+.Vt struct eqn_box .
 .Pp
 Provides
 .Vt enum tbl_part ,
@@ -405,6 +460,7 @@ Provides
 .Vt enum termtype ,
 .Vt struct termp_tbl ,
 .Vt struct termp ,
+.Fn roff_term_pre ,
 and many terminal formatting functions.
 .Pp
 Uses the opaque type
@@ -414,11 +470,13 @@ from
 Uses
 .Vt struct tbl_span
 and
-.Vt struct eqn
+.Vt struct eqn_box
 from
 .Pa mandoc.h
 and
 .Vt struct roff_meta
+and
+.Vt struct roff_node
 from
 .Pa roff.h
 as opaque types for function prototypes.
@@ -431,10 +489,7 @@ or
 Requires
 .In sys/types.h
 for
-.Vt size_t ,
-.In stdio.h
-for
-.Dv BUFSIZ ,
+.Vt size_t
 and
 .Qq Pa out.h
 for
@@ -450,8 +505,21 @@ Provides
 .Vt struct tagq ,
 .Vt struct htmlpair ,
 .Vt struct html ,
+.Fn roff_html_pre ,
 and many HTML formatting functions.
 .Pp
+Uses
+.Vt struct tbl_span
+and
+.Vt struct eqn_box
+from
+.Pa mandoc.h
+and
+.Vt struct roff_node
+from
+.Pa roff.h
+as opaque types for function prototypes.
+.Pp
 When this header is included, the same file should not include
 .Pa term.h
 or
@@ -489,8 +557,9 @@ Provides
 and the functions
 .Fn manconf_parse ,
 .Fn manconf_output ,
+.Fn manconf_free ,
 and
-.Fn manconf_free .
+.Fn manpath_base .
 .It Qq Pa mansearch.h
 Requires
 .In sys/types.h
@@ -506,8 +575,7 @@ Provides
 .Vt struct manpage ,
 .Vt struct mansearch ,
 and the functions
-.Fn mansearch_setup ,
-.Fn mansearch ,
+.Fn mansearch
 and
 .Fn mansearch_free .
 .Pp