Fix incorrect file type tests.

[mandoc.git] / mandoc_headers.3

diff --git a/mandoc_headers.3 b/mandoc_headers.3
index 199f6dfc0af55568216275a611b06b620bbde1ee..1632b07ca4d3f6b39b42ffea0b3eecf0da327e66 100644 (file)
--- a/mandoc_headers.3
+++ b/mandoc_headers.3
@@ -1,4 +1,20 @@
-.Dd $Mdocdate: December 13 2018 $
+.\"    $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
 .Dt MANDOC_HEADERS 3
 .Os
 .Sh NAME


@@ -84,45 +100,65 @@ Includes
 and provides
 .Fn mandoc_ohash_init .
 .It Qq Pa mandoc.h
 and provides
 .Fn mandoc_ohash_init .
 .It Qq Pa mandoc.h

-Error handling utilities and top level parser interface;
+Error handling, escape sequence, and character utilities;

 can be used everywhere.
 .Pp
 Requires
 .In sys/types.h
 for
 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 ,
 .Pp
 Provides
 .Vt enum mandoc_esc ,
 .Vt enum mandocerr ,
 .Vt enum mandoclevel ,

-.Vt enum mandoc_os ,
-.Vt enum eqn_boxt ,
-.Vt enum eqn_fontt ,
-.Vt enum eqn_pilet ,
-.Vt enum eqn_post ,
-.Vt struct eqn_box ,
-the function prototype typedef
-.Fn mandocmsg ,

 the function
 .Xr mandoc_escape 3 ,
 the functions described in
 .Xr mchars_alloc 3 ,
 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 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
 .Pp

-Uses the opaque type
-.Vt struct mparse
+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
 from

-.Pa read.c
-for function prototypes.
-Uses the type
-.Vt struct roff_man
+.Qq Pa mandoc_ohash.h ,
+.Vt struct mdoc_arg
+and
+.Vt union mdoc_data

 from
 from

-.Pa roff.h
-as an opaque type for function prototypes.
+.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
 .It Qq Pa tbl.h
 Data structures for the
 .Xr tbl 7


@@ -143,55 +179,59 @@ Provides
 .Vt struct tbl_dat ,
 and
 .Vt struct tbl_span .
 .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.
+.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
 .Pp
 Provides

-.Vt struct mandoc_xr
-and the functions
-.Fn mandoc_xr_reset ,
-.Fn mandoc_xr_add ,
-.Fn mandoc_xr_get ,
+.Vt enum eqn_boxt ,
+.Vt enum eqn_fontt ,
+.Vt enum eqn_post ,

 and
 and

-.Fn mandoc_xr_free .
-.It Qq Pa roff.h
+.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
 Requires

-.Qq Pa mandoc_ohash.h
+.Qq Pa mandoc.h

 for
 for

-.Vt struct ohash
+.Vt enum mandocerr

 and
 and

-.Qq Pa mandoc.h
+.Vt enum mandoclevel
+and
+.Qq Pa roff.h

 for
 .Vt enum mandoc_os .
 .Pp
 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
 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
+.Vt struct mandoc_xr

 and the functions
 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
+.Fn mandoc_xr_reset ,
+.Fn mandoc_xr_add ,
+.Fn mandoc_xr_get ,

 and
 and

-.Vt union mdoc_data
-from
-.Pa mdoc.h
-as opaque struct members.
+.Fn mandoc_xr_free .

 .El
 .Pp
 The following two require
 .El
 .Pp
 The following two require


@@ -224,11 +264,15 @@ and the functions
 described in
 .Xr mandoc 3 .
 .Pp
 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
 .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.
 .Pp
 When this header is included, the same file should not include
 internals of different parsers.


@@ -238,15 +282,10 @@ Provides the functions
 described in
 .Xr mandoc 3 .
 .Pp
 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
 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
 as an opaque type for function prototypes.
 .Pp
 When this header is included, the same file should not include


@@ -274,11 +313,7 @@ Provides
 utility functions needed by multiple parsers,
 and the top-level functions to call the parsers.
 .Pp
 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
 .Vt struct roff
 from
 .Pa roff.c


@@ -286,33 +321,53 @@ for function prototypes.
 Uses the type
 .Vt struct roff_man
 from
 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
 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
 Requires
 .Qq Pa roff.h
 for

-.Vt enum roff_type .
+.Vt enum roff_type
+and
+.Vt enum roff_tok .

 .Pp
 .Pp

-Provides functions named
+Provides
+.Vt enum roff_next ,
+.Vt struct roff_man ,
+functions named

 .Fn roff_*
 .Fn roff_*

-to handle roff nodes and the two special functions
+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
 .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
 .Pp
 Uses the types

-.Vt struct roff_man
-and
+.Vt struct ohash
+from
+.Qq Pa mandoc_ohash.h ,

 .Vt struct roff_node
 .Vt struct roff_node

+and
+.Vt struct roff_meta
+from
+.Qq Pa roff.h ,
+.Vt struct roff

 from
 from

-.Pa roff.h
+.Pa roff.c ,

 and
 .Vt struct mdoc_arg
 from
 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
 as opaque types for function prototypes.
 .It Qq Pa libmdoc.h
 Requires


@@ -320,11 +375,7 @@ Requires
 for
 .Vt enum roff_tok
 and
 for
 .Vt enum roff_tok
 and

-.Qq Pa mdoc.h
-for
-.Vt enum mdoc_*
-and
-.Vt struct mdoc_* .
+.Vt enum roff_sec .

 .Pp
 Provides
 .Vt enum margserr ,
 .Pp
 Provides
 .Vt enum margserr ,


@@ -334,16 +385,17 @@ and many functions internal to the
 .Xr mdoc 7
 parser.
 .Pp
 .Xr mdoc 7
 parser.
 .Pp

-Uses the opaque type
-.Vt struct mparse
-from
-.Pa read.c .

 Uses the types
 Uses the types

+.Vt struct roff_node
+from
+.Qq Pa roff.h ,

 .Vt struct roff_man
 .Vt struct roff_man

+from
+.Qq Pa roff_int.h ,

 and
 and

-.Vt struct roff_node
+.Vt struct mdoc_arg

 from
 from

-.Pa roff.h
+.Qq Pa mdoc.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


@@ -361,11 +413,13 @@ and some functions internal to the
 parser.
 .Pp
 Uses the types
 parser.
 .Pp
 Uses the types

-.Vt struct roff_man
-and

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


@@ -388,6 +442,7 @@ Provides
 .Vt struct eqn_node
 and the functions
 .Fn eqn_alloc ,
 .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_box_free ,
 .Fn eqn_free ,
 .Fn eqn_parse ,


@@ -395,20 +450,15 @@ and the functions
 and
 .Fn eqn_reset .
 .Pp
 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
 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
 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
 and
 .Vt struct eqn_def
 from


@@ -429,18 +479,14 @@ parsers only.
 Provides the functions documented in
 .Xr tbl 3 .
 .Pp
 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
 Uses the types
 .Vt struct tbl_span
 from

-.Pa tbl.h
+.Qq Pa tbl.h

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


@@ -468,12 +514,6 @@ and the functions
 and
 .Fn tbl_reset .
 .Pp
 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
 When this header is included, the same file should not include
 interfaces of different parsers.
 .El


@@ -499,11 +539,11 @@ and
 Uses
 .Vt struct tbl_span
 from
 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
 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
 .It Qq Pa term.h
 Requires
 .In sys/types.h


@@ -534,24 +574,30 @@ Uses
 and
 .Vt struct eqn_box
 from
 and
 .Vt struct eqn_box
 from

-.Pa mandoc.h
+.Qq Pa mandoc.h

 and
 .Vt struct roff_meta
 and
 .Vt struct roff_node
 from
 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
 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
 or

-.Pa mansearch.h .
+.Qq Pa mansearch.h .

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

-.Vt size_t
+.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
 and
 .Qq Pa out.h
 for


@@ -575,22 +621,26 @@ Uses
 and
 .Vt struct eqn_box
 from
 and
 .Vt struct eqn_box
 from

-.Pa mandoc.h
+.Qq Pa mandoc.h

 and
 .Vt struct roff_node
 from
 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
 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
 or

-.Pa mansearch.h .
+.Qq Pa mansearch.h .

 .It Qq Pa tag.h
 Requires
 .In sys/types.h
 for
 .It Qq Pa tag.h
 Requires
 .In sys/types.h
 for

-.Vt size_t .
+.Vt size_t
+and
+.In limits.h
+for
+.Dv INT_MAX .

 .Pp
 Provides an interface to generate
 .Xr ctags 1
 .Pp
 Provides an interface to generate
 .Xr ctags 1


@@ -602,9 +652,9 @@ functionality mentioned in
 Provides the top level steering functions for all formatters.
 .Pp
 Uses the type
 Provides the top level steering functions for all formatters.
 .Pp
 Uses the type

-.Vt struct roff_man
+.Vt struct roff_meta

 from
 from

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

 as an opaque type for function prototypes.
 .It Qq Pa manconf.h
 Requires
 as an opaque type for function prototypes.
 .It Qq Pa manconf.h
 Requires


@@ -644,12 +694,12 @@ and
 Uses
 .Vt struct manpaths
 from
 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
 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
 or

-.Pa html.h .
+.Qq Pa html.h .

 .El
 .El