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

Annotation of mandoc/mandoc_headers.3, Revision 1.10

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 .
1.8       schwarze   65: .It Qq Pa mandoc_ohash.h
                     66: Includes
                     67: .In ohash.h
                     68: and provides
                     69: .Fn mandoc_ohash_init .
1.1       schwarze   70: .It Qq Pa mandoc.h
                     71: Requires
                     72: .In sys/types.h
                     73: for
                     74: .Vt size_t .
                     75: .Pp
                     76: Provides
                     77: .Vt enum mandoc_esc ,
                     78: .Vt enum mandocerr ,
                     79: .Vt enum mandoclevel ,
                     80: .Vt enum tbl_cellt ,
                     81: .Vt enum tbl_datt ,
                     82: .Vt enum tbl_spant ,
                     83: .Vt enum eqn_boxt ,
                     84: .Vt enum eqn_fontt ,
                     85: .Vt enum eqn_pilet ,
                     86: .Vt enum eqn_post ,
                     87: .Vt struct tbl_opts ,
                     88: .Vt struct tbl_cell ,
                     89: .Vt struct tbl_row ,
                     90: .Vt struct tbl_dat ,
                     91: .Vt struct tbl_span ,
                     92: .Vt struct eqn_box ,
                     93: .Vt struct eqn ,
                     94: the function prototype typedef
                     95: .Fn mandocmsg ,
                     96: the function
                     97: .Xr mandoc_escape 3 ,
                     98: the functions described in
                     99: .Xr mchars_alloc 3 ,
                    100: and the functions
                    101: .Fn mparse_*
                    102: described in
                    103: .Xr mandoc 3 .
                    104: .Pp
1.7       schwarze  105: Uses the opaque type
1.1       schwarze  106: .Vt struct mparse
                    107: from
                    108: .Pa read.c
                    109: for function prototypes.
1.8       schwarze  110: Uses the type
                    111: .Vt struct roff_man
1.1       schwarze  112: from
1.8       schwarze  113: .Pa roff.h
                    114: as an opaque type for function prototypes.
1.4       schwarze  115: .It Qq Pa roff.h
                    116: Provides
1.5       schwarze  117: .Vt enum mdoc_endbody ,
1.8       schwarze  118: .Vt enum roff_macroset ,
                    119: .Vt enum roff_next ,
1.5       schwarze  120: .Vt enum roff_sec ,
1.10    ! schwarze  121: .Vt enum roff_tok ,
1.5       schwarze  122: .Vt enum roff_type ,
1.8       schwarze  123: .Vt struct roff_man ,
1.6       schwarze  124: .Vt struct roff_meta ,
1.8       schwarze  125: .Vt struct roff_node ,
1.10    ! schwarze  126: the constant array
        !           127: .Va roff_name
1.8       schwarze  128: and the function
                    129: .Fn deroff .
1.5       schwarze  130: .Pp
                    131: Uses pointers to the types
                    132: .Vt struct mdoc_arg
                    133: and
                    134: .Vt union mdoc_data
                    135: from
1.8       schwarze  136: .Pa mdoc.h
1.5       schwarze  137: as opaque struct members.
1.4       schwarze  138: .El
                    139: .Pp
                    140: The following two require
                    141: .Qq Pa roff.h
                    142: but no other mandoc headers.
                    143: Afterwards, any other mandoc headers can be included as needed.
                    144: .Bl -tag -width Ds
1.1       schwarze  145: .It Qq Pa mdoc.h
                    146: Requires
                    147: .In sys/types.h
                    148: for
1.8       schwarze  149: .Vt size_t .
1.1       schwarze  150: .Pp
                    151: Provides
                    152: .Vt enum mdocargt ,
1.8       schwarze  153: .Vt enum mdoc_auth ,
1.1       schwarze  154: .Vt enum mdoc_disp ,
1.8       schwarze  155: .Vt enum mdoc_font ,
1.1       schwarze  156: .Vt enum mdoc_list ,
                    157: .Vt struct mdoc_argv ,
                    158: .Vt struct mdoc_arg ,
1.8       schwarze  159: .Vt struct mdoc_an ,
1.1       schwarze  160: .Vt struct mdoc_bd ,
1.8       schwarze  161: .Vt struct mdoc_bf ,
1.1       schwarze  162: .Vt struct mdoc_bl ,
                    163: .Vt struct mdoc_rs ,
1.8       schwarze  164: .Vt union mdoc_data ,
1.1       schwarze  165: and the functions
                    166: .Fn mdoc_*
                    167: described in
                    168: .Xr mandoc 3 .
                    169: .Pp
                    170: Uses the type
1.8       schwarze  171: .Vt struct roff_man
1.1       schwarze  172: from
1.8       schwarze  173: .Pa roff.h
1.1       schwarze  174: as an opaque type for function prototypes.
                    175: .Pp
                    176: When this header is included, the same file should not include
                    177: .Pa libman.h
                    178: or
                    179: .Pa libroff.h .
                    180: .It Qq Pa man.h
1.6       schwarze  181: Provides the functions
1.1       schwarze  182: .Fn man_*
                    183: described in
                    184: .Xr mandoc 3 .
                    185: .Pp
                    186: Uses the opaque type
                    187: .Vt struct mparse
                    188: from
                    189: .Pa read.c
                    190: for function prototypes.
                    191: Uses the type
1.8       schwarze  192: .Vt struct roff_man
1.1       schwarze  193: from
1.8       schwarze  194: .Pa roff.h
1.1       schwarze  195: as an opaque type for function prototypes.
                    196: .Pp
                    197: When this header is included, the same file should not include
                    198: .Pa libmdoc.h
                    199: or
                    200: .Pa libroff.h .
                    201: .El
                    202: .Ss Parser internals
                    203: The following headers require inclusion of a parser interface header
1.9       schwarze  204: before they can be included.
                    205: All parser interface headers should precede all parser internal headers.
                    206: When any parser internal headers are included, the same file should
                    207: not include any formatter headers.
1.1       schwarze  208: .Bl -tag -width Ds
                    209: .It Qq Pa libmandoc.h
                    210: Requires
                    211: .In sys/types.h
                    212: for
1.8       schwarze  213: .Vt size_t
                    214: and
1.6       schwarze  215: .Qq Pa mandoc.h
                    216: for
1.8       schwarze  217: .Vt enum mandocerr .
1.1       schwarze  218: .Pp
                    219: Provides
                    220: .Vt enum rofferr ,
                    221: .Vt struct buf ,
                    222: utility functions needed by multiple parsers,
                    223: and the top-level functions to call the parsers.
                    224: .Pp
                    225: Uses the opaque types
                    226: .Vt struct mparse
                    227: from
                    228: .Pa read.c
                    229: and
                    230: .Vt struct roff
                    231: from
                    232: .Pa roff.c
                    233: for function prototypes.
                    234: Uses the types
1.2       schwarze  235: .Vt struct tbl_span
1.1       schwarze  236: and
                    237: .Vt struct eqn
                    238: from
1.8       schwarze  239: .Pa mandoc.h
                    240: and
                    241: .Vt struct roff_man
                    242: from
                    243: .Pa roff.h
                    244: as opaque types for function prototypes.
                    245: .It Qq Pa roff_int.h
                    246: Requires
                    247: .Qq Pa roff.h
                    248: for
                    249: .Vt enum roff_type .
                    250: .Pp
                    251: Provides functions named
                    252: .Fn roff_*
                    253: to handle roff nodes and the two special functions
                    254: .Fn man_breakscope
                    255: and
                    256: .Fn mdoc_argv_free
                    257: because the latter two are needed by
                    258: .Qq Pa roff.c .
                    259: .Pp
                    260: Uses the types
                    261: .Vt struct eqn
                    262: and
                    263: .Vt struct tbl_span
                    264: from
1.1       schwarze  265: .Pa mandoc.h ,
1.8       schwarze  266: .Vt struct roff_man
                    267: and
                    268: .Vt struct roff_node
1.1       schwarze  269: from
1.8       schwarze  270: .Pa roff.h ,
1.1       schwarze  271: and
1.8       schwarze  272: .Vt struct mdoc_arg
1.1       schwarze  273: from
1.8       schwarze  274: .Pa mdoc.h
1.1       schwarze  275: as opaque types for function prototypes.
                    276: .It Qq Pa libmdoc.h
                    277: Requires
1.10    ! schwarze  278: .Qq Pa roff.h
        !           279: for
        !           280: .Vt enum roff_tok
        !           281: and
1.1       schwarze  282: .Qq Pa mdoc.h
                    283: for
1.5       schwarze  284: .Vt enum mdoc_*
1.1       schwarze  285: and
                    286: .Vt struct mdoc_* .
                    287: .Pp
                    288: Provides
                    289: .Vt enum margserr ,
                    290: .Vt enum mdelim ,
                    291: .Vt struct mdoc_macro ,
                    292: and many functions internal to the
                    293: .Xr mdoc 7
                    294: parser.
                    295: .Pp
1.8       schwarze  296: Uses the opaque type
1.1       schwarze  297: .Vt struct mparse
                    298: from
1.8       schwarze  299: .Pa read.c .
                    300: Uses the types
                    301: .Vt struct roff_man
1.1       schwarze  302: and
1.8       schwarze  303: .Vt struct roff_node
1.1       schwarze  304: from
1.8       schwarze  305: .Pa roff.h
                    306: as opaque types for function prototypes.
1.1       schwarze  307: .Pp
                    308: When this header is included, the same file should not include
                    309: .Pa man.h ,
                    310: .Pa libman.h ,
                    311: or
                    312: .Pa libroff.h .
                    313: .It Qq Pa libman.h
1.10    ! schwarze  314: Requires
        !           315: .Qq Pa roff.h
        !           316: for
        !           317: .Vt enum roff_tok .
1.1       schwarze  318: Provides
1.8       schwarze  319: .Vt struct man_macro
                    320: and some functions internal to the
1.1       schwarze  321: .Xr man 7
                    322: parser.
                    323: .Pp
1.8       schwarze  324: Uses the types
                    325: .Vt struct roff_man
1.1       schwarze  326: and
1.8       schwarze  327: .Vt struct roff_node
1.1       schwarze  328: from
1.8       schwarze  329: .Pa roff.h
                    330: as opaque types for function prototypes.
1.1       schwarze  331: .Pp
                    332: When this header is included, the same file should not include
                    333: .Pa mdoc.h ,
                    334: .Pa libmdoc.h ,
                    335: or
                    336: .Pa libroff.h .
                    337: .It Qq Pa libroff.h
                    338: Requires
                    339: .In sys/types.h
                    340: for
                    341: .Vt size_t ,
                    342: .Qq Pa mandoc.h
                    343: for
                    344: .Vt struct tbl_*
                    345: and
                    346: .Vt struct eqn ,
                    347: and
                    348: .Qq Pa libmandoc.h
                    349: for
                    350: .Vt enum rofferr .
                    351: .Pp
                    352: Provides
                    353: .Vt enum tbl_part ,
                    354: .Vt struct tbl_node ,
                    355: .Vt struct eqn_def ,
                    356: .Vt struct eqn_node ,
                    357: and many functions internal to the
                    358: .Xr tbl 7
                    359: and
                    360: .Xr eqn 7
                    361: parsers.
                    362: .Pp
                    363: Uses the opaque type
                    364: .Vt struct mparse
                    365: from
                    366: .Pa read.c .
                    367: .Pp
                    368: When this header is included, the same file should not include
                    369: .Pa man.h ,
                    370: .Pa mdoc.h ,
                    371: .Pa libman.h ,
                    372: or
                    373: .Pa libmdoc.h .
                    374: .El
                    375: .Ss Formatter interface
                    376: These headers should be included after any parser interface headers.
                    377: No parser internal headers should be included by the same file.
                    378: .Bl -tag -width Ds
                    379: .It Qq Pa out.h
                    380: Requires
                    381: .In sys/types.h
                    382: for
                    383: .Vt size_t .
                    384: .Pp
                    385: Provides
                    386: .Vt enum roffscale ,
                    387: .Vt struct roffcol ,
                    388: .Vt struct roffsu ,
                    389: .Vt struct rofftbl ,
                    390: .Fn a2roffsu ,
                    391: and
                    392: .Fn tblcalc .
                    393: .Pp
                    394: Uses
                    395: .Vt struct tbl_span
                    396: from
                    397: .Pa mandoc.h
                    398: as an opaque type for function prototypes.
                    399: .Pp
                    400: When this header is included, the same file should not include
                    401: .Pa mansearch.h .
                    402: .It Qq Pa term.h
                    403: Requires
                    404: .In sys/types.h
                    405: for
                    406: .Vt size_t
                    407: and
                    408: .Qq Pa out.h
                    409: for
                    410: .Vt struct roffsu
                    411: and
                    412: .Vt struct rofftbl .
                    413: .Pp
                    414: Provides
                    415: .Vt enum termenc ,
                    416: .Vt enum termfont ,
                    417: .Vt enum termtype ,
                    418: .Vt struct termp_tbl ,
                    419: .Vt struct termp ,
                    420: and many terminal formatting functions.
                    421: .Pp
1.7       schwarze  422: Uses the opaque type
1.1       schwarze  423: .Vt struct termp_ps
                    424: from
                    425: .Pa term_ps.c .
                    426: Uses
                    427: .Vt struct tbl_span
                    428: and
                    429: .Vt struct eqn
                    430: from
                    431: .Pa mandoc.h
1.6       schwarze  432: and
                    433: .Vt struct roff_meta
                    434: from
1.8       schwarze  435: .Pa roff.h
1.1       schwarze  436: as opaque types for function prototypes.
                    437: .Pp
                    438: When this header is included, the same file should not include
1.3       schwarze  439: .Pa html.h
1.1       schwarze  440: or
                    441: .Pa mansearch.h .
                    442: .It Qq Pa html.h
                    443: Requires
                    444: .In sys/types.h
                    445: for
                    446: .Vt size_t ,
                    447: .In stdio.h
                    448: for
                    449: .Dv BUFSIZ ,
                    450: and
                    451: .Qq Pa out.h
                    452: for
                    453: .Vt struct roffsu
                    454: and
                    455: .Vt struct rofftbl .
                    456: .Pp
                    457: Provides
                    458: .Vt enum htmltag ,
                    459: .Vt enum htmlattr ,
                    460: .Vt enum htmlfont ,
                    461: .Vt struct tag ,
                    462: .Vt struct tagq ,
                    463: .Vt struct htmlpair ,
                    464: .Vt struct html ,
                    465: and many HTML formatting functions.
                    466: .Pp
                    467: When this header is included, the same file should not include
1.3       schwarze  468: .Pa term.h
1.1       schwarze  469: or
                    470: .Pa mansearch.h .
1.8       schwarze  471: .It Qq Pa tag.h
                    472: Requires
                    473: .In sys/types.h
                    474: for
                    475: .Vt size_t .
                    476: .Pp
                    477: Provides an interface to generate
                    478: .Xr ctags 1
                    479: files for the
                    480: .Ic :t
                    481: functionality mentioned in
                    482: .Xr man 1 .
1.1       schwarze  483: .It Qq Pa main.h
                    484: Provides the top level steering functions for all formatters.
                    485: .Pp
1.8       schwarze  486: Uses the type
                    487: .Vt struct roff_man
1.1       schwarze  488: from
1.8       schwarze  489: .Pa roff.h
                    490: as an opaque type for function prototypes.
1.3       schwarze  491: .It Qq Pa manconf.h
1.1       schwarze  492: Requires
                    493: .In sys/types.h
                    494: for
                    495: .Vt size_t .
                    496: .Pp
                    497: Provides
1.3       schwarze  498: .Vt struct manconf ,
                    499: .Vt struct manpaths ,
                    500: .Vt struct manoutput ,
1.1       schwarze  501: and the functions
1.3       schwarze  502: .Fn manconf_parse ,
                    503: .Fn manconf_output ,
1.1       schwarze  504: and
1.3       schwarze  505: .Fn manconf_free .
1.1       schwarze  506: .It Qq Pa mansearch.h
                    507: Requires
                    508: .In sys/types.h
                    509: for
                    510: .Vt size_t
                    511: and
                    512: .In stdint.h
                    513: for
                    514: .Vt uint64_t .
                    515: .Pp
                    516: Provides
                    517: .Vt enum argmode ,
                    518: .Vt struct manpage ,
                    519: .Vt struct mansearch ,
                    520: and the functions
1.9       schwarze  521: .Fn mansearch
1.1       schwarze  522: and
                    523: .Fn mansearch_free .
                    524: .Pp
                    525: Uses
                    526: .Vt struct manpaths
                    527: from
1.3       schwarze  528: .Pa manconf.h
1.1       schwarze  529: as an opaque type for function prototypes.
                    530: .Pp
                    531: When this header is included, the same file should not include
                    532: .Pa out.h ,
                    533: .Pa term.h ,
                    534: or
                    535: .Pa html.h .
                    536: .El

CVSweb