[BACK]Return to mandoc_headers.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mandoc_headers.3, Revision 1.2

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
1.2     ! schwarze   50: Note that mere usage of an opaque struct type does
1.1       schwarze   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
1.2     ! schwarze  207: .Vt size_t
        !           208: and
        !           209: .Qq Pa mandoc.h
        !           210: for
        !           211: .Vt enum mandocerr .
1.1       schwarze  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
1.2     ! schwarze  229: .Vt struct tbl_span
1.1       schwarze  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

CVSweb