-.Dd $Mdocdate: December 13 2018 $
+.\" $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
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 prototype typedef
-.Fn mandocmsg ,
the function
.Xr mandoc_escape 3 ,
-and the functions described in
-.Xr mchars_alloc 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.
.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 ,
.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
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
.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
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.
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
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
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.
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
+.Qq Pa roff.h ,
+.Vt struct roff
from
-.Pa roff.h
+.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
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
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
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
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
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
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
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
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
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
git.ckatri.com / mandoc.git / blobdiff