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

Annotation of mandoc/mandoc_headers.3, Revision 1.4

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: .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.
1.4     ! schwarze  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
1.1       schwarze  129: .It Qq Pa mdoc.h
                    130: Requires
                    131: .In sys/types.h
                    132: for
1.4     ! schwarze  133: .Vt size_t
        !           134: and
        !           135: .Qq Pa roff.h
        !           136: for
        !           137: .Vt enum roff_type .
1.1       schwarze  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
1.4     ! schwarze  178: Requires
        !           179: .Qq Pa roff.h
        !           180: for
        !           181: .Vt enum roff_type .
        !           182: .Pp
1.1       schwarze  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
1.2       schwarze  223: .Vt size_t
                    224: and
                    225: .Qq Pa mandoc.h
                    226: for
                    227: .Vt enum mandocerr .
1.1       schwarze  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
1.2       schwarze  245: .Vt struct tbl_span
1.1       schwarze  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
1.3       schwarze  423: .Pa html.h
1.1       schwarze  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
1.3       schwarze  457: .Pa term.h
1.1       schwarze  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.
1.3       schwarze  476: .It Qq Pa manconf.h
1.1       schwarze  477: Requires
                    478: .In sys/types.h
                    479: for
                    480: .Vt size_t .
                    481: .Pp
                    482: Provides
1.3       schwarze  483: .Vt struct manconf ,
                    484: .Vt struct manpaths ,
                    485: .Vt struct manoutput ,
1.1       schwarze  486: and the functions
1.3       schwarze  487: .Fn manconf_parse ,
                    488: .Fn manconf_output ,
1.1       schwarze  489: and
1.3       schwarze  490: .Fn manconf_free .
1.1       schwarze  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
1.3       schwarze  514: .Pa manconf.h
1.1       schwarze  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

CVSweb