NAME

mandoc_headers —

ordering 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:

roff(7) parser
mdoc(7) parser
man(7) parser
tbl(7) parser
eqn(7) parser
terminal formatters
HTML formatters
search tools
main programs

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”

Memory allocation utility functions; can be used everywhere.

Requires <sys/types.h> for size_t.

Provides the functions documented in mandoc_malloc(3).

“mandoc_ohash.h”

Hashing utility functions; can be used everywhere.

Requires <stddef.h> for ptrdiff_t and <stdint.h> for uint32_t.

Includes <ohash.h> and provides mandoc_ohash_init().

“mandoc.h”

Error handling, escape sequence, and character utilities; can be used everywhere.

Requires <sys/types.h> for size_t and <stdio.h> for FILE.

Provides enum mandoc_esc, enum mandocerr, enum mandoclevel, the function mandoc_escape(3), the functions described in mchars_alloc(3), and the mandoc_msg*() functions.

“roff.h”

Common data types for all syntax trees and related functions; can be used everywhere.

Provides enum mandoc_os, enum mdoc_endbody, enum roff_macroset, enum roff_sec, enum roff_tok, enum roff_type, struct roff_man, struct roff_meta, struct roff_node, the constant array roff_name and the function deroff().

Uses pointers to the types struct ohash from “mandoc_ohash.h”, struct mdoc_arg and union mdoc_data from “mdoc.h”, struct tbl_span from “tbl.h”, and struct eqn_box from “eqn.h” as opaque struct members.

“tbl.h”

Data structures for the tbl(7) parse tree; can be used everywhere.

Requires <sys/types.h> for size_t.

Provides enum tbl_cellt, enum tbl_datt, enum tbl_spant, struct tbl_opts, struct tbl_cell, struct tbl_row, struct tbl_dat, and struct tbl_span.

“eqn.h”

Data structures for the eqn(7) parse tree; can be used everywhere.

Requires <sys/types.h> for size_t.

Provides enum eqn_boxt, enum eqn_fontt, enum eqn_post, and struct eqn_box.

“mandoc_parse.h”

Top level parser interface, for use in the main program and in the main parser, but not in formatters.

Requires “mandoc.h” for enum mandocerr and enum mandoclevel and “roff.h” for enum mandoc_os.

Uses the opaque type struct mparse from read.c for function prototypes. Uses struct roff_meta from “roff.h” as an opaque type for function prototypes.

“mandoc_xr.h”

Cross reference validation; intended for use in the main program and in parsers, but not in formatters.

Provides struct mandoc_xr and the functions mandoc_xr_reset(), mandoc_xr_add(), mandoc_xr_get(), and mandoc_xr_free().

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 types struct roff_node from “roff.h” and struct roff_man from “roff_int.h” as opaque types for function prototypes.

When this header is included, the same file should not include internals of different parsers.

“man.h”

Provides the functions man_*() 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 internals of different parsers.

Parser internals

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.

“libmandoc.h”

Requires <sys/types.h> for size_t and “mandoc.h” for enum mandocerr.

Provides struct buf, utility functions needed by multiple parsers, and the top-level functions to call the parsers.

Uses the opaque type struct roff from roff.c for function prototypes. Uses the type struct roff_man from “roff.h” as an opaque type for function prototypes.

“roff_int.h”

Parser internals shared by multiple parsers. Can be used in all parsers, but not in main programs or formatters.

Requires “roff.h” for enum roff_type and enum roff_tok.

Provides enum roff_next, struct roff_man, functions named roff_*() to handle roff nodes, roffhash_alloc(), roffhash_find(), roffhash_free(), and roff_validate(), and the two special functions man_breakscope() and mdoc_argv_free() because the latter two are needed by roff.c.

Uses the types struct ohash from “mandoc_ohash.h”, struct roff_node and struct roff_meta from “roff.h”, struct roff from roff.c, and struct mdoc_arg from “mdoc.h” as opaque types for function prototypes.

“libmdoc.h”

Requires “roff.h” for enum roff_tok and enum roff_sec.

Provides enum margserr, enum mdelim, struct mdoc_macro, and many functions internal to the mdoc(7) parser.

Uses the types struct roff_node from “roff.h”, struct roff_man from “roff_int.h”, and struct mdoc_arg from “mdoc.h” as opaque types for function prototypes.

When this header is included, the same file should not include interfaces of different parsers.

“libman.h”

Requires “roff.h” for enum roff_tok.

Provides struct man_macro and some functions internal to the man(7) parser.

Uses the types struct roff_node from “roff.h” and struct roff_man from “roff_int.h” as opaque types for function prototypes.

When this header is included, the same file should not include interfaces of different parsers.

“eqn_parse.h”

External interface of the eqn(7) parser, for use in the roff(7) and eqn(7) parsers only.

Requires <sys/types.h> for size_t.

Provides struct eqn_node and the functions eqn_alloc(), eqn_box_new(), eqn_box_free(), eqn_free(), eqn_parse(), eqn_read(), and eqn_reset().

Uses the type struct eqn_box from “mandoc.h” as an opaque type for function prototypes. Uses the types struct roff_node from “roff.h” and struct eqn_def from eqn.c as opaque struct members.

When this header is included, the same file should not include internals of different parsers.

“tbl_parse.h”

External interface of the tbl(7) parser, for use in the roff(7) and tbl(7) parsers only.

Provides the functions documented in tbl(3).

Uses the types struct tbl_span from “tbl.h” and struct tbl_node from “tbl_int.h” as opaque types for function prototypes.

When this header is included, the same file should not include internals of different parsers.

“tbl_int.h”

Internal interfaces of the tbl(7) parser, for use inside the tbl(7) parser only.

Requires “tbl.h” for struct tbl_opts.

Provides enum tbl_part, struct tbl_node, and the functions tbl_option(), tbl_layout(), tbl_data(), tbl_cdata(), and tbl_reset().

When this header is included, the same file should not include interfaces of different parsers.

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, roff_term_pre(), and many terminal formatting functions.

Uses the opaque type struct termp_ps from term_ps.c. Uses struct tbl_span and struct eqn_box from “mandoc.h” and struct roff_meta and struct roff_node 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, “mandoc.h” for enum mandoc_esc, “roff.h” for enum roff_tok, and “out.h” for struct roffsu and struct rofftbl.

Provides enum htmltag, enum htmlattr, enum htmlfont, struct tag, struct tagq, struct htmlpair, struct html, roff_html_pre(), and many HTML formatting functions.

Uses struct tbl_span and struct eqn_box from “mandoc.h” and struct roff_node from “roff.h” as opaque types for function prototypes.

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_meta 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(), manconf_free(), and manpath_base().

“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() 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”.