When checking the validity of cross references with -Tlint,

[mandoc.git] / mandoc_headers.3

diff --git a/mandoc_headers.3 b/mandoc_headers.3
index aa8754e46ec8f4bdeab1d18949a952b42782afd6..e964aeced837d00a5e310aded44a4327684be556 100644 (file)
--- a/mandoc_headers.3
+++ b/mandoc_headers.3
@@ -47,22 +47,36 @@ HTML formatters
 search tools
 .El
 .Pp
 search tools
 .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.
 .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
 Requires
 .In sys/types.h
 for
 .Vt size_t .
 .Bl -tag -width Ds
 .It Qq Pa mandoc_aux.h
 Requires
 .In sys/types.h
 for
 .Vt size_t .

+.Pp

 Provides the utility functions documented in
 .Xr mandoc_malloc 3 .
 Provides the utility functions documented in
 .Xr mandoc_malloc 3 .

+.It Qq Pa mandoc_ohash.h
+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
 Requires
 .In sys/types.h
 .It Qq Pa mandoc.h
 Requires
 .In sys/types.h


@@ -73,6 +87,7 @@ Provides
 .Vt enum mandoc_esc ,
 .Vt enum mandocerr ,
 .Vt enum mandoclevel ,
 .Vt enum mandoc_esc ,
 .Vt enum mandocerr ,
 .Vt enum mandoclevel ,

+.Vt enum mandoc_os ,

 .Vt enum tbl_cellt ,
 .Vt enum tbl_datt ,
 .Vt enum tbl_spant ,
 .Vt enum tbl_cellt ,
 .Vt enum tbl_datt ,
 .Vt enum tbl_spant ,


@@ -81,7 +96,6 @@ Provides
 .Vt enum eqn_pilet ,
 .Vt enum eqn_post ,
 .Vt struct tbl_opts ,
 .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_cell ,
 .Vt struct tbl_row ,
 .Vt struct tbl_dat ,


@@ -99,24 +113,69 @@ and the functions
 described in
 .Xr mandoc 3 .
 .Pp
 described in
 .Xr mandoc 3 .
 .Pp

-Uses the opaque types
+Uses the opaque type

 .Vt struct mparse
 from
 .Pa read.c
 .Vt struct mparse
 from
 .Pa read.c

-and
-.Vt struct mchars
-from
-.Pa chars.c

 for function prototypes.
 for function prototypes.

-Uses the types
-.Vt struct mdoc
+Uses the type
+.Vt struct roff_man

 from
 from

-.Pa libmdoc.h
+.Pa roff.h
+as an opaque type for function prototypes.
+.It Qq Pa mandoc_xr.h
+Provides
+.Vt struct mandoc_xr
+and the functions
+.Fn mandoc_xr_reset ,
+.Fn mandoc_xr_add ,
+.Fn mandoc_xr_get ,

 and
 and

-.Vt struct man
+.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 ,
+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
+and
+.Vt union mdoc_data

 from
 from

-.Pa libman.h
-as opaque types for function prototypes.
+.Pa mdoc.h
+as opaque struct members.
+.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
 .It Qq Pa mdoc.h
 Requires
 .In sys/types.h


@@ -124,51 +183,36 @@ for
 .Vt size_t .
 .Pp
 Provides
 .Vt size_t .
 .Pp
 Provides

-.Vt enum mdoct ,

 .Vt enum mdocargt ,
 .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_auth ,

+.Vt enum mdoc_disp ,

 .Vt enum mdoc_font ,
 .Vt enum mdoc_font ,

-.Vt struct mdoc_meta ,
+.Vt enum mdoc_list ,

 .Vt struct mdoc_argv ,
 .Vt struct mdoc_arg ,
 .Vt struct mdoc_argv ,
 .Vt struct mdoc_arg ,

-.Vt struct mdoc_bd ,
-.Vt struct mdoc_bl ,

 .Vt struct mdoc_an ,
 .Vt struct mdoc_an ,

+.Vt struct mdoc_bd ,

 .Vt struct mdoc_bf ,
 .Vt struct mdoc_bf ,

+.Vt struct mdoc_bl ,

 .Vt struct mdoc_rs ,
 .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
 and the functions
 .Fn mdoc_*
 described in
 .Xr mandoc 3 .
 .Pp
 Uses the type

-.Vt struct mdoc
+.Vt struct roff_man

 from
 from

-.Pa libmdoc.h
+.Pa roff.h

 as an opaque type for function prototypes.
 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 libman.h
 or
 .Pa libroff.h .
 .It Qq Pa man.h
 .Pp
 When this header is included, the same file should not include
 .Pa libman.h
 or
 .Pa libroff.h .
 .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 .
 .Fn man_*
 described in
 .Xr mandoc 3 .


@@ -179,15 +223,10 @@ from
 .Pa read.c
 for function prototypes.
 Uses the type
 .Pa read.c
 for function prototypes.
 Uses the type

-.Vt struct man
+.Vt struct roff_man

 from
 from

-.Pa libman.h
+.Pa roff.h

 as an opaque type for function prototypes.
 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
 .Pp
 When this header is included, the same file should not include
 .Pa libmdoc.h


@@ -196,15 +235,20 @@ or
 .El
 .Ss Parser internals
 The following headers require inclusion of a parser interface header
 .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
 .In sys/types.h
 for
 .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 ,
 .Pp
 Provides
 .Vt enum rofferr ,


@@ -222,47 +266,78 @@ from
 .Pa roff.c
 for function prototypes.
 Uses the types
 .Pa roff.c
 for function prototypes.
 Uses the types

-.Vt enum mandocerr ,
-.Vt struct tbl_span ,
+.Vt struct tbl_span

 and
 .Vt struct eqn
 from
 and
 .Vt struct eqn
 from

+.Pa mandoc.h
+and
+.Vt struct roff_man
+from
+.Pa roff.h
+as opaque types for function prototypes.
+.It Qq Pa roff_int.h
+Requires
+.Qq Pa roff.h
+for
+.Vt enum roff_type .
+.Pp
+Provides functions named
+.Fn roff_*
+to handle roff nodes and the two special functions
+.Fn man_breakscope
+and
+.Fn mdoc_argv_free
+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 ,
 .Pa mandoc.h ,

-.Vt struct mdoc
+.Vt struct roff_man
+and
+.Vt struct roff_node

 from
 from

-.Pa libmdoc.h ,
+.Pa roff.h ,

 and
 and

-.Vt struct man
+.Vt struct mdoc_arg

 from
 from

-.Pa libman.h
+.Pa mdoc.h

 as opaque types for function prototypes.
 .It Qq Pa libmdoc.h
 Requires
 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
 .Qq Pa mdoc.h
 for

-.Vt enum mdoct ,
-.Vt enum mdoc_* ,
+.Vt enum mdoc_*

 and
 .Vt struct mdoc_* .
 .Pp
 Provides
 and
 .Vt struct mdoc_* .
 .Pp
 Provides

-.Vt enum mdoc_next ,

 .Vt enum margserr ,
 .Vt enum mdelim ,
 .Vt enum margserr ,
 .Vt enum mdelim ,

-.Vt struct mdoc ,

 .Vt struct mdoc_macro ,
 and many functions internal to the
 .Xr mdoc 7
 parser.
 .Pp
 .Vt struct mdoc_macro ,
 and many functions internal to the
 .Xr mdoc 7
 parser.
 .Pp

-Uses the opaque types
+Uses the opaque type

 .Vt struct mparse
 from
 .Vt struct mparse
 from

-.Pa read.c
+.Pa read.c .
+Uses the types
+.Vt struct roff_man

 and
 and

-.Vt struct roff
+.Vt struct roff_node

 from
 from

-.Pa roff.c .
+.Pa roff.h
+as opaque types for function prototypes.

 .Pp
 When this header is included, the same file should not include
 .Pa man.h ,
 .Pp
 When this header is included, the same file should not include
 .Pa man.h ,


@@ -271,28 +346,23 @@ or
 .Pa libroff.h .
 .It Qq Pa libman.h
 Requires
 .Pa libroff.h .
 .It Qq Pa libman.h
 Requires

-.Qq Pa man.h
+.Qq Pa roff.h

 for
 for

-.Vt enum mant
-and
-.Vt struct man_node.
+.Vt enum roff_tok .

 .Pp
 Provides
 .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
 .Xr man 7
 parser.
 .Pp

-Uses the opaque types
-.Vt struct mparse
-from
-.Pa read.c
+Uses the types
+.Vt struct roff_man

 and
 and

-.Vt struct roff
+.Vt struct roff_node

 from
 from

-.Pa roff.c .
+.Pa roff.h
+as opaque types for function prototypes.

 .Pp
 When this header is included, the same file should not include
 .Pa mdoc.h ,
 .Pp
 When this header is included, the same file should not include
 .Pa mdoc.h ,


@@ -363,8 +433,6 @@ from
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include
 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 .
 .It Qq Pa term.h
 Requires
 .Pa mansearch.h .
 .It Qq Pa term.h
 Requires


@@ -384,13 +452,10 @@ Provides
 .Vt enum termtype ,
 .Vt struct termp_tbl ,
 .Vt struct termp ,
 .Vt enum termtype ,
 .Vt struct termp_tbl ,
 .Vt struct termp ,

+.Fn roff_term_pre ,

 and many terminal formatting functions.
 .Pp
 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 .
 .Vt struct termp_ps
 from
 .Pa term_ps.c .


@@ -400,21 +465,23 @@ and
 .Vt struct eqn
 from
 .Pa mandoc.h
 .Vt struct eqn
 from
 .Pa mandoc.h

+and
+.Vt struct roff_meta
+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
 as opaque types for function prototypes.
 .Pp
 When this header is included, the same file should not include

-.Pa html.h ,
-.Pa manpath.h
+.Pa html.h

 or
 .Pa mansearch.h .
 .It Qq Pa html.h
 Requires
 .In sys/types.h
 for
 or
 .Pa mansearch.h .
 .It Qq Pa html.h
 Requires
 .In sys/types.h
 for

-.Vt size_t ,
-.In stdio.h
-for
-.Dv BUFSIZ ,
+.Vt size_t

 and
 .Qq Pa out.h
 for
 and
 .Qq Pa out.h
 for


@@ -430,53 +497,61 @@ Provides
 .Vt struct tagq ,
 .Vt struct htmlpair ,
 .Vt struct html ,
 .Vt struct tagq ,
 .Vt struct htmlpair ,
 .Vt struct html ,

+.Fn roff_html_pre ,

 and many HTML formatting functions.
 .Pp
 and many HTML formatting functions.
 .Pp

-Uses the opaque type
-.Vt struct mchars
+Uses
+.Vt struct tbl_span
+and
+.Vt struct eqn

 from
 from

-.Pa chars.c .
+.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
 .Pp
 When this header is included, the same file should not include

-.Pa term.h ,
-.Pa manpath.h
+.Pa term.h

 or
 .Pa mansearch.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 .

 .It Qq Pa main.h
 Provides the top level steering functions for all formatters.
 .Pp
 .It Qq Pa main.h
 Provides the top level steering functions for all formatters.
 .Pp

-Uses the opaque type
-.Vt struct mchars
-from
-.Pa chars.c .
-Uses the types
-.Vt struct mdoc
-from
-.Pa libmdoc.h
-and
-.Vt struct man
+Uses the type
+.Vt struct roff_man

 from
 from

-.Pa libman.h
-as opaque types for function prototypes.
-.It Qq Pa manpath.h
+.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
 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
 and the functions

-.Fn manpath_manconf ,
-.Fn manpath_parse ,
+.Fn manconf_parse ,
+.Fn manconf_output ,
+.Fn manconf_free ,

 and
 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
 .It Qq Pa mansearch.h
 Requires
 .In sys/types.h


@@ -492,15 +567,14 @@ Provides
 .Vt struct manpage ,
 .Vt struct mansearch ,
 and the functions
 .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
 and
 .Fn mansearch_free .
 .Pp
 Uses
 .Vt struct manpaths
 from

-.Pa manpath.h
+.Pa manconf.h

 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include