contrib/mdocml/mandoc_headers.3

   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
   8 To support a cleaner coding style, the mandoc header files do not
   9 contain any include directives and do not guard against multiple
  10 inclusion.
  11 The application developer has to make sure that the headers are
  12 included in a proper order, and that no header is included more
  13 than once.
  14 .Pp
  15 The headers and functions form three major groups:
  16 .Sx Parser interface ,
  17 .Sx Parser internals ,
  18 and
  19 .Sx Formatter interface .
  20 .Pp
  21 Various rules are given below prohibiting the inclusion of certain
  22 combinations of headers into the same file.
  23 The intention is to keep the following functional components
  24 separate from each other:
  25 .Pp
  26 .Bl -dash -offset indent -compact
  27 .It
  28 .Xr mdoc 7
  29 parser
  30 .It
  31 .Xr man 7
  32 parser
  33 .It
  34 .Xr roff 7
  35 parser
  36 .It
  37 .Xr tbl 7
  38 parser
  39 .It
  40 .Xr eqn 7
  41 parser
  42 .It
  43 terminal formatters
  44 .It
  45 HTML formatters
  46 .It
  47 search tools
  48 .El
  49 .Pp
  50 Note that mere usage of an opaque struct type does
  51 .Em not
  52 require inclusion of the header where that type is defined.
  53 .Ss Parser interface
  54 Each of the following headers can be included without including
  55 any other mandoc header.
  56 These headers should be included before any other mandoc headers.
  57 .Bl -tag -width Ds
  58 .It Qq Pa mandoc_aux.h
  59 Requires
  60 .In sys/types.h
  61 for
  62 .Vt size_t .
  63 .Pp
  64 Provides the utility functions documented in
  65 .Xr mandoc_malloc 3 .
  66 .It Qq Pa mandoc_ohash.h
  67 Requires
  68 .In stddef.h
  69 for
  70 .Vt ptrdiff_t
  71 and
  72 .In stdint.h
  73 for
  74 .Vt uint32_t .
  75 .Pp
  76 Includes
  77 .In ohash.h
  78 and provides
  79 .Fn mandoc_ohash_init .
  80 .It Qq Pa mandoc.h
  81 Requires
  82 .In sys/types.h
  83 for
  84 .Vt size_t .
  85 .Pp
  86 Provides
  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 ,
 104 the function prototype typedef
 105 .Fn mandocmsg ,
 106 the function
 107 .Xr mandoc_escape 3 ,
 108 the functions described in
 109 .Xr mchars_alloc 3 ,
 110 and the functions
 111 .Fn mparse_*
 112 described in
 113 .Xr mandoc 3 .
 114 .Pp
 115 Uses the opaque type
 116 .Vt struct mparse
 117 from
 118 .Pa read.c
 119 for function prototypes.
 120 Uses the type
 121 .Vt struct roff_man
 122 from
 123 .Pa roff.h
 124 as an opaque type for function prototypes.
 125 .It Qq Pa mandoc_xr.h
 126 Provides
 127 .Vt struct mandoc_xr
 128 and the functions
 129 .Fn mandoc_xr_reset ,
 130 .Fn mandoc_xr_add ,
 131 .Fn mandoc_xr_get ,
 132 and
 133 .Fn mandoc_xr_free .
 134 .It Qq Pa roff.h
 135 Requires
 136 .Qq Pa mandoc_ohash.h
 137 for
 138 .Vt struct ohash
 139 and
 140 .Qq Pa mandoc.h
 141 for
 142 .Vt enum mandoc_os .
 143 .Pp
 144 Provides
 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 ,
 154 the constant array
 155 .Va roff_name
 156 and the functions
 157 .Fn deroff ,
 158 .Fn roffhash_alloc ,
 159 .Fn roffhash_find ,
 160 .Fn roffhash_free ,
 161 and
 162 .Fn roff_validate .
 163 .Pp
 164 Uses pointers to the types
 165 .Vt struct mdoc_arg
 166 and
 167 .Vt union mdoc_data
 168 from
 169 .Pa mdoc.h
 170 as opaque struct members.
 171 .El
 172 .Pp
 173 The following two require
 174 .Qq Pa roff.h
 175 but no other mandoc headers.
 176 Afterwards, any other mandoc headers can be included as needed.
 177 .Bl -tag -width Ds
 178 .It Qq Pa mdoc.h
 179 Requires
 180 .In sys/types.h
 181 for
 182 .Vt size_t .
 183 .Pp
 184 Provides
 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 ,
 198 and the functions
 199 .Fn mdoc_*
 200 described in
 201 .Xr mandoc 3 .
 202 .Pp
 203 Uses the type
 204 .Vt struct roff_man
 205 from
 206 .Pa roff.h
 207 as an opaque type for function prototypes.
 208 .Pp
 209 When this header is included, the same file should not include
 210 .Pa libman.h
 211 or
 212 .Pa libroff.h .
 213 .It Qq Pa man.h
 214 Provides the functions
 215 .Fn man_*
 216 described in
 217 .Xr mandoc 3 .
 218 .Pp
 219 Uses the opaque type
 220 .Vt struct mparse
 221 from
 222 .Pa read.c
 223 for function prototypes.
 224 Uses the type
 225 .Vt struct roff_man
 226 from
 227 .Pa roff.h
 228 as an opaque type for function prototypes.
 229 .Pp
 230 When this header is included, the same file should not include
 231 .Pa libmdoc.h
 232 or
 233 .Pa libroff.h .
 234 .El
 235 .Ss Parser internals
 236 The following headers require inclusion of a parser interface header
 237 before they can be included.
 238 All parser interface headers should precede all parser internal headers.
 239 When any parser internal headers are included, the same file should
 240 not include any formatter headers.
 241 .Bl -tag -width Ds
 242 .It Qq Pa libmandoc.h
 243 Requires
 244 .In sys/types.h
 245 for
 246 .Vt size_t
 247 and
 248 .Qq Pa mandoc.h
 249 for
 250 .Vt enum mandocerr .
 251 .Pp
 252 Provides
 253 .Vt enum rofferr ,
 254 .Vt struct buf ,
 255 utility functions needed by multiple parsers,
 256 and the top-level functions to call the parsers.
 257 .Pp
 258 Uses the opaque types
 259 .Vt struct mparse
 260 from
 261 .Pa read.c
 262 and
 263 .Vt struct roff
 264 from
 265 .Pa roff.c
 266 for function prototypes.
 267 Uses the type
 268 .Vt struct roff_man
 269 from
 270 .Pa roff.h
 271 as an opaque type for function prototypes.
 272 .It Qq Pa roff_int.h
 273 Requires
 274 .Qq Pa roff.h
 275 for
 276 .Vt enum roff_type .
 277 .Pp
 278 Provides functions named
 279 .Fn roff_*
 280 to handle roff nodes and the two special functions
 281 .Fn man_breakscope
 282 and
 283 .Fn mdoc_argv_free
 284 because the latter two are needed by
 285 .Qq Pa roff.c .
 286 .Pp
 287 Uses the types
 288 .Vt struct roff_man
 289 and
 290 .Vt struct roff_node
 291 from
 292 .Pa roff.h
 293 and
 294 .Vt struct mdoc_arg
 295 from
 296 .Pa mdoc.h
 297 as opaque types for function prototypes.
 298 .It Qq Pa libmdoc.h
 299 Requires
 300 .Qq Pa roff.h
 301 for
 302 .Vt enum roff_tok
 303 and
 304 .Qq Pa mdoc.h
 305 for
 306 .Vt enum mdoc_*
 307 and
 308 .Vt struct mdoc_* .
 309 .Pp
 310 Provides
 311 .Vt enum margserr ,
 312 .Vt enum mdelim ,
 313 .Vt struct mdoc_macro ,
 314 and many functions internal to the
 315 .Xr mdoc 7
 316 parser.
 317 .Pp
 318 Uses the opaque type
 319 .Vt struct mparse
 320 from
 321 .Pa read.c .
 322 Uses the types
 323 .Vt struct roff_man
 324 and
 325 .Vt struct roff_node
 326 from
 327 .Pa roff.h
 328 as opaque types for function prototypes.
 329 .Pp
 330 When this header is included, the same file should not include
 331 .Pa man.h ,
 332 .Pa libman.h ,
 333 or
 334 .Pa libroff.h .
 335 .It Qq Pa libman.h
 336 Requires
 337 .Qq Pa roff.h
 338 for
 339 .Vt enum roff_tok .
 340 .Pp
 341 Provides
 342 .Vt struct man_macro
 343 and some functions internal to the
 344 .Xr man 7
 345 parser.
 346 .Pp
 347 Uses the types
 348 .Vt struct roff_man
 349 and
 350 .Vt struct roff_node
 351 from
 352 .Pa roff.h
 353 as opaque types for function prototypes.
 354 .Pp
 355 When this header is included, the same file should not include
 356 .Pa mdoc.h ,
 357 .Pa libmdoc.h ,
 358 or
 359 .Pa libroff.h .
 360 .It Qq Pa libroff.h
 361 Requires
 362 .In sys/types.h
 363 for
 364 .Vt size_t
 365 and
 366 .Qq Pa mandoc.h
 367 for
 368 .Vt struct tbl_*
 369 and
 370 .Vt struct eqn_box .
 371 .Pp
 372 Provides
 373 .Vt enum tbl_part ,
 374 .Vt struct tbl_node ,
 375 .Vt struct eqn_def ,
 376 .Vt struct eqn_node ,
 377 and many functions internal to the
 378 .Xr tbl 7
 379 and
 380 .Xr eqn 7
 381 parsers.
 382 .Pp
 383 Uses the opaque type
 384 .Vt struct mparse
 385 from
 386 .Pa read.c .
 387 .Pp
 388 When this header is included, the same file should not include
 389 .Pa man.h ,
 390 .Pa mdoc.h ,
 391 .Pa libman.h ,
 392 or
 393 .Pa libmdoc.h .
 394 .El
 395 .Ss Formatter interface
 396 These headers should be included after any parser interface headers.
 397 No parser internal headers should be included by the same file.
 398 .Bl -tag -width Ds
 399 .It Qq Pa out.h
 400 Requires
 401 .In sys/types.h
 402 for
 403 .Vt size_t .
 404 .Pp
 405 Provides
 406 .Vt enum roffscale ,
 407 .Vt struct roffcol ,
 408 .Vt struct roffsu ,
 409 .Vt struct rofftbl ,
 410 .Fn a2roffsu ,
 411 and
 412 .Fn tblcalc .
 413 .Pp
 414 Uses
 415 .Vt struct tbl_span
 416 from
 417 .Pa mandoc.h
 418 as an opaque type for function prototypes.
 419 .Pp
 420 When this header is included, the same file should not include
 421 .Pa mansearch.h .
 422 .It Qq Pa term.h
 423 Requires
 424 .In sys/types.h
 425 for
 426 .Vt size_t
 427 and
 428 .Qq Pa out.h
 429 for
 430 .Vt struct roffsu
 431 and
 432 .Vt struct rofftbl .
 433 .Pp
 434 Provides
 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 ,
 441 and many terminal formatting functions.
 442 .Pp
 443 Uses the opaque type
 444 .Vt struct termp_ps
 445 from
 446 .Pa term_ps.c .
 447 Uses
 448 .Vt struct tbl_span
 449 and
 450 .Vt struct eqn_box
 451 from
 452 .Pa mandoc.h
 453 and
 454 .Vt struct roff_meta
 455 and
 456 .Vt struct roff_node
 457 from
 458 .Pa roff.h
 459 as opaque types for function prototypes.
 460 .Pp
 461 When this header is included, the same file should not include
 462 .Pa html.h
 463 or
 464 .Pa mansearch.h .
 465 .It Qq Pa html.h
 466 Requires
 467 .In sys/types.h
 468 for
 469 .Vt size_t
 470 and
 471 .Qq Pa out.h
 472 for
 473 .Vt struct roffsu
 474 and
 475 .Vt struct rofftbl .
 476 .Pp
 477 Provides
 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 ,
 486 and many HTML formatting functions.
 487 .Pp
 488 Uses
 489 .Vt struct tbl_span
 490 and
 491 .Vt struct eqn_box
 492 from
 493 .Pa mandoc.h
 494 and
 495 .Vt struct roff_node
 496 from
 497 .Pa roff.h
 498 as opaque types for function prototypes.
 499 .Pp
 500 When this header is included, the same file should not include
 501 .Pa term.h
 502 or
 503 .Pa mansearch.h .
 504 .It Qq Pa tag.h
 505 Requires
 506 .In sys/types.h
 507 for
 508 .Vt size_t .
 509 .Pp
 510 Provides an interface to generate
 511 .Xr ctags 1
 512 files for the
 513 .Ic :t
 514 functionality mentioned in
 515 .Xr man 1 .
 516 .It Qq Pa main.h
 517 Provides the top level steering functions for all formatters.
 518 .Pp
 519 Uses the type
 520 .Vt struct roff_man
 521 from
 522 .Pa roff.h
 523 as an opaque type for function prototypes.
 524 .It Qq Pa manconf.h
 525 Requires
 526 .In sys/types.h
 527 for
 528 .Vt size_t .
 529 .Pp
 530 Provides
 531 .Vt struct manconf ,
 532 .Vt struct manpaths ,
 533 .Vt struct manoutput ,
 534 and the functions
 535 .Fn manconf_parse ,
 536 .Fn manconf_output ,
 537 .Fn manconf_free ,
 538 and
 539 .Fn manpath_base .
 540 .It Qq Pa mansearch.h
 541 Requires
 542 .In sys/types.h
 543 for
 544 .Vt size_t
 545 and
 546 .In stdint.h
 547 for
 548 .Vt uint64_t .
 549 .Pp
 550 Provides
 551 .Vt enum argmode ,
 552 .Vt struct manpage ,
 553 .Vt struct mansearch ,
 554 and the functions
 555 .Fn mansearch
 556 and
 557 .Fn mansearch_free .
 558 .Pp
 559 Uses
 560 .Vt struct manpaths
 561 from
 562 .Pa manconf.h
 563 as an opaque type for function prototypes.
 564 .Pp
 565 When this header is included, the same file should not include
 566 .Pa out.h ,
 567 .Pa term.h ,
 568 or
 569 .Pa html.h .
 570 .El