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