1.Dd December 1, 2014 2.Dt MANDOC_HEADERS 3 3.Os 4.Sh NAME 5.Nm mandoc_headers 6.Nd ordering of mandoc include files 7.Sh DESCRIPTION 8To support a cleaner coding style, the mandoc header files do not 9contain any include directives and do not guard against multiple 10inclusion. 11The application developer has to make sure that the headers are 12included in a proper order, and that no header is included more 13than once. 14.Pp 15The headers and functions form three major groups: 16.Sx Parser interface , 17.Sx Parser internals , 18and 19.Sx Formatter interface . 20.Pp 21Various rules are given below prohibiting the inclusion of certain 22combinations of headers into the same file. 23The intention is to keep the following functional components 24separate from each other: 25.Pp 26.Bl -dash -offset indent -compact 27.It 28.Xr mdoc 7 29parser 30.It 31.Xr man 7 32parser 33.It 34.Xr roff 7 35parser 36.It 37.Xr tbl 7 38parser 39.It 40.Xr eqn 7 41parser 42.It 43terminal formatters 44.It 45HTML formatters 46.It 47search tools 48.El 49.Pp 50Note that mere usage of an opaque struct type does 51.Em not 52require inclusion of the header where that type is defined. 53.Ss Parser interface 54Each of the following headers can be included without including 55any other mandoc header. 56These headers should be included before any other mandoc headers. 57Afterwards, any other mandoc headers can be included as needed. 58.Bl -tag -width Ds 59.It Qq Pa mandoc_aux.h 60Requires 61.In sys/types.h 62for 63.Vt size_t . 64Provides the utility functions documented in 65.Xr mandoc_malloc 3 . 66.It Qq Pa mandoc.h 67Requires 68.In sys/types.h 69for 70.Vt size_t . 71.Pp 72Provides 73.Vt enum mandoc_esc , 74.Vt enum mandocerr , 75.Vt enum mandoclevel , 76.Vt enum tbl_cellt , 77.Vt enum tbl_datt , 78.Vt enum tbl_spant , 79.Vt enum eqn_boxt , 80.Vt enum eqn_fontt , 81.Vt enum eqn_pilet , 82.Vt enum eqn_post , 83.Vt struct tbl_opts , 84.Vt struct tbl_head , 85.Vt struct tbl_cell , 86.Vt struct tbl_row , 87.Vt struct tbl_dat , 88.Vt struct tbl_span , 89.Vt struct eqn_box , 90.Vt struct eqn , 91the function prototype typedef 92.Fn mandocmsg , 93the function 94.Xr mandoc_escape 3 , 95the functions described in 96.Xr mchars_alloc 3 , 97and the functions 98.Fn mparse_* 99described in 100.Xr mandoc 3 . 101.Pp 102Uses the opaque types 103.Vt struct mparse 104from 105.Pa read.c 106and 107.Vt struct mchars 108from 109.Pa chars.c 110for function prototypes. 111Uses the types 112.Vt struct mdoc 113from 114.Pa libmdoc.h 115and 116.Vt struct man 117from 118.Pa libman.h 119as opaque types for function prototypes. 120.It Qq Pa mdoc.h 121Requires 122.In sys/types.h 123for 124.Vt size_t . 125.Pp 126Provides 127.Vt enum mdoct , 128.Vt enum mdocargt , 129.Vt enum mdoc_type , 130.Vt enum mdoc_sec , 131.Vt enum mdoc_endbody , 132.Vt enum mdoc_disp , 133.Vt enum mdoc_list , 134.Vt enum mdoc_auth , 135.Vt enum mdoc_font , 136.Vt struct mdoc_meta , 137.Vt struct mdoc_argv , 138.Vt struct mdoc_arg , 139.Vt struct mdoc_bd , 140.Vt struct mdoc_bl , 141.Vt struct mdoc_an , 142.Vt struct mdoc_bf , 143.Vt struct mdoc_rs , 144.Vt struct mdoc_node , 145and the functions 146.Fn mdoc_* 147described in 148.Xr mandoc 3 . 149.Pp 150Uses the type 151.Vt struct mdoc 152from 153.Pa libmdoc.h 154as an opaque type for function prototypes. 155Uses pointers to the types 156.Vt struct tbl_span 157and 158.Vt struct eqn 159as opaque struct members. 160.Pp 161When this header is included, the same file should not include 162.Pa libman.h 163or 164.Pa libroff.h . 165.It Qq Pa man.h 166Provides 167.Vt enum mant , 168.Vt enum man_type , 169.Vt struct man_meta , 170.Vt struct man_node , 171and the functions 172.Fn man_* 173described in 174.Xr mandoc 3 . 175.Pp 176Uses the opaque type 177.Vt struct mparse 178from 179.Pa read.c 180for function prototypes. 181Uses the type 182.Vt struct man 183from 184.Pa libman.h 185as an opaque type for function prototypes. 186Uses pointers to the types 187.Vt struct tbl_span 188and 189.Vt struct eqn 190as opaque struct members. 191.Pp 192When this header is included, the same file should not include 193.Pa libmdoc.h 194or 195.Pa libroff.h . 196.El 197.Ss Parser internals 198The following headers require inclusion of a parser interface header 199before they can be included. All parser interface headers should 200precede all parser internal headers. When any parser internal headers 201are included, the same file should not include any formatter headers. 202.Bl -tag -width Ds 203.It Qq Pa libmandoc.h 204Requires 205.In sys/types.h 206for 207.Vt size_t 208and 209.Qq Pa mandoc.h 210for 211.Vt enum mandocerr . 212.Pp 213Provides 214.Vt enum rofferr , 215.Vt struct buf , 216utility functions needed by multiple parsers, 217and the top-level functions to call the parsers. 218.Pp 219Uses the opaque types 220.Vt struct mparse 221from 222.Pa read.c 223and 224.Vt struct roff 225from 226.Pa roff.c 227for function prototypes. 228Uses the types 229.Vt struct tbl_span 230and 231.Vt struct eqn 232from 233.Pa mandoc.h , 234.Vt struct mdoc 235from 236.Pa libmdoc.h , 237and 238.Vt struct man 239from 240.Pa libman.h 241as opaque types for function prototypes. 242.It Qq Pa libmdoc.h 243Requires 244.Qq Pa mdoc.h 245for 246.Vt enum mdoct , 247.Vt enum mdoc_* , 248and 249.Vt struct mdoc_* . 250.Pp 251Provides 252.Vt enum mdoc_next , 253.Vt enum margserr , 254.Vt enum mdelim , 255.Vt struct mdoc , 256.Vt struct mdoc_macro , 257and many functions internal to the 258.Xr mdoc 7 259parser. 260.Pp 261Uses the opaque types 262.Vt struct mparse 263from 264.Pa read.c 265and 266.Vt struct roff 267from 268.Pa roff.c . 269.Pp 270When this header is included, the same file should not include 271.Pa man.h , 272.Pa libman.h , 273or 274.Pa libroff.h . 275.It Qq Pa libman.h 276Requires 277.Qq Pa man.h 278for 279.Vt enum mant 280and 281.Vt struct man_node. 282.Pp 283Provides 284.Vt enum man_next , 285.Vt struct man , 286.Vt struct man_macro , 287and many functions internal to the 288.Xr man 7 289parser. 290.Pp 291Uses the opaque types 292.Vt struct mparse 293from 294.Pa read.c 295and 296.Vt struct roff 297from 298.Pa roff.c . 299.Pp 300When this header is included, the same file should not include 301.Pa mdoc.h , 302.Pa libmdoc.h , 303or 304.Pa libroff.h . 305.It Qq Pa libroff.h 306Requires 307.In sys/types.h 308for 309.Vt size_t , 310.Qq Pa mandoc.h 311for 312.Vt struct tbl_* 313and 314.Vt struct eqn , 315and 316.Qq Pa libmandoc.h 317for 318.Vt enum rofferr . 319.Pp 320Provides 321.Vt enum tbl_part , 322.Vt struct tbl_node , 323.Vt struct eqn_def , 324.Vt struct eqn_node , 325and many functions internal to the 326.Xr tbl 7 327and 328.Xr eqn 7 329parsers. 330.Pp 331Uses the opaque type 332.Vt struct mparse 333from 334.Pa read.c . 335.Pp 336When this header is included, the same file should not include 337.Pa man.h , 338.Pa mdoc.h , 339.Pa libman.h , 340or 341.Pa libmdoc.h . 342.El 343.Ss Formatter interface 344These headers should be included after any parser interface headers. 345No parser internal headers should be included by the same file. 346.Bl -tag -width Ds 347.It Qq Pa out.h 348Requires 349.In sys/types.h 350for 351.Vt size_t . 352.Pp 353Provides 354.Vt enum roffscale , 355.Vt struct roffcol , 356.Vt struct roffsu , 357.Vt struct rofftbl , 358.Fn a2roffsu , 359and 360.Fn tblcalc . 361.Pp 362Uses 363.Vt struct tbl_span 364from 365.Pa mandoc.h 366as an opaque type for function prototypes. 367.Pp 368When this header is included, the same file should not include 369.Pa manpath.h 370or 371.Pa mansearch.h . 372.It Qq Pa term.h 373Requires 374.In sys/types.h 375for 376.Vt size_t 377and 378.Qq Pa out.h 379for 380.Vt struct roffsu 381and 382.Vt struct rofftbl . 383.Pp 384Provides 385.Vt enum termenc , 386.Vt enum termfont , 387.Vt enum termtype , 388.Vt struct termp_tbl , 389.Vt struct termp , 390and many terminal formatting functions. 391.Pp 392Uses the opaque types 393.Vt struct mchars 394from 395.Pa chars.c 396and 397.Vt struct termp_ps 398from 399.Pa term_ps.c . 400Uses 401.Vt struct tbl_span 402and 403.Vt struct eqn 404from 405.Pa mandoc.h 406as opaque types for function prototypes. 407.Pp 408When this header is included, the same file should not include 409.Pa html.h , 410.Pa manpath.h 411or 412.Pa mansearch.h . 413.It Qq Pa html.h 414Requires 415.In sys/types.h 416for 417.Vt size_t , 418.In stdio.h 419for 420.Dv BUFSIZ , 421and 422.Qq Pa out.h 423for 424.Vt struct roffsu 425and 426.Vt struct rofftbl . 427.Pp 428Provides 429.Vt enum htmltag , 430.Vt enum htmlattr , 431.Vt enum htmlfont , 432.Vt struct tag , 433.Vt struct tagq , 434.Vt struct htmlpair , 435.Vt struct html , 436and many HTML formatting functions. 437.Pp 438Uses the opaque type 439.Vt struct mchars 440from 441.Pa chars.c . 442.Pp 443When this header is included, the same file should not include 444.Pa term.h , 445.Pa manpath.h 446or 447.Pa mansearch.h . 448.It Qq Pa main.h 449Provides the top level steering functions for all formatters. 450.Pp 451Uses the opaque type 452.Vt struct mchars 453from 454.Pa chars.c . 455Uses the types 456.Vt struct mdoc 457from 458.Pa libmdoc.h 459and 460.Vt struct man 461from 462.Pa libman.h 463as opaque types for function prototypes. 464.It Qq Pa manpath.h 465Requires 466.In sys/types.h 467for 468.Vt size_t . 469.Pp 470Provides 471.Vt struct manpaths 472and the functions 473.Fn manpath_manconf , 474.Fn manpath_parse , 475and 476.Fn manpath_free . 477.Pp 478When this header is included, the same file should not include 479.Pa out.h , 480.Pa term.h , 481or 482.Pa html.h . 483.It Qq Pa mansearch.h 484Requires 485.In sys/types.h 486for 487.Vt size_t 488and 489.In stdint.h 490for 491.Vt uint64_t . 492.Pp 493Provides 494.Vt enum argmode , 495.Vt struct manpage , 496.Vt struct mansearch , 497and the functions 498.Fn mansearch_setup , 499.Fn mansearch , 500and 501.Fn mansearch_free . 502.Pp 503Uses 504.Vt struct manpaths 505from 506.Pa manpath.h 507as an opaque type for function prototypes. 508.Pp 509When this header is included, the same file should not include 510.Pa out.h , 511.Pa term.h , 512or 513.Pa html.h . 514.El 515