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

Annotation of mandoc/mandoc_headers.3, Revision 1.27

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

CVSweb