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

Annotation of mandoc/mandoc_headers.3, Revision 1.15

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

CVSweb