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 roff_type .
 122 .El
 123 .Pp
 124 The following two require
 125 .Qq Pa roff.h
 126 but no other mandoc headers.
 127 Afterwards, any other mandoc headers can be included as needed.
 128 .Bl -tag -width Ds
 129 .It Qq Pa mdoc.h
 130 Requires
 131 .In sys/types.h
 132 for
 133 .Vt size_t
 134 and
 135 .Qq Pa roff.h
 136 for
 137 .Vt enum roff_type .
 138 .Pp
 139 Provides
 140 .Vt enum mdoct ,
 141 .Vt enum mdocargt ,
 142 .Vt enum mdoc_sec ,
 143 .Vt enum mdoc_endbody ,
 144 .Vt enum mdoc_disp ,
 145 .Vt enum mdoc_list ,
 146 .Vt enum mdoc_auth ,
 147 .Vt enum mdoc_font ,
 148 .Vt struct mdoc_meta ,
 149 .Vt struct mdoc_argv ,
 150 .Vt struct mdoc_arg ,
 151 .Vt struct mdoc_bd ,
 152 .Vt struct mdoc_bl ,
 153 .Vt struct mdoc_an ,
 154 .Vt struct mdoc_bf ,
 155 .Vt struct mdoc_rs ,
 156 .Vt struct mdoc_node ,
 157 and the functions
 158 .Fn mdoc_*
 159 described in
 160 .Xr mandoc 3 .
 161 .Pp
 162 Uses the type
 163 .Vt struct mdoc
 164 from
 165 .Pa libmdoc.h
 166 as an opaque type for function prototypes.
 167 Uses pointers to the types
 168 .Vt struct tbl_span
 169 and
 170 .Vt struct eqn
 171 as opaque struct members.
 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 Requires
 179 .Qq Pa roff.h
 180 for
 181 .Vt enum roff_type .
 182 .Pp
 183 Provides
 184 .Vt enum mant ,
 185 .Vt struct man_meta ,
 186 .Vt struct man_node ,
 187 and 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 and
 225 .Qq Pa mandoc.h
 226 for
 227 .Vt enum mandocerr .
 228 .Pp
 229 Provides
 230 .Vt enum rofferr ,
 231 .Vt struct buf ,
 232 utility functions needed by multiple parsers,
 233 and the top-level functions to call the parsers.
 234 .Pp
 235 Uses the opaque types
 236 .Vt struct mparse
 237 from
 238 .Pa read.c
 239 and
 240 .Vt struct roff
 241 from
 242 .Pa roff.c
 243 for function prototypes.
 244 Uses the types
 245 .Vt struct tbl_span
 246 and
 247 .Vt struct eqn
 248 from
 249 .Pa mandoc.h ,
 250 .Vt struct mdoc
 251 from
 252 .Pa libmdoc.h ,
 253 and
 254 .Vt struct man
 255 from
 256 .Pa libman.h
 257 as opaque types for function prototypes.
 258 .It Qq Pa libmdoc.h
 259 Requires
 260 .Qq Pa mdoc.h
 261 for
 262 .Vt enum mdoct ,
 263 .Vt enum mdoc_* ,
 264 and
 265 .Vt struct mdoc_* .
 266 .Pp
 267 Provides
 268 .Vt enum mdoc_next ,
 269 .Vt enum margserr ,
 270 .Vt enum mdelim ,
 271 .Vt struct mdoc ,
 272 .Vt struct mdoc_macro ,
 273 and many functions internal to the
 274 .Xr mdoc 7
 275 parser.
 276 .Pp
 277 Uses the opaque types
 278 .Vt struct mparse
 279 from
 280 .Pa read.c
 281 and
 282 .Vt struct roff
 283 from
 284 .Pa roff.c .
 285 .Pp
 286 When this header is included, the same file should not include
 287 .Pa man.h ,
 288 .Pa libman.h ,
 289 or
 290 .Pa libroff.h .
 291 .It Qq Pa libman.h
 292 Requires
 293 .Qq Pa man.h
 294 for
 295 .Vt enum mant
 296 and
 297 .Vt struct man_node.
 298 .Pp
 299 Provides
 300 .Vt enum man_next ,
 301 .Vt struct man ,
 302 .Vt struct man_macro ,
 303 and many functions internal to the
 304 .Xr man 7
 305 parser.
 306 .Pp
 307 Uses the opaque types
 308 .Vt struct mparse
 309 from
 310 .Pa read.c
 311 and
 312 .Vt struct roff
 313 from
 314 .Pa roff.c .
 315 .Pp
 316 When this header is included, the same file should not include
 317 .Pa mdoc.h ,
 318 .Pa libmdoc.h ,
 319 or
 320 .Pa libroff.h .
 321 .It Qq Pa libroff.h
 322 Requires
 323 .In sys/types.h
 324 for
 325 .Vt size_t ,
 326 .Qq Pa mandoc.h
 327 for
 328 .Vt struct tbl_*
 329 and
 330 .Vt struct eqn ,
 331 and
 332 .Qq Pa libmandoc.h
 333 for
 334 .Vt enum rofferr .
 335 .Pp
 336 Provides
 337 .Vt enum tbl_part ,
 338 .Vt struct tbl_node ,
 339 .Vt struct eqn_def ,
 340 .Vt struct eqn_node ,
 341 and many functions internal to the
 342 .Xr tbl 7
 343 and
 344 .Xr eqn 7
 345 parsers.
 346 .Pp
 347 Uses the opaque type
 348 .Vt struct mparse
 349 from
 350 .Pa read.c .
 351 .Pp
 352 When this header is included, the same file should not include
 353 .Pa man.h ,
 354 .Pa mdoc.h ,
 355 .Pa libman.h ,
 356 or
 357 .Pa libmdoc.h .
 358 .El
 359 .Ss Formatter interface
 360 These headers should be included after any parser interface headers.
 361 No parser internal headers should be included by the same file.
 362 .Bl -tag -width Ds
 363 .It Qq Pa out.h
 364 Requires
 365 .In sys/types.h
 366 for
 367 .Vt size_t .
 368 .Pp
 369 Provides
 370 .Vt enum roffscale ,
 371 .Vt struct roffcol ,
 372 .Vt struct roffsu ,
 373 .Vt struct rofftbl ,
 374 .Fn a2roffsu ,
 375 and
 376 .Fn tblcalc .
 377 .Pp
 378 Uses
 379 .Vt struct tbl_span
 380 from
 381 .Pa mandoc.h
 382 as an opaque type for function prototypes.
 383 .Pp
 384 When this header is included, the same file should not include
 385 .Pa mansearch.h .
 386 .It Qq Pa term.h
 387 Requires
 388 .In sys/types.h
 389 for
 390 .Vt size_t
 391 and
 392 .Qq Pa out.h
 393 for
 394 .Vt struct roffsu
 395 and
 396 .Vt struct rofftbl .
 397 .Pp
 398 Provides
 399 .Vt enum termenc ,
 400 .Vt enum termfont ,
 401 .Vt enum termtype ,
 402 .Vt struct termp_tbl ,
 403 .Vt struct termp ,
 404 and many terminal formatting functions.
 405 .Pp
 406 Uses the opaque types
 407 .Vt struct mchars
 408 from
 409 .Pa chars.c
 410 and
 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 as opaque types for function prototypes.
 421 .Pp
 422 When this header is included, the same file should not include
 423 .Pa html.h
 424 or
 425 .Pa mansearch.h .
 426 .It Qq Pa html.h
 427 Requires
 428 .In sys/types.h
 429 for
 430 .Vt size_t ,
 431 .In stdio.h
 432 for
 433 .Dv BUFSIZ ,
 434 and
 435 .Qq Pa out.h
 436 for
 437 .Vt struct roffsu
 438 and
 439 .Vt struct rofftbl .
 440 .Pp
 441 Provides
 442 .Vt enum htmltag ,
 443 .Vt enum htmlattr ,
 444 .Vt enum htmlfont ,
 445 .Vt struct tag ,
 446 .Vt struct tagq ,
 447 .Vt struct htmlpair ,
 448 .Vt struct html ,
 449 and many HTML formatting functions.
 450 .Pp
 451 Uses the opaque type
 452 .Vt struct mchars
 453 from
 454 .Pa chars.c .
 455 .Pp
 456 When this header is included, the same file should not include
 457 .Pa term.h
 458 or
 459 .Pa mansearch.h .
 460 .It Qq Pa main.h
 461 Provides the top level steering functions for all formatters.
 462 .Pp
 463 Uses the opaque type
 464 .Vt struct mchars
 465 from
 466 .Pa chars.c .
 467 Uses the types
 468 .Vt struct mdoc
 469 from
 470 .Pa libmdoc.h
 471 and
 472 .Vt struct man
 473 from
 474 .Pa libman.h
 475 as opaque types for function prototypes.
 476 .It Qq Pa manconf.h
 477 Requires
 478 .In sys/types.h
 479 for
 480 .Vt size_t .
 481 .Pp
 482 Provides
 483 .Vt struct manconf ,
 484 .Vt struct manpaths ,
 485 .Vt struct manoutput ,
 486 and the functions
 487 .Fn manconf_parse ,
 488 .Fn manconf_output ,
 489 and
 490 .Fn manconf_free .
 491 .It Qq Pa mansearch.h
 492 Requires
 493 .In sys/types.h
 494 for
 495 .Vt size_t
 496 and
 497 .In stdint.h
 498 for
 499 .Vt uint64_t .
 500 .Pp
 501 Provides
 502 .Vt enum argmode ,
 503 .Vt struct manpage ,
 504 .Vt struct mansearch ,
 505 and the functions
 506 .Fn mansearch_setup ,
 507 .Fn mansearch ,
 508 and
 509 .Fn mansearch_free .
 510 .Pp
 511 Uses
 512 .Vt struct manpaths
 513 from
 514 .Pa manconf.h
 515 as an opaque type for function prototypes.
 516 .Pp
 517 When this header is included, the same file should not include
 518 .Pa out.h ,
 519 .Pa term.h ,
 520 or
 521 .Pa html.h .
 522 .El