mandoc_headers.3 revision 307795
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_ohash.h 66Includes 67.In ohash.h 68and provides 69.Fn mandoc_ohash_init . 70.It Qq Pa mandoc.h 71Requires 72.In sys/types.h 73for 74.Vt size_t . 75.Pp 76Provides 77.Vt enum mandoc_esc , 78.Vt enum mandocerr , 79.Vt enum mandoclevel , 80.Vt enum tbl_cellt , 81.Vt enum tbl_datt , 82.Vt enum tbl_spant , 83.Vt enum eqn_boxt , 84.Vt enum eqn_fontt , 85.Vt enum eqn_pilet , 86.Vt enum eqn_post , 87.Vt struct tbl_opts , 88.Vt struct tbl_cell , 89.Vt struct tbl_row , 90.Vt struct tbl_dat , 91.Vt struct tbl_span , 92.Vt struct eqn_box , 93.Vt struct eqn , 94the function prototype typedef 95.Fn mandocmsg , 96the function 97.Xr mandoc_escape 3 , 98the functions described in 99.Xr mchars_alloc 3 , 100and the functions 101.Fn mparse_* 102described in 103.Xr mandoc 3 . 104.Pp 105Uses the opaque type 106.Vt struct mparse 107from 108.Pa read.c 109for function prototypes. 110Uses the type 111.Vt struct roff_man 112from 113.Pa roff.h 114as an opaque type for function prototypes. 115.It Qq Pa roff.h 116Provides 117.Vt enum mdoc_endbody , 118.Vt enum roff_macroset , 119.Vt enum roff_next , 120.Vt enum roff_sec , 121.Vt enum roff_type , 122.Vt struct roff_man , 123.Vt struct roff_meta , 124.Vt struct roff_node , 125and the function 126.Fn deroff . 127.Pp 128Uses pointers to the types 129.Vt struct mdoc_arg 130and 131.Vt union mdoc_data 132from 133.Pa mdoc.h 134as opaque struct members. 135.El 136.Pp 137The following two require 138.Qq Pa roff.h 139but no other mandoc headers. 140Afterwards, any other mandoc headers can be included as needed. 141.Bl -tag -width Ds 142.It Qq Pa mdoc.h 143Requires 144.In sys/types.h 145for 146.Vt size_t . 147.Pp 148Provides 149.Vt enum mdocargt , 150.Vt enum mdoc_auth , 151.Vt enum mdoc_disp , 152.Vt enum mdoc_font , 153.Vt enum mdoc_list , 154.Vt struct mdoc_argv , 155.Vt struct mdoc_arg , 156.Vt struct mdoc_an , 157.Vt struct mdoc_bd , 158.Vt struct mdoc_bf , 159.Vt struct mdoc_bl , 160.Vt struct mdoc_rs , 161.Vt union mdoc_data , 162and the functions 163.Fn mdoc_* 164described in 165.Xr mandoc 3 . 166.Pp 167Uses the type 168.Vt struct roff_man 169from 170.Pa roff.h 171as an opaque type for function prototypes. 172.Pp 173When this header is included, the same file should not include 174.Pa libman.h 175or 176.Pa libroff.h . 177.It Qq Pa man.h 178Provides the functions 179.Fn man_* 180described in 181.Xr mandoc 3 . 182.Pp 183Uses the opaque type 184.Vt struct mparse 185from 186.Pa read.c 187for function prototypes. 188Uses the type 189.Vt struct roff_man 190from 191.Pa roff.h 192as an opaque type for function prototypes. 193.Pp 194When this header is included, the same file should not include 195.Pa libmdoc.h 196or 197.Pa libroff.h . 198.El 199.Ss Parser internals 200The following headers require inclusion of a parser interface header 201before they can be included. All parser interface headers should 202precede all parser internal headers. When any parser internal headers 203are included, the same file should not include any formatter headers. 204.Bl -tag -width Ds 205.It Qq Pa libmandoc.h 206Requires 207.In sys/types.h 208for 209.Vt size_t 210and 211.Qq Pa mandoc.h 212for 213.Vt enum mandocerr . 214.Pp 215Provides 216.Vt enum rofferr , 217.Vt struct buf , 218utility functions needed by multiple parsers, 219and the top-level functions to call the parsers. 220.Pp 221Uses the opaque types 222.Vt struct mparse 223from 224.Pa read.c 225and 226.Vt struct roff 227from 228.Pa roff.c 229for function prototypes. 230Uses the types 231.Vt struct tbl_span 232and 233.Vt struct eqn 234from 235.Pa mandoc.h 236and 237.Vt struct roff_man 238from 239.Pa roff.h 240as opaque types for function prototypes. 241.It Qq Pa roff_int.h 242Requires 243.Qq Pa roff.h 244for 245.Vt enum roff_type . 246.Pp 247Provides functions named 248.Fn roff_* 249to handle roff nodes and the two special functions 250.Fn man_breakscope 251and 252.Fn mdoc_argv_free 253because the latter two are needed by 254.Qq Pa roff.c . 255.Pp 256Uses the types 257.Vt struct eqn 258and 259.Vt struct tbl_span 260from 261.Pa mandoc.h , 262.Vt struct roff_man 263and 264.Vt struct roff_node 265from 266.Pa roff.h , 267and 268.Vt struct mdoc_arg 269from 270.Pa mdoc.h 271as opaque types for function prototypes. 272.It Qq Pa libmdoc.h 273Requires 274.Qq Pa mdoc.h 275for 276.Vt enum mdoc_* 277and 278.Vt struct mdoc_* . 279.Pp 280Provides 281.Vt enum margserr , 282.Vt enum mdelim , 283.Vt struct mdoc_macro , 284and many functions internal to the 285.Xr mdoc 7 286parser. 287.Pp 288Uses the opaque type 289.Vt struct mparse 290from 291.Pa read.c . 292Uses the types 293.Vt struct roff_man 294and 295.Vt struct roff_node 296from 297.Pa roff.h 298as opaque types for function prototypes. 299.Pp 300When this header is included, the same file should not include 301.Pa man.h , 302.Pa libman.h , 303or 304.Pa libroff.h . 305.It Qq Pa libman.h 306Provides 307.Vt struct man_macro 308and some functions internal to the 309.Xr man 7 310parser. 311.Pp 312Uses the types 313.Vt struct roff_man 314and 315.Vt struct roff_node 316from 317.Pa roff.h 318as opaque types for function prototypes. 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.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 tag.h 460Requires 461.In sys/types.h 462for 463.Vt size_t . 464.Pp 465Provides an interface to generate 466.Xr ctags 1 467files for the 468.Ic :t 469functionality mentioned in 470.Xr man 1 . 471.It Qq Pa main.h 472Provides the top level steering functions for all formatters. 473.Pp 474Uses the type 475.Vt struct roff_man 476from 477.Pa roff.h 478as an opaque type for function prototypes. 479.It Qq Pa manconf.h 480Requires 481.In sys/types.h 482for 483.Vt size_t . 484.Pp 485Provides 486.Vt struct manconf , 487.Vt struct manpaths , 488.Vt struct manoutput , 489and the functions 490.Fn manconf_parse , 491.Fn manconf_output , 492and 493.Fn manconf_free . 494.It Qq Pa mansearch.h 495Requires 496.In sys/types.h 497for 498.Vt size_t 499and 500.In stdint.h 501for 502.Vt uint64_t . 503.Pp 504Provides 505.Vt enum argmode , 506.Vt struct manpage , 507.Vt struct mansearch , 508and the functions 509.Fn mansearch_setup , 510.Fn mansearch , 511and 512.Fn mansearch_free . 513.Pp 514Uses 515.Vt struct manpaths 516from 517.Pa manconf.h 518as an opaque type for function prototypes. 519.Pp 520When this header is included, the same file should not include 521.Pa out.h , 522.Pa term.h , 523or 524.Pa html.h . 525.El 526