===================================================================
RCS file: /cvs/mandoc/mandoc_headers.3,v
retrieving revision 1.27
retrieving revision 1.35
diff -u -p -r1.27 -r1.35
--- mandoc/mandoc_headers.3	2018/12/14 01:18:25	1.27
+++ mandoc/mandoc_headers.3	2022/04/14 16:43:44	1.35
@@ -1,4 +1,20 @@
-.Dd $Mdocdate: December 14 2018 $
+.\" $Id: mandoc_headers.3,v 1.35 2022/04/14 16:43:44 schwarze Exp $
+.\"
+.\" Copyright (c) 2014-2022 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 14 2022 $
 .Dt MANDOC_HEADERS 3
 .Os
 .Sh NAME
@@ -9,8 +25,8 @@ To support a cleaner coding style, the mandoc header f
 contain any include directives and do not guard against multiple
 inclusion.
 The application developer has to make sure that the headers are
-included in a proper order, and that no header is included more
-than once.
+included in the order shown in this manual page,
+and that no header is included more than once.
 .Pp
 The headers and functions form three major groups:
 .Sx Parser interface ,
@@ -67,6 +83,33 @@ for
 .Pp
 Provides the functions documented in
 .Xr mandoc_malloc 3 .
+.Pp
+When this header is included, the same file must not include
+.Qq Pa mandoc_dbg.h
+because
+.Qq Pa mandoc_aux.h
+automatically includes
+.Qq Pa mandoc_dbg.h
+if and only if the preprocessor symbol
+.Dv DEBUG_MEMORY
+is defined.
+.It Qq Pa mandoc_dbg.h
+Debugging utility functions and
+debugging wrappers around memory allocation functions.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides the functions documented in
+.Xr mandoc_dbg_init 3 .
+.Pp
+This header must not be included unless the preprocessor symbol
+.Dv DEBUG_MEMORY
+is defined.
+When this header is included, the same file must not include
+.Qq Pa mandoc_aux.h .
 .It Qq Pa mandoc_ohash.h
 Hashing utility functions; can be used everywhere.
 .Pp
@@ -115,7 +158,6 @@ Provides
 .Vt enum mandoc_os ,
 .Vt enum mdoc_endbody ,
 .Vt enum roff_macroset ,
-.Vt enum roff_next ,
 .Vt enum roff_sec ,
 .Vt enum roff_tok ,
 .Vt enum roff_type ,
@@ -124,21 +166,25 @@ Provides
 .Vt struct roff_node ,
 the constant array
 .Va roff_name
-and the functions
-.Fn deroff
-and
-.Fn roff_validate .
+and the function
+.Fn deroff .
 .Pp
 Uses pointers to the types
 .Vt struct ohash
 from
-.Pa mandoc_ohash.h
-and
+.Qq Pa mandoc_ohash.h ,
 .Vt struct mdoc_arg
 and
 .Vt union mdoc_data
 from
-.Pa mdoc.h
+.Qq Pa mdoc.h ,
+.Vt struct tbl_span
+from
+.Qq Pa tbl.h ,
+and
+.Vt struct eqn_box
+from
+.Qq Pa eqn.h
 as opaque struct members.
 .It Qq Pa tbl.h
 Data structures for the
@@ -148,7 +194,11 @@ parse tree; can be used everywhere.
 Requires
 .In sys/types.h
 for
-.Vt size_t .
+.Vt size_t
+and
+.Qq Pa mandoc.h
+for
+.Vt enum mandoc_esc .
 .Pp
 Provides
 .Vt enum tbl_cellt ,
@@ -181,26 +231,25 @@ Top level parser interface, for use in the main progra
 and in the main parser, but not in formatters.
 .Pp
 Requires
-.Pa mandoc.h
+.Qq Pa mandoc.h
 for
-.Vt enum mandocerr ,
-.Vt enum mandoclevel ,
+.Vt enum mandocerr
 and
-.Fn mandocmsg ,
+.Vt enum mandoclevel
 and
-.Pa roff.h
+.Qq Pa roff.h
 for
 .Vt enum mandoc_os .
 .Pp
-Uses to opaque type
+Uses the opaque type
 .Vt struct mparse
 from
 .Pa read.c
 for function prototypes.
 Uses
-.Vt struct roff_man
+.Vt struct roff_meta
 from
-.Pa roff.h
+.Qq Pa roff.h
 as an opaque type for function prototypes.
 .It Qq Pa mandoc_xr.h
 Cross reference validation; intended for use in the main program
@@ -214,6 +263,30 @@ and the functions
 .Fn mandoc_xr_get ,
 and
 .Fn mandoc_xr_free .
+.It Qq Pa tag.h
+Internal interfaces to tag syntax tree nodes,
+for use by validation modules only.
+.Pp
+Requires
+.In limits.h
+for
+.Dv INT_MAX .
+.Pp
+Provides the functions
+.Fn tag_alloc ,
+.Fn tag_put ,
+.Fn tag_check ,
+and
+.Fn tag_free
+and some
+.Dv TAG_*
+constants.
+.Pp
+Uses the type
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
 .El
 .Pp
 The following two require
@@ -246,11 +319,15 @@ and the functions
 described in
 .Xr mandoc 3 .
 .Pp
-Uses the type
+Uses the types
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+and
 .Vt struct roff_man
 from
-.Pa roff.h
-as an opaque type for function prototypes.
+.Qq Pa roff_int.h
+as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
 internals of different parsers.
@@ -260,15 +337,10 @@ Provides the functions
 described in
 .Xr mandoc 3 .
 .Pp
-Uses the opaque type
-.Vt struct mparse
-from
-.Pa read.c
-for function prototypes.
 Uses the type
 .Vt struct roff_man
 from
-.Pa roff.h
+.Qq Pa roff.h
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include
@@ -296,11 +368,7 @@ Provides
 utility functions needed by multiple parsers,
 and the top-level functions to call the parsers.
 .Pp
-Uses the opaque types
-.Vt struct mparse
-from
-.Pa read.c
-and
+Uses the opaque type
 .Vt struct roff
 from
 .Pa roff.c
@@ -308,7 +376,7 @@ for function prototypes.
 Uses the type
 .Vt struct roff_man
 from
-.Pa roff.h
+.Qq Pa roff.h
 as an opaque type for function prototypes.
 .It Qq Pa roff_int.h
 Parser internals shared by multiple parsers.
@@ -321,30 +389,40 @@ for
 and
 .Vt enum roff_tok .
 .Pp
-Provides functions named
+Provides
+.Vt enum roff_next ,
+.Vt struct roff_man ,
+functions named
 .Fn roff_*
 to handle roff nodes,
 .Fn roffhash_alloc ,
 .Fn roffhash_find ,
-and
 .Fn roffhash_free ,
+and
+.Fn roff_validate ,
 and the two special functions
 .Fn man_breakscope
 and
 .Fn mdoc_argv_free
 because the latter two are needed by
-.Qq Pa roff.c .
+.Pa roff.c .
 .Pp
 Uses the types
-.Vt struct roff_man
-and
+.Vt struct ohash
+from
+.Qq Pa mandoc_ohash.h ,
 .Vt struct roff_node
+and
+.Vt struct roff_meta
 from
-.Pa roff.h
+.Qq Pa roff.h ,
+.Vt struct roff
+from
+.Pa roff.c ,
 and
 .Vt struct mdoc_arg
 from
-.Pa mdoc.h
+.Qq Pa mdoc.h
 as opaque types for function prototypes.
 .It Qq Pa libmdoc.h
 Requires
@@ -363,15 +441,16 @@ and many functions internal to the
 parser.
 .Pp
 Uses the types
-.Vt struct roff_man
-and
 .Vt struct roff_node
 from
-.Pa roff.h
+.Qq Pa roff.h ,
+.Vt struct roff_man
+from
+.Qq Pa roff_int.h ,
 and
 .Vt struct mdoc_arg
 from
-.Pa mdoc.h
+.Qq Pa mdoc.h
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
@@ -389,11 +468,13 @@ and some functions internal to the
 parser.
 .Pp
 Uses the types
-.Vt struct roff_man
-and
 .Vt struct roff_node
 from
-.Pa roff.h
+.Qq Pa roff.h
+and
+.Vt struct roff_man
+from
+.Qq Pa roff_int.h
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
@@ -424,20 +505,15 @@ and the functions
 and
 .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
+.Qq Pa mandoc.h
 as an opaque type for function prototypes.
 Uses the types
 .Vt struct roff_node
 from
-.Pa roff.h
+.Qq Pa roff.h
 and
 .Vt struct eqn_def
 from
@@ -458,18 +534,14 @@ parsers only.
 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
+.Qq Pa tbl.h
 and
 .Vt struct tbl_node
 from
-.Pa tbl_int.h
+.Qq Pa tbl_int.h
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
@@ -497,12 +569,6 @@ and the functions
 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
@@ -528,11 +594,11 @@ and
 Uses
 .Vt struct tbl_span
 from
-.Pa mandoc.h
+.Qq Pa mandoc.h
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa mansearch.h .
+.Qq Pa mansearch.h .
 .It Qq Pa term.h
 Requires
 .In sys/types.h
@@ -563,25 +629,58 @@ Uses
 and
 .Vt struct eqn_box
 from
-.Pa mandoc.h
+.Qq Pa mandoc.h
 and
 .Vt struct roff_meta
 and
 .Vt struct roff_node
 from
-.Pa roff.h
+.Qq Pa roff.h
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa html.h
+.Qq Pa html.h
 or
-.Pa mansearch.h .
-.It Qq Pa html.h
+.Qq Pa mansearch.h .
+.It Qq Pa tag_term.h
 Requires
 .In sys/types.h
 for
 .Vt size_t
 and
+.In stdio.h
+for
+.Vt FILE .
+.Pp
+Provides an interface to generate
+.Xr ctags 1
+files for the
+.Ic :t
+functionality mentioned in
+.Xr man 1 .
+.Pp
+Uses the type
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.Pp
+When this header is included, the same file should not include
+.Qq Pa html.h
+or
+.Qq Pa mansearch.h .
+.It Qq Pa html.h
+Requires
+.In sys/types.h
+for
+.Vt size_t ,
+.Qq Pa mandoc.h
+for
+.Vt enum mandoc_esc ,
+.Qq Pa roff.h
+for
+.Vt enum roff_tok ,
+and
 .Qq Pa out.h
 for
 .Vt struct roffsu
@@ -604,36 +703,25 @@ Uses
 and
 .Vt struct eqn_box
 from
-.Pa mandoc.h
+.Qq Pa mandoc.h
 and
 .Vt struct roff_node
 from
-.Pa roff.h
+.Qq Pa roff.h
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa term.h
+.Qq Pa term.h ,
+.Qq Pa tab_term.h ,
 or
-.Pa mansearch.h .
-.It Qq Pa tag.h
-Requires
-.In sys/types.h
-for
-.Vt size_t .
-.Pp
-Provides an interface to generate
-.Xr ctags 1
-files for the
-.Ic :t
-functionality mentioned in
-.Xr man 1 .
+.Qq Pa mansearch.h .
 .It Qq Pa main.h
 Provides the top level steering functions for all formatters.
 .Pp
 Uses the type
-.Vt struct roff_man
+.Vt struct roff_meta
 from
-.Pa roff.h
+.Qq Pa roff.h
 as an opaque type for function prototypes.
 .It Qq Pa manconf.h
 Requires
@@ -673,12 +761,13 @@ and
 Uses
 .Vt struct manpaths
 from
-.Pa manconf.h
+.Qq Pa manconf.h
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include
-.Pa out.h ,
-.Pa term.h ,
+.Qq Pa out.h ,
+.Qq Pa term.h ,
+.Qq Pa tab_term.h ,
 or
-.Pa html.h .
+.Qq Pa html.h .
 .El