Annotation of mandoc/mandoc_headers.3, Revision 1.1
1.1 ! schwarze 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
CVSweb