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