contrib/mdocml/mandoc_headers.3

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