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