6 .Nd ordering of mandoc include files
8 To support a cleaner coding style, the mandoc header files do not
9 contain any include directives and do not guard against multiple
11 The application developer has to make sure that the headers are
12 included in a proper order, and that no header is included more
15 The headers and functions form three major groups:
16 .Sx Parser interface ,
17 .Sx Parser internals ,
19 .Sx Formatter interface .
21 Various rules are given below prohibiting the inclusion of certain
22 combinations of headers into the same file.
23 The intention is to keep the following functional components
24 separate from each other:
26 .Bl -dash -offset indent -compact
50 Note that mere usage of an opaque struct type does
52 require inclusion of the header where that type is defined.
54 Each of the following headers can be included without including
55 any other mandoc header.
56 These headers should be included before any other mandoc headers.
57 Afterwards, any other mandoc headers can be included as needed.
59 .It Qq Pa mandoc_aux.h
64 Provides the utility functions documented in
75 .Vt enum mandoclevel ,
91 the function prototype typedef
95 the functions described in
102 Uses the opaque types
110 for function prototypes.
119 as opaque types for function prototypes.
131 .Vt enum mdoc_endbody ,
136 .Vt struct mdoc_meta ,
137 .Vt struct mdoc_argv ,
138 .Vt struct mdoc_arg ,
144 .Vt struct mdoc_node ,
154 as an opaque type for function prototypes.
155 Uses pointers to the types
159 as opaque struct members.
161 When this header is included, the same file should not include
169 .Vt struct man_meta ,
170 .Vt struct man_node ,
180 for function prototypes.
185 as an opaque type for function prototypes.
186 Uses pointers to the types
190 as opaque struct members.
192 When this header is included, the same file should not include
198 The following headers require inclusion of a parser interface header
199 before they can be included. All parser interface headers should
200 precede all parser internal headers. When any parser internal headers
201 are included, the same file should not include any formatter headers.
203 .It Qq Pa libmandoc.h
216 utility functions needed by multiple parsers,
217 and the top-level functions to call the parsers.
219 Uses the opaque types
227 for function prototypes.
241 as opaque types for function prototypes.
256 .Vt struct mdoc_macro ,
257 and many functions internal to the
261 Uses the opaque types
270 When this header is included, the same file should not include
286 .Vt struct man_macro ,
287 and many functions internal to the
291 Uses the opaque types
300 When this header is included, the same file should not include
322 .Vt struct tbl_node ,
324 .Vt struct eqn_node ,
325 and many functions internal to the
336 When this header is included, the same file should not include
343 .Ss Formatter interface
344 These headers should be included after any parser interface headers.
345 No parser internal headers should be included by the same file.
366 as an opaque type for function prototypes.
368 When this header is included, the same file should not include
388 .Vt struct termp_tbl ,
390 and many terminal formatting functions.
392 Uses the opaque types
406 as opaque types for function prototypes.
408 When this header is included, the same file should not include
434 .Vt struct htmlpair ,
436 and many HTML formatting functions.
443 When this header is included, the same file should not include
449 Provides the top level steering functions for all formatters.
463 as opaque types for function prototypes.
473 .Fn manpath_manconf ,
478 When this header is included, the same file should not include
483 .It Qq Pa mansearch.h
496 .Vt struct mansearch ,
498 .Fn mansearch_setup ,
507 as an opaque type for function prototypes.
509 When this header is included, the same file should not include