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 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 and
 209 .Qq Pa mandoc.h
 210 for
 211 .Vt enum mandocerr .
 212 .Pp
 213 Provides
 214 .Vt enum rofferr ,
 215 .Vt struct buf ,
 216 utility functions needed by multiple parsers,
 217 and the top-level functions to call the parsers.
 218 .Pp
 219 Uses the opaque types
 220 .Vt struct mparse
 221 from
 222 .Pa read.c
 223 and
 224 .Vt struct roff
 225 from
 226 .Pa roff.c
 227 for function prototypes.
 228 Uses the types
 229 .Vt struct tbl_span
 230 and
 231 .Vt struct eqn
 232 from
 233 .Pa mandoc.h ,
 234 .Vt struct mdoc
 235 from
 236 .Pa libmdoc.h ,
 237 and
 238 .Vt struct man
 239 from
 240 .Pa libman.h
 241 as opaque types for function prototypes.
 242 .It Qq Pa libmdoc.h
 243 Requires
 244 .Qq Pa mdoc.h
 245 for
 246 .Vt enum mdoct ,
 247 .Vt enum mdoc_* ,
 248 and
 249 .Vt struct mdoc_* .
 250 .Pp
 251 Provides
 252 .Vt enum mdoc_next ,
 253 .Vt enum margserr ,
 254 .Vt enum mdelim ,
 255 .Vt struct mdoc ,
 256 .Vt struct mdoc_macro ,
 257 and many functions internal to the
 258 .Xr mdoc 7
 259 parser.
 260 .Pp
 261 Uses the opaque types
 262 .Vt struct mparse
 263 from
 264 .Pa read.c
 265 and
 266 .Vt struct roff
 267 from
 268 .Pa roff.c .
 269 .Pp
 270 When this header is included, the same file should not include
 271 .Pa man.h ,
 272 .Pa libman.h ,
 273 or
 274 .Pa libroff.h .
 275 .It Qq Pa libman.h
 276 Requires
 277 .Qq Pa man.h
 278 for
 279 .Vt enum mant
 280 and
 281 .Vt struct man_node.
 282 .Pp
 283 Provides
 284 .Vt enum man_next ,
 285 .Vt struct man ,
 286 .Vt struct man_macro ,
 287 and many functions internal to the
 288 .Xr man 7
 289 parser.
 290 .Pp
 291 Uses the opaque types
 292 .Vt struct mparse
 293 from
 294 .Pa read.c
 295 and
 296 .Vt struct roff
 297 from
 298 .Pa roff.c .
 299 .Pp
 300 When this header is included, the same file should not include
 301 .Pa mdoc.h ,
 302 .Pa libmdoc.h ,
 303 or
 304 .Pa libroff.h .
 305 .It Qq Pa libroff.h
 306 Requires
 307 .In sys/types.h
 308 for
 309 .Vt size_t ,
 310 .Qq Pa mandoc.h
 311 for
 312 .Vt struct tbl_*
 313 and
 314 .Vt struct eqn ,
 315 and
 316 .Qq Pa libmandoc.h
 317 for
 318 .Vt enum rofferr .
 319 .Pp
 320 Provides
 321 .Vt enum tbl_part ,
 322 .Vt struct tbl_node ,
 323 .Vt struct eqn_def ,
 324 .Vt struct eqn_node ,
 325 and many functions internal to the
 326 .Xr tbl 7
 327 and
 328 .Xr eqn 7
 329 parsers.
 330 .Pp
 331 Uses the opaque type
 332 .Vt struct mparse
 333 from
 334 .Pa read.c .
 335 .Pp
 336 When this header is included, the same file should not include
 337 .Pa man.h ,
 338 .Pa mdoc.h ,
 339 .Pa libman.h ,
 340 or
 341 .Pa libmdoc.h .
 342 .El
 343 .Ss Formatter interface
 344 These headers should be included after any parser interface headers.
 345 No parser internal headers should be included by the same file.
 346 .Bl -tag -width Ds
 347 .It Qq Pa out.h
 348 Requires
 349 .In sys/types.h
 350 for
 351 .Vt size_t .
 352 .Pp
 353 Provides
 354 .Vt enum roffscale ,
 355 .Vt struct roffcol ,
 356 .Vt struct roffsu ,
 357 .Vt struct rofftbl ,
 358 .Fn a2roffsu ,
 359 and
 360 .Fn tblcalc .
 361 .Pp
 362 Uses
 363 .Vt struct tbl_span
 364 from
 365 .Pa mandoc.h
 366 as an opaque type for function prototypes.
 367 .Pp
 368 When this header is included, the same file should not include
 369 .Pa manpath.h
 370 or
 371 .Pa mansearch.h .
 372 .It Qq Pa term.h
 373 Requires
 374 .In sys/types.h
 375 for
 376 .Vt size_t
 377 and
 378 .Qq Pa out.h
 379 for
 380 .Vt struct roffsu
 381 and
 382 .Vt struct rofftbl .
 383 .Pp
 384 Provides
 385 .Vt enum termenc ,
 386 .Vt enum termfont ,
 387 .Vt enum termtype ,
 388 .Vt struct termp_tbl ,
 389 .Vt struct termp ,
 390 and many terminal formatting functions.
 391 .Pp
 392 Uses the opaque types
 393 .Vt struct mchars
 394 from
 395 .Pa chars.c
 396 and
 397 .Vt struct termp_ps
 398 from
 399 .Pa term_ps.c .
 400 Uses
 401 .Vt struct tbl_span
 402 and
 403 .Vt struct eqn
 404 from
 405 .Pa mandoc.h
 406 as opaque types for function prototypes.
 407 .Pp
 408 When this header is included, the same file should not include
 409 .Pa html.h ,
 410 .Pa manpath.h
 411 or
 412 .Pa mansearch.h .
 413 .It Qq Pa html.h
 414 Requires
 415 .In sys/types.h
 416 for
 417 .Vt size_t ,
 418 .In stdio.h
 419 for
 420 .Dv BUFSIZ ,
 421 and
 422 .Qq Pa out.h
 423 for
 424 .Vt struct roffsu
 425 and
 426 .Vt struct rofftbl .
 427 .Pp
 428 Provides
 429 .Vt enum htmltag ,
 430 .Vt enum htmlattr ,
 431 .Vt enum htmlfont ,
 432 .Vt struct tag ,
 433 .Vt struct tagq ,
 434 .Vt struct htmlpair ,
 435 .Vt struct html ,
 436 and many HTML formatting functions.
 437 .Pp
 438 Uses the opaque type
 439 .Vt struct mchars
 440 from
 441 .Pa chars.c .
 442 .Pp
 443 When this header is included, the same file should not include
 444 .Pa term.h ,
 445 .Pa manpath.h
 446 or
 447 .Pa mansearch.h .
 448 .It Qq Pa main.h
 449 Provides the top level steering functions for all formatters.
 450 .Pp
 451 Uses the opaque type
 452 .Vt struct mchars
 453 from
 454 .Pa chars.c .
 455 Uses the types
 456 .Vt struct mdoc
 457 from
 458 .Pa libmdoc.h
 459 and
 460 .Vt struct man
 461 from
 462 .Pa libman.h
 463 as opaque types for function prototypes.
 464 .It Qq Pa manpath.h
 465 Requires
 466 .In sys/types.h
 467 for
 468 .Vt size_t .
 469 .Pp
 470 Provides
 471 .Vt struct manpaths
 472 and the functions
 473 .Fn manpath_manconf ,
 474 .Fn manpath_parse ,
 475 and
 476 .Fn manpath_free .
 477 .Pp
 478 When this header is included, the same file should not include
 479 .Pa out.h ,
 480 .Pa term.h ,
 481 or
 482 .Pa html.h .
 483 .It Qq Pa mansearch.h
 484 Requires
 485 .In sys/types.h
 486 for
 487 .Vt size_t
 488 and
 489 .In stdint.h
 490 for
 491 .Vt uint64_t .
 492 .Pp
 493 Provides
 494 .Vt enum argmode ,
 495 .Vt struct manpage ,
 496 .Vt struct mansearch ,
 497 and the functions
 498 .Fn mansearch_setup ,
 499 .Fn mansearch ,
 500 and
 501 .Fn mansearch_free .
 502 .Pp
 503 Uses
 504 .Vt struct manpaths
 505 from
 506 .Pa manpath.h
 507 as an opaque type for function prototypes.
 508 .Pp
 509 When this header is included, the same file should not include
 510 .Pa out.h ,
 511 .Pa term.h ,
 512 or
 513 .Pa html.h .
 514 .El