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