mandoc_headers.3 revision 276219
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 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 . 208.Pp 209Provides 210.Vt enum rofferr , 211.Vt struct buf , 212utility functions needed by multiple parsers, 213and the top-level functions to call the parsers. 214.Pp 215Uses the opaque types 216.Vt struct mparse 217from 218.Pa read.c 219and 220.Vt struct roff 221from 222.Pa roff.c 223for function prototypes. 224Uses the types 225.Vt enum mandocerr , 226.Vt struct tbl_span , 227and 228.Vt struct eqn 229from 230.Pa mandoc.h , 231.Vt struct mdoc 232from 233.Pa libmdoc.h , 234and 235.Vt struct man 236from 237.Pa libman.h 238as opaque types for function prototypes. 239.It Qq Pa libmdoc.h 240Requires 241.Qq Pa mdoc.h 242for 243.Vt enum mdoct , 244.Vt enum mdoc_* , 245and 246.Vt struct mdoc_* . 247.Pp 248Provides 249.Vt enum mdoc_next , 250.Vt enum margserr , 251.Vt enum mdelim , 252.Vt struct mdoc , 253.Vt struct mdoc_macro , 254and many functions internal to the 255.Xr mdoc 7 256parser. 257.Pp 258Uses the opaque types 259.Vt struct mparse 260from 261.Pa read.c 262and 263.Vt struct roff 264from 265.Pa roff.c . 266.Pp 267When this header is included, the same file should not include 268.Pa man.h , 269.Pa libman.h , 270or 271.Pa libroff.h . 272.It Qq Pa libman.h 273Requires 274.Qq Pa man.h 275for 276.Vt enum mant 277and 278.Vt struct man_node. 279.Pp 280Provides 281.Vt enum man_next , 282.Vt struct man , 283.Vt struct man_macro , 284and many functions internal to the 285.Xr man 7 286parser. 287.Pp 288Uses the opaque types 289.Vt struct mparse 290from 291.Pa read.c 292and 293.Vt struct roff 294from 295.Pa roff.c . 296.Pp 297When this header is included, the same file should not include 298.Pa mdoc.h , 299.Pa libmdoc.h , 300or 301.Pa libroff.h . 302.It Qq Pa libroff.h 303Requires 304.In sys/types.h 305for 306.Vt size_t , 307.Qq Pa mandoc.h 308for 309.Vt struct tbl_* 310and 311.Vt struct eqn , 312and 313.Qq Pa libmandoc.h 314for 315.Vt enum rofferr . 316.Pp 317Provides 318.Vt enum tbl_part , 319.Vt struct tbl_node , 320.Vt struct eqn_def , 321.Vt struct eqn_node , 322and many functions internal to the 323.Xr tbl 7 324and 325.Xr eqn 7 326parsers. 327.Pp 328Uses the opaque type 329.Vt struct mparse 330from 331.Pa read.c . 332.Pp 333When this header is included, the same file should not include 334.Pa man.h , 335.Pa mdoc.h , 336.Pa libman.h , 337or 338.Pa libmdoc.h . 339.El 340.Ss Formatter interface 341These headers should be included after any parser interface headers. 342No parser internal headers should be included by the same file. 343.Bl -tag -width Ds 344.It Qq Pa out.h 345Requires 346.In sys/types.h 347for 348.Vt size_t . 349.Pp 350Provides 351.Vt enum roffscale , 352.Vt struct roffcol , 353.Vt struct roffsu , 354.Vt struct rofftbl , 355.Fn a2roffsu , 356and 357.Fn tblcalc . 358.Pp 359Uses 360.Vt struct tbl_span 361from 362.Pa mandoc.h 363as an opaque type for function prototypes. 364.Pp 365When this header is included, the same file should not include 366.Pa manpath.h 367or 368.Pa mansearch.h . 369.It Qq Pa term.h 370Requires 371.In sys/types.h 372for 373.Vt size_t 374and 375.Qq Pa out.h 376for 377.Vt struct roffsu 378and 379.Vt struct rofftbl . 380.Pp 381Provides 382.Vt enum termenc , 383.Vt enum termfont , 384.Vt enum termtype , 385.Vt struct termp_tbl , 386.Vt struct termp , 387and many terminal formatting functions. 388.Pp 389Uses the opaque types 390.Vt struct mchars 391from 392.Pa chars.c 393and 394.Vt struct termp_ps 395from 396.Pa term_ps.c . 397Uses 398.Vt struct tbl_span 399and 400.Vt struct eqn 401from 402.Pa mandoc.h 403as opaque types for function prototypes. 404.Pp 405When this header is included, the same file should not include 406.Pa html.h , 407.Pa manpath.h 408or 409.Pa mansearch.h . 410.It Qq Pa html.h 411Requires 412.In sys/types.h 413for 414.Vt size_t , 415.In stdio.h 416for 417.Dv BUFSIZ , 418and 419.Qq Pa out.h 420for 421.Vt struct roffsu 422and 423.Vt struct rofftbl . 424.Pp 425Provides 426.Vt enum htmltag , 427.Vt enum htmlattr , 428.Vt enum htmlfont , 429.Vt struct tag , 430.Vt struct tagq , 431.Vt struct htmlpair , 432.Vt struct html , 433and many HTML formatting functions. 434.Pp 435Uses the opaque type 436.Vt struct mchars 437from 438.Pa chars.c . 439.Pp 440When this header is included, the same file should not include 441.Pa term.h , 442.Pa manpath.h 443or 444.Pa mansearch.h . 445.It Qq Pa main.h 446Provides the top level steering functions for all formatters. 447.Pp 448Uses the opaque type 449.Vt struct mchars 450from 451.Pa chars.c . 452Uses the types 453.Vt struct mdoc 454from 455.Pa libmdoc.h 456and 457.Vt struct man 458from 459.Pa libman.h 460as opaque types for function prototypes. 461.It Qq Pa manpath.h 462Requires 463.In sys/types.h 464for 465.Vt size_t . 466.Pp 467Provides 468.Vt struct manpaths 469and the functions 470.Fn manpath_manconf , 471.Fn manpath_parse , 472and 473.Fn manpath_free . 474.Pp 475When this header is included, the same file should not include 476.Pa out.h , 477.Pa term.h , 478or 479.Pa html.h . 480.It Qq Pa mansearch.h 481Requires 482.In sys/types.h 483for 484.Vt size_t 485and 486.In stdint.h 487for 488.Vt uint64_t . 489.Pp 490Provides 491.Vt enum argmode , 492.Vt struct manpage , 493.Vt struct mansearch , 494and the functions 495.Fn mansearch_setup , 496.Fn mansearch , 497and 498.Fn mansearch_free . 499.Pp 500Uses 501.Vt struct manpaths 502from 503.Pa manpath.h 504as an opaque type for function prototypes. 505.Pp 506When this header is included, the same file should not include 507.Pa out.h , 508.Pa term.h , 509or 510.Pa html.h . 511.El 512