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

Annotation of mandoc/mandoc_headers.3, Revision 1.24

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

CVSweb