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

Annotation of mandoc/mandoc_headers.3, Revision 1.8

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

CVSweb