MANDOC_HEADERS(3) Library Functions Manual MANDOC_HEADERS(3)

NAME

mandoc_headersordering of mandoc include files

DESCRIPTION

To support a cleaner coding style, the mandoc header files do not contain any include directives and do not guard against multiple inclusion. The application developer has to make sure that the headers are included in a proper order, and that no header is included more than once.
The headers and functions form three major groups: Parser interface, Parser internals, and Formatter interface.
Various rules are given below prohibiting the inclusion of certain combinations of headers into the same file. The intention is to keep the following functional components separate from each other:
Note that mere usage of an opaque struct type does not require inclusion of the header where that type is defined.

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.
 
 
mandoc_aux.h
Requires <sys/types.h> for size_t. Provides the utility functions documented in mandoc_malloc(3).
 
 
mandoc_ohash.h
Includes <ohash.h> and provides mandoc_ohash_init().
 
 
mandoc.h
Requires <sys/types.h> for size_t.
Provides enum mandoc_esc, enum mandocerr, enum mandoclevel, enum tbl_cellt, enum tbl_datt, enum tbl_spant, enum eqn_boxt, enum eqn_fontt, enum eqn_pilet, enum eqn_post, struct tbl_opts, struct tbl_cell, struct tbl_row, struct tbl_dat, struct tbl_span, struct eqn_box, struct eqn, the function prototype typedef mandocmsg(), the function mandoc_escape(3), the functions described in mchars_alloc(3), and the functions mparse_*() described in mandoc(3).
Uses the opaque type struct mparse from read.c for function prototypes. Uses the type struct roff_man from roff.h as an opaque type for function prototypes.
 
 
roff.h
Provides enum mdoc_endbody, enum roff_macroset, enum roff_next, enum roff_sec, enum roff_type, struct roff_man, struct roff_meta, struct roff_node, and the function deroff().
Uses pointers to the types struct mdoc_arg and union mdoc_data from mdoc.h as opaque struct members.
The following two require “roff.h” but no other mandoc headers. Afterwards, any other mandoc headers can be included as needed.
 
 
mdoc.h
Requires <sys/types.h> for size_t.
Provides enum mdocargt, enum mdoc_auth, enum mdoc_disp, enum mdoc_font, enum mdoc_list, struct mdoc_argv, struct mdoc_arg, struct mdoc_an, struct mdoc_bd, struct mdoc_bf, struct mdoc_bl, struct mdoc_rs, union mdoc_data, and the functions mdoc_*() described in mandoc(3).
Uses the type struct roff_man from roff.h as an opaque type for function prototypes.
When this header is included, the same file should not include libman.h or libroff.h.
 
 
man.h
Provides the functions man_*() described in mandoc(3).
Uses the opaque type struct mparse from read.c for function prototypes. Uses the type struct roff_man from roff.h as an opaque type for function prototypes.
When this header is included, the same file should not include libmdoc.h or libroff.h.

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.
 
 
libmandoc.h
Requires <sys/types.h> for size_t and “mandoc.h” for enum mandocerr.
Provides enum rofferr, struct buf, utility functions needed by multiple parsers, and the top-level functions to call the parsers.
Uses the opaque types struct mparse from read.c and struct roff from roff.c for function prototypes. Uses the types struct tbl_span and struct eqn from mandoc.h and struct roff_man from roff.h as opaque types for function prototypes.
 
 
roff_int.h
Requires “roff.h” for enum roff_type.
Provides functions named roff_*() to handle roff nodes and the two special functions man_breakscope() and mdoc_argv_free() because the latter two are needed by “roff.c”.
Uses the types struct eqn and struct tbl_span from mandoc.h, struct roff_man and struct roff_node from roff.h, and struct mdoc_arg from mdoc.h as opaque types for function prototypes.
 
 
libmdoc.h
Requires “mdoc.h” for enum mdoc_* and struct mdoc_*.
Provides enum margserr, enum mdelim, struct mdoc_macro, and many functions internal to the mdoc(7) parser.
Uses the opaque type struct mparse from read.c. Uses the types struct roff_man and struct roff_node from roff.h as opaque types for function prototypes.
When this header is included, the same file should not include man.h, libman.h, or libroff.h.
 
 
libman.h
Provides struct man_macro and some functions internal to the man(7) parser.
Uses the types struct roff_man and struct roff_node from roff.h as opaque types for function prototypes.
When this header is included, the same file should not include mdoc.h, libmdoc.h, or libroff.h.
 
 
libroff.h
Requires <sys/types.h> for size_t, “mandoc.h” for struct tbl_* and struct eqn, and “libmandoc.h” for enum rofferr.
Provides enum tbl_part, struct tbl_node, struct eqn_def, struct eqn_node, and many functions internal to the tbl(7) and eqn(7) parsers.
Uses the opaque type struct mparse from read.c.
When this header is included, the same file should not include man.h, mdoc.h, libman.h, or libmdoc.h.

Formatter interface

These headers should be included after any parser interface headers. No parser internal headers should be included by the same file.
 
 
out.h
Requires <sys/types.h> for size_t.
Provides enum roffscale, struct roffcol, struct roffsu, struct rofftbl, a2roffsu(), and tblcalc().
Uses struct tbl_span from mandoc.h as an opaque type for function prototypes.
When this header is included, the same file should not include mansearch.h.
 
 
term.h
Requires <sys/types.h> for size_t and “out.h” for struct roffsu and struct rofftbl.
Provides enum termenc, enum termfont, enum termtype, struct termp_tbl, struct termp, and many terminal formatting functions.
Uses the opaque type struct termp_ps from term_ps.c. Uses struct tbl_span and struct eqn from mandoc.h and struct roff_meta from roff.h as opaque types for function prototypes.
When this header is included, the same file should not include html.h or mansearch.h.
 
 
html.h
Requires <sys/types.h> for size_t, <stdio.h> for BUFSIZ, and “out.h” for struct roffsu and struct rofftbl.
Provides enum htmltag, enum htmlattr, enum htmlfont, struct tag, struct tagq, struct htmlpair, struct html, and many HTML formatting functions.
When this header is included, the same file should not include term.h or mansearch.h.
 
 
tag.h
Requires <sys/types.h> for size_t.
Provides an interface to generate ctags(1) files for the :t functionality mentioned in man(1).
 
 
main.h
Provides the top level steering functions for all formatters.
Uses the type struct roff_man from roff.h as an opaque type for function prototypes.
 
 
manconf.h
Requires <sys/types.h> for size_t.
Provides struct manconf, struct manpaths, struct manoutput, and the functions manconf_parse(), manconf_output(), and manconf_free().
 
 
mansearch.h
Requires <sys/types.h> for size_t and <stdint.h> for uint64_t.
Provides enum argmode, struct manpage, struct mansearch, and the functions mansearch_setup(), mansearch(), and mansearch_free().
Uses struct manpaths from manconf.h as an opaque type for function prototypes.
When this header is included, the same file should not include out.h, term.h, or html.h.
December 1, 2014 OpenBSD 5.8