===================================================================
RCS file: /cvs/mandoc/mandoc_headers.3,v
retrieving revision 1.5
retrieving revision 1.32
diff -u -p -r1.5 -r1.32
--- mandoc/mandoc_headers.3	2015/04/02 22:48:17	1.5
+++ mandoc/mandoc_headers.3	2020/01/20 10:37:15	1.32
@@ -1,4 +1,20 @@
-.Dd December 1, 2014
+.\"	$Id: mandoc_headers.3,v 1.32 2020/01/20 10:37:15 schwarze Exp $
+.\"
+.\" Copyright (c) 2014-2019 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: January 20 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,6 +61,8 @@ terminal formatters
 HTML formatters
 .It
 search tools
+.It
+main programs
 .El
 .Pp
 Note that mere usage of an opaque struct type does
@@ -56,81 +74,164 @@ 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, 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 ,
-.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 .
-.Pp
-Uses the opaque types
-.Vt struct mparse
-from
-.Pa read.c
-and
-.Vt struct mchars
-from
-.Pa chars.c
-for function prototypes.
-Uses the types
-.Vt struct mdoc
-from
-.Pa libmdoc.h
-and
-.Vt struct man
-from
-.Pa libman.h
-as opaque types for function prototypes.
+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 ,
-and
-.Vt struct roff_node .
+.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
+.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 struct tbl_opts ,
+.Vt struct tbl_cell ,
+.Vt struct tbl_row ,
+.Vt struct tbl_dat ,
+and
+.Vt struct tbl_span .
+.It Qq Pa eqn.h
+Data structures for the
+.Xr eqn 7
+parse tree; can be used everywhere.
+.Pp
+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
+for function prototypes.
+Uses
+.Vt struct roff_meta
+from
+.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
+.Fn mandoc_xr_free .
 .El
 .Pp
 The following two require
@@ -142,85 +243,60 @@ Afterwards, any other mandoc headers can be included a
 Requires
 .In sys/types.h
 for
-.Vt size_t
-and
-.Qq Pa roff.h
-for
-.Vt enum roff_type .
+.Vt size_t .
 .Pp
 Provides
 .Vt enum mdocargt ,
-.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 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
-Requires
-.Qq Pa roff.h
-for
-.Vt enum roff_type .
-.Pp
-Provides
-.Vt struct man_meta
-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
@@ -233,131 +309,213 @@ 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 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 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 roff.h
 for
-.Vt struct roff_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.
@@ -381,11 +539,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
@@ -404,36 +562,42 @@ 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
+.Qq Pa html.h
 or
-.Pa mansearch.h .
+.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
@@ -449,33 +613,49 @@ 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
+.Qq Pa term.h
 or
-.Pa mansearch.h .
+.Qq Pa mansearch.h .
+.It Qq Pa tag.h
+Requires
+.In sys/types.h
+for
+.Vt size_t
+and
+.In limits.h
+for
+.Dv INT_MAX .
+.Pp
+Provides an interface to generate
+.Xr ctags 1
+files for the
+.Ic :t
+functionality mentioned in
+.Xr man 1 .
 .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.
+.Qq Pa roff.h
+as an opaque type for function prototypes.
 .It Qq Pa manconf.h
 Requires
 .In sys/types.h
@@ -489,8 +669,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,20 +687,19 @@ 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 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 ,
 or
-.Pa html.h .
+.Qq Pa html.h .
 .El