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