MANDOC_HEADERS(3)					   BSD Library Functions Manual 					 MANDOC_HEADERS(3)

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:

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

     Note that mere usage of an opaque 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.  Afterwards, any other mandoc headers can be included as needed.

     "mandoc_aux.h"
	     Requires <sys/types.h> for size_t.  Provides the utility functions documented in mandoc_malloc(3).

     "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_head, 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 types struct mparse from read.c and struct mchars from chars.c for function prototypes.  Uses the types struct mdoc
	     from libmdoc.h and struct man from libman.h as opaque types for function prototypes.

     "mdoc.h"
	     Requires <sys/types.h> for size_t.

	     Provides enum mdoct, enum mdocargt, enum mdoc_type, enum mdoc_sec, enum mdoc_endbody, enum mdoc_disp, enum mdoc_list, enum mdoc_auth,
	     enum mdoc_font, struct mdoc_meta, struct mdoc_argv, struct mdoc_arg, struct mdoc_bd, struct mdoc_bl, struct mdoc_an, struct mdoc_bf,
	     struct mdoc_rs, struct mdoc_node, and the functions mdoc_*() described in mandoc(3).

	     Uses the type struct mdoc from libmdoc.h as an opaque type for function prototypes.  Uses pointers to the types struct tbl_span and
	     struct eqn as opaque struct members.

	     When this header is included, the same file should not include libman.h or libroff.h.

     "man.h"
	     Provides enum mant, enum man_type, struct man_meta, struct man_node, and the functions man_*() described in mandoc(3).

	     Uses the opaque type struct mparse from read.c for function prototypes.  Uses the type struct man from libman.h as an opaque type for
	     function prototypes.  Uses pointers to the types struct tbl_span and struct eqn as opaque struct members.

	     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 pre-
     cede 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.

	     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 enum mandocerr,
	     struct tbl_span, and struct eqn from mandoc.h, struct mdoc from libmdoc.h, and struct man from libman.h as opaque types for function
	     prototypes.

     "libmdoc.h"
	     Requires "mdoc.h" for enum mdoct, enum mdoc_*, and struct mdoc_*.

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

	     Uses the opaque types struct mparse from read.c and struct roff from roff.c.

	     When this header is included, the same file should not include man.h, libman.h, or libroff.h.

     "libman.h"
	     Requires "man.h" for enum mant and struct man_node.

	     Provides enum man_next, struct man, struct man_macro, and many functions internal to the man(7) parser.

	     Uses the opaque types struct mparse from read.c and struct roff from roff.c.

	     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 manpath.h or 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 types struct mchars from chars.c and struct termp_ps from term_ps.c.  Uses struct tbl_span and struct eqn from
	     mandoc.h as opaque types for function prototypes.

	     When this header is included, the same file should not include html.h, manpath.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.

	     Uses the opaque type struct mchars from chars.c.

	     When this header is included, the same file should not include term.h, manpath.h or mansearch.h.

     "main.h"
	     Provides the top level steering functions for all formatters.

	     Uses the opaque type struct mchars from chars.c.  Uses the types struct mdoc from libmdoc.h and struct man from libman.h as opaque
	     types for function prototypes.

     "manpath.h"
	     Requires <sys/types.h> for size_t.

	     Provides struct manpaths and the functions manpath_manconf(), manpath_parse(), and manpath_free().

	     When this header is included, the same file should not include out.h, term.h, or html.h.

     "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 manpath.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.

BSD
								 December 1, 2014							       BSD