===================================================================
RCS file: /cvs/mandoc/mandoc_headers.3,v
retrieving revision 1.1
retrieving revision 1.33
diff -u -p -r1.1 -r1.33
--- mandoc/mandoc_headers.3	2014/12/01 08:09:26	1.1
+++ mandoc/mandoc_headers.3	2020/03/13 15:32:28	1.33
@@ -1,4 +1,20 @@
-.Dd December 1, 2014
+.\"	$Id: mandoc_headers.3,v 1.33 2020/03/13 15:32:28 schwarze Exp $
+.\"
+.\" Copyright (c) 2014-2020 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: March 13 2020 $
 .Dt MANDOC_HEADERS 3
 .Os
 .Sh NAME
@@ -25,15 +41,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,78 +61,208 @@ terminal formatters
 HTML formatters
 .It
 search tools
+.It
+main programs
 .El
 .Pp
-Note that mere usage of an opaque type does
+Note that mere usage of an opaque struct type does
 .Em not
 require inclusion of the header where that type is defined.
 .Ss Parser interface
 Each of the following headers can be included without including
 any other mandoc header.
 These headers should be included before any other mandoc headers.
-Afterwards, any other mandoc headers can be included as needed.
 .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, escape sequence, and character utilities;
+can be used everywhere.
+.Pp
 Requires
 .In sys/types.h
 for
-.Vt size_t .
+.Vt size_t
+and
+.In stdio.h
+for
+.Vt FILE .
 .Pp
 Provides
 .Vt enum mandoc_esc ,
 .Vt enum mandocerr ,
 .Vt enum mandoclevel ,
+the function
+.Xr mandoc_escape 3 ,
+the functions described in
+.Xr mchars_alloc 3 ,
+and the
+.Fn mandoc_msg*
+functions.
+.It Qq Pa roff.h
+Common data types for all syntax trees and related functions;
+can be used everywhere.
+.Pp
+Provides
+.Vt enum mandoc_os ,
+.Vt enum mdoc_endbody ,
+.Vt enum roff_macroset ,
+.Vt enum roff_sec ,
+.Vt enum roff_tok ,
+.Vt enum roff_type ,
+.Vt struct roff_man ,
+.Vt struct roff_meta ,
+.Vt struct roff_node ,
+the constant array
+.Va roff_name
+and the function
+.Fn deroff .
+.Pp
+Uses pointers to the types
+.Vt struct ohash
+from
+.Qq Pa mandoc_ohash.h ,
+.Vt struct mdoc_arg
+and
+.Vt union mdoc_data
+from
+.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
+.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 enum eqn_boxt ,
-.Vt enum eqn_fontt ,
-.Vt enum eqn_pilet ,
-.Vt enum eqn_post ,
 .Vt struct tbl_opts ,
-.Vt struct tbl_head ,
 .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
-.Xr mandoc_escape 3 ,
-the functions described in
-.Xr mchars_alloc 3 ,
-and the functions
-.Fn mparse_*
-described in
-.Xr mandoc 3 .
+and
+.Vt struct tbl_span .
+.It Qq Pa eqn.h
+Data structures for the
+.Xr eqn 7
+parse tree; can be used everywhere.
 .Pp
-Uses the opaque types
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides
+.Vt enum eqn_boxt ,
+.Vt enum eqn_fontt ,
+.Vt enum eqn_post ,
+and
+.Vt struct eqn_box .
+.It Qq Pa mandoc_parse.h
+Top level parser interface, for use in the main program
+and in the main parser, but not in formatters.
+.Pp
+Requires
+.Qq Pa mandoc.h
+for
+.Vt enum mandocerr
+and
+.Vt enum mandoclevel
+and
+.Qq Pa roff.h
+for
+.Vt enum mandoc_os .
+.Pp
+Uses the opaque type
 .Vt struct mparse
 from
 .Pa read.c
-and
-.Vt struct mchars
-from
-.Pa chars.c
 for function prototypes.
-Uses the types
-.Vt struct mdoc
+Uses
+.Vt struct roff_meta
 from
-.Pa libmdoc.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
+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
-.Vt struct man
+.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
-.Pa libman.h
-as opaque types for function prototypes.
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.El
+.Pp
+The following two require
+.Qq Pa roff.h
+but no other mandoc headers.
+Afterwards, any other mandoc headers can be included as needed.
+.Bl -tag -width Ds
 .It Qq Pa mdoc.h
 Requires
 .In sys/types.h
@@ -124,218 +270,276 @@ for
 .Vt size_t .
 .Pp
 Provides
-.Vt enum mdoct ,
 .Vt enum mdocargt ,
-.Vt enum mdoc_type ,
-.Vt enum mdoc_sec ,
-.Vt enum mdoc_endbody ,
-.Vt enum mdoc_disp ,
-.Vt enum mdoc_list ,
 .Vt enum mdoc_auth ,
+.Vt enum mdoc_disp ,
 .Vt enum mdoc_font ,
-.Vt struct mdoc_meta ,
+.Vt enum mdoc_list ,
 .Vt struct mdoc_argv ,
 .Vt struct mdoc_arg ,
-.Vt struct mdoc_bd ,
-.Vt struct mdoc_bl ,
 .Vt struct mdoc_an ,
+.Vt struct mdoc_bd ,
 .Vt struct mdoc_bf ,
+.Vt struct mdoc_bl ,
 .Vt struct mdoc_rs ,
-.Vt struct mdoc_node ,
+.Vt union mdoc_data ,
 and the functions
 .Fn mdoc_*
 described in
 .Xr mandoc 3 .
 .Pp
-Uses the type
-.Vt struct mdoc
+Uses the types
+.Vt struct roff_node
 from
-.Pa libmdoc.h
-as an opaque type for function prototypes.
-Uses pointers to the types
-.Vt struct tbl_span
+.Qq Pa roff.h
 and
-.Vt struct eqn
-as opaque struct members.
+.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
-.Pa libman.h
-or
-.Pa libroff.h .
+internals of different parsers.
 .It Qq Pa man.h
-Provides
-.Vt enum mant ,
-.Vt enum man_type ,
-.Vt struct man_meta ,
-.Vt struct man_node ,
-and the functions
+Provides the functions
 .Fn man_*
 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 man
+.Vt struct roff_man
 from
-.Pa libman.h
+.Qq Pa roff.h
 as an opaque type for function prototypes.
-Uses pointers to the types
-.Vt struct tbl_span
-and
-.Vt struct eqn
-as opaque struct members.
 .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
-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.
+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
+not include any formatter headers.
 .Bl -tag -width Ds
 .It Qq Pa libmandoc.h
 Requires
 .In sys/types.h
 for
-.Vt size_t .
+.Vt size_t
+and
+.Qq Pa mandoc.h
+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.
 .Pp
-Uses the opaque types
-.Vt struct mparse
-from
-.Pa read.c
-and
+Uses the opaque type
 .Vt struct roff
 from
 .Pa roff.c
 for function prototypes.
+Uses the type
+.Vt struct roff_man
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.It Qq Pa roff_int.h
+Parser internals shared by multiple parsers.
+Can be used in all parsers, but not in main programs or formatters.
+.Pp
+Requires
+.Qq Pa roff.h
+for
+.Vt enum roff_type
+and
+.Vt enum roff_tok .
+.Pp
+Provides
+.Vt enum roff_next ,
+.Vt struct roff_man ,
+functions named
+.Fn roff_*
+to handle roff nodes,
+.Fn roffhash_alloc ,
+.Fn roffhash_find ,
+.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
+.Pa roff.c .
+.Pp
 Uses the types
-.Vt enum mandocerr ,
-.Vt struct tbl_span ,
+.Vt struct ohash
+from
+.Qq Pa mandoc_ohash.h ,
+.Vt struct roff_node
 and
-.Vt struct eqn
+.Vt struct roff_meta
 from
-.Pa mandoc.h ,
-.Vt struct mdoc
+.Qq Pa roff.h ,
+.Vt struct roff
 from
-.Pa libmdoc.h ,
+.Pa roff.c ,
 and
-.Vt struct man
+.Vt struct mdoc_arg
 from
-.Pa libman.h
+.Qq Pa mdoc.h
 as opaque types for function prototypes.
 .It Qq Pa libmdoc.h
 Requires
-.Qq Pa mdoc.h
+.Qq Pa roff.h
 for
-.Vt enum mdoct ,
-.Vt enum mdoc_* ,
+.Vt enum roff_tok
 and
-.Vt struct mdoc_* .
+.Vt enum roff_sec .
 .Pp
 Provides
-.Vt enum mdoc_next ,
 .Vt enum margserr ,
 .Vt enum mdelim ,
-.Vt struct mdoc ,
 .Vt struct mdoc_macro ,
 and many functions internal to the
 .Xr mdoc 7
 parser.
 .Pp
-Uses the opaque types
-.Vt struct mparse
+Uses the types
+.Vt struct roff_node
 from
-.Pa read.c
+.Qq Pa roff.h ,
+.Vt struct roff_man
+from
+.Qq Pa roff_int.h ,
 and
-.Vt struct roff
+.Vt struct mdoc_arg
 from
-.Pa roff.c .
+.Qq Pa mdoc.h
+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 man.h
+.Qq Pa roff.h
 for
-.Vt enum mant
-and
-.Vt struct man_node.
+.Vt enum roff_tok .
 .Pp
 Provides
-.Vt enum man_next ,
-.Vt struct man ,
-.Vt struct man_macro ,
-and many functions internal to the
+.Vt struct man_macro
+and some functions internal to the
 .Xr man 7
 parser.
 .Pp
-Uses the opaque types
-.Vt struct mparse
+Uses the types
+.Vt struct roff_node
 from
-.Pa read.c
+.Qq Pa roff.h
 and
-.Vt struct roff
+.Vt struct roff_man
 from
-.Pa roff.c .
+.Qq Pa roff_int.h
+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_new ,
+.Fn eqn_box_free ,
+.Fn eqn_free ,
+.Fn eqn_parse ,
+.Fn eqn_read ,
+and
+.Fn eqn_reset .
+.Pp
+Uses the type
+.Vt struct eqn_box
+from
 .Qq Pa mandoc.h
-for
-.Vt struct tbl_*
+as an opaque type for function prototypes.
+Uses the types
+.Vt struct roff_node
+from
+.Qq Pa roff.h
 and
-.Vt struct eqn ,
+.Vt struct eqn_def
+from
+.Pa eqn.c
+as opaque struct members.
+.Pp
+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
-.Qq Pa libmandoc.h
+.Xr tbl 7
+parsers only.
+.Pp
+Provides the functions documented in
+.Xr tbl 3 .
+.Pp
+Uses the types
+.Vt struct tbl_span
+from
+.Qq Pa tbl.h
+and
+.Vt struct tbl_node
+from
+.Qq Pa tbl_int.h
+as opaque types for function prototypes.
+.Pp
+When this header is included, the same file should not include
+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 enum rofferr .
+.Vt struct tbl_opts .
 .Pp
 Provides
 .Vt enum tbl_part ,
 .Vt struct tbl_node ,
-.Vt struct eqn_def ,
-.Vt struct eqn_node ,
-and many functions internal to the
-.Xr tbl 7
+and the functions
+.Fn tbl_option ,
+.Fn tbl_layout ,
+.Fn tbl_data ,
+.Fn tbl_cdata ,
 and
-.Xr eqn 7
-parsers.
+.Fn tbl_reset .
 .Pp
-Uses the opaque type
-.Vt struct mparse
-from
-.Pa read.c .
-.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 .
+interfaces of different parsers.
 .El
 .Ss Formatter interface
 These headers should be included after any parser interface headers.
@@ -359,13 +563,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 manpath.h
-or
-.Pa mansearch.h .
+.Qq Pa mansearch.h .
 .It Qq Pa term.h
 Requires
 .In sys/types.h
@@ -384,37 +586,69 @@ Provides
 .Vt enum termtype ,
 .Vt struct termp_tbl ,
 .Vt struct termp ,
+.Fn roff_term_pre ,
 and many terminal formatting functions.
 .Pp
-Uses the opaque types
-.Vt struct mchars
-from
-.Pa chars.c
-and
+Uses the opaque type
 .Vt struct termp_ps
 from
 .Pa term_ps.c .
 Uses
 .Vt struct tbl_span
 and
-.Vt struct eqn
+.Vt struct eqn_box
 from
-.Pa mandoc.h
+.Qq Pa mandoc.h
+and
+.Vt struct roff_meta
+and
+.Vt struct roff_node
+from
+.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 ,
-.Pa manpath.h
+.Qq Pa html.h
 or
-.Pa mansearch.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 ,
-.In stdio.h
+.Qq Pa mandoc.h
 for
-.Dv BUFSIZ ,
+.Vt enum mandoc_esc ,
+.Qq Pa roff.h
+for
+.Vt enum roff_tok ,
 and
 .Qq Pa out.h
 for
@@ -430,53 +664,50 @@ Provides
 .Vt struct tagq ,
 .Vt struct htmlpair ,
 .Vt struct html ,
+.Fn roff_html_pre ,
 and many HTML formatting functions.
 .Pp
-Uses the opaque type
-.Vt struct mchars
+Uses
+.Vt struct tbl_span
+and
+.Vt struct eqn_box
 from
-.Pa chars.c .
+.Qq Pa mandoc.h
+and
+.Vt struct roff_node
+from
+.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 ,
-.Pa manpath.h
+.Qq Pa term.h ,
+.Qq Pa tab_term.h ,
 or
-.Pa mansearch.h .
+.Qq Pa mansearch.h .
 .It Qq Pa main.h
 Provides the top level steering functions for all formatters.
 .Pp
-Uses the opaque type
-.Vt struct mchars
+Uses the type
+.Vt struct roff_meta
 from
-.Pa chars.c .
-Uses the types
-.Vt struct mdoc
-from
-.Pa libmdoc.h
-and
-.Vt struct man
-from
-.Pa libman.h
-as opaque types for function prototypes.
-.It Qq Pa manpath.h
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.It Qq Pa manconf.h
 Requires
 .In sys/types.h
 for
 .Vt size_t .
 .Pp
 Provides
-.Vt struct manpaths
+.Vt struct manconf ,
+.Vt struct manpaths ,
+.Vt struct manoutput ,
 and the functions
-.Fn manpath_manconf ,
-.Fn manpath_parse ,
+.Fn manconf_parse ,
+.Fn manconf_output ,
+.Fn manconf_free ,
 and
-.Fn manpath_free .
-.Pp
-When this header is included, the same file should not include
-.Pa out.h ,
-.Pa term.h ,
-or
-.Pa html.h .
+.Fn manpath_base .
 .It Qq Pa mansearch.h
 Requires
 .In sys/types.h
@@ -492,20 +723,20 @@ Provides
 .Vt struct manpage ,
 .Vt struct mansearch ,
 and the functions
-.Fn mansearch_setup ,
-.Fn mansearch ,
+.Fn mansearch
 and
 .Fn mansearch_free .
 .Pp
 Uses
 .Vt struct manpaths
 from
-.Pa manpath.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