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