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

Annotation of mandoc/mandoc_headers.3, Revision 1.28

1.28    ! schwarze    1: .Dd $Mdocdate: December 14 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
1.28    ! schwarze  195: Uses the opaque type
1.26      schwarze  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 type
1.8       schwarze  264: .Vt struct roff_man
1.1       schwarze  265: from
1.8       schwarze  266: .Pa roff.h
1.1       schwarze  267: as an opaque type for function prototypes.
                    268: .Pp
                    269: When this header is included, the same file should not include
1.22      schwarze  270: internals of different parsers.
1.1       schwarze  271: .El
                    272: .Ss Parser internals
1.21      schwarze  273: Most of the following headers require inclusion of a parser interface header
1.9       schwarze  274: before they can be included.
                    275: All parser interface headers should precede all parser internal headers.
                    276: When any parser internal headers are included, the same file should
                    277: not include any formatter headers.
1.1       schwarze  278: .Bl -tag -width Ds
                    279: .It Qq Pa libmandoc.h
                    280: Requires
                    281: .In sys/types.h
                    282: for
1.8       schwarze  283: .Vt size_t
                    284: and
1.6       schwarze  285: .Qq Pa mandoc.h
                    286: for
1.8       schwarze  287: .Vt enum mandocerr .
1.1       schwarze  288: .Pp
                    289: Provides
                    290: .Vt struct buf ,
                    291: utility functions needed by multiple parsers,
                    292: and the top-level functions to call the parsers.
                    293: .Pp
1.28    ! schwarze  294: Uses the opaque type
1.1       schwarze  295: .Vt struct roff
                    296: from
                    297: .Pa roff.c
                    298: for function prototypes.
1.18      schwarze  299: Uses the type
1.8       schwarze  300: .Vt struct roff_man
                    301: from
                    302: .Pa roff.h
1.18      schwarze  303: as an opaque type for function prototypes.
1.8       schwarze  304: .It Qq Pa roff_int.h
1.24      schwarze  305: Parser internals shared by multiple parsers.
                    306: Can be used in all parsers, but not in main programs or formatters.
                    307: .Pp
1.8       schwarze  308: Requires
                    309: .Qq Pa roff.h
                    310: for
1.24      schwarze  311: .Vt enum roff_type
                    312: and
                    313: .Vt enum roff_tok .
1.8       schwarze  314: .Pp
                    315: Provides functions named
                    316: .Fn roff_*
1.24      schwarze  317: to handle roff nodes,
                    318: .Fn roffhash_alloc ,
                    319: .Fn roffhash_find ,
                    320: and
                    321: .Fn roffhash_free ,
                    322: and the two special functions
1.8       schwarze  323: .Fn man_breakscope
                    324: and
                    325: .Fn mdoc_argv_free
                    326: because the latter two are needed by
                    327: .Qq Pa roff.c .
                    328: .Pp
                    329: Uses the types
                    330: .Vt struct roff_man
                    331: and
                    332: .Vt struct roff_node
1.1       schwarze  333: from
1.18      schwarze  334: .Pa roff.h
1.1       schwarze  335: and
1.8       schwarze  336: .Vt struct mdoc_arg
1.1       schwarze  337: from
1.8       schwarze  338: .Pa mdoc.h
1.1       schwarze  339: as opaque types for function prototypes.
                    340: .It Qq Pa libmdoc.h
                    341: Requires
1.10      schwarze  342: .Qq Pa roff.h
                    343: for
                    344: .Vt enum roff_tok
                    345: and
1.25      schwarze  346: .Vt enum roff_sec .
1.1       schwarze  347: .Pp
                    348: Provides
                    349: .Vt enum margserr ,
                    350: .Vt enum mdelim ,
                    351: .Vt struct mdoc_macro ,
                    352: and many functions internal to the
                    353: .Xr mdoc 7
                    354: parser.
                    355: .Pp
1.8       schwarze  356: Uses the types
                    357: .Vt struct roff_man
1.1       schwarze  358: and
1.8       schwarze  359: .Vt struct roff_node
1.1       schwarze  360: from
1.8       schwarze  361: .Pa roff.h
1.25      schwarze  362: and
                    363: .Vt struct mdoc_arg
                    364: from
                    365: .Pa mdoc.h
1.8       schwarze  366: as opaque types for function prototypes.
1.1       schwarze  367: .Pp
                    368: When this header is included, the same file should not include
1.22      schwarze  369: interfaces of different parsers.
1.1       schwarze  370: .It Qq Pa libman.h
1.10      schwarze  371: Requires
                    372: .Qq Pa roff.h
                    373: for
                    374: .Vt enum roff_tok .
1.11      schwarze  375: .Pp
1.1       schwarze  376: Provides
1.8       schwarze  377: .Vt struct man_macro
                    378: and some functions internal to the
1.1       schwarze  379: .Xr man 7
                    380: parser.
                    381: .Pp
1.8       schwarze  382: Uses the types
                    383: .Vt struct roff_man
1.1       schwarze  384: and
1.8       schwarze  385: .Vt struct roff_node
1.1       schwarze  386: from
1.8       schwarze  387: .Pa roff.h
                    388: as opaque types for function prototypes.
1.1       schwarze  389: .Pp
                    390: When this header is included, the same file should not include
1.22      schwarze  391: interfaces of different parsers.
                    392: .It Qq Pa eqn_parse.h
                    393: External interface of the
                    394: .Xr eqn 7
                    395: parser, for use in the
                    396: .Xr roff 7
                    397: and
                    398: .Xr eqn 7
                    399: parsers only.
                    400: .Pp
1.1       schwarze  401: Requires
                    402: .In sys/types.h
                    403: for
1.22      schwarze  404: .Vt size_t .
1.1       schwarze  405: .Pp
                    406: Provides
1.22      schwarze  407: .Vt struct eqn_node
                    408: and the functions
                    409: .Fn eqn_alloc ,
1.23      schwarze  410: .Fn eqn_box_new ,
1.22      schwarze  411: .Fn eqn_box_free ,
                    412: .Fn eqn_free ,
                    413: .Fn eqn_parse ,
                    414: .Fn eqn_read ,
                    415: and
                    416: .Fn eqn_reset .
1.1       schwarze  417: .Pp
1.22      schwarze  418: Uses the type
                    419: .Vt struct eqn_box
                    420: from
                    421: .Pa mandoc.h
                    422: as an opaque type for function prototypes.
                    423: Uses the types
                    424: .Vt struct roff_node
                    425: from
                    426: .Pa roff.h
                    427: and
                    428: .Vt struct eqn_def
                    429: from
                    430: .Pa eqn.c
                    431: as opaque struct members.
1.1       schwarze  432: .Pp
                    433: When this header is included, the same file should not include
1.22      schwarze  434: internals of different parsers.
1.21      schwarze  435: .It Qq Pa tbl_parse.h
                    436: External interface of the
                    437: .Xr tbl 7
                    438: parser, for use in the
                    439: .Xr roff 7
                    440: and
                    441: .Xr tbl 7
                    442: parsers only.
                    443: .Pp
                    444: Provides the functions documented in
                    445: .Xr tbl 3 .
                    446: .Pp
                    447: Uses the types
                    448: .Vt struct tbl_span
                    449: from
                    450: .Pa tbl.h
                    451: and
                    452: .Vt struct tbl_node
                    453: from
                    454: .Pa tbl_int.h
                    455: as opaque types for function prototypes.
                    456: .Pp
                    457: When this header is included, the same file should not include
1.22      schwarze  458: internals of different parsers.
1.21      schwarze  459: .It Qq Pa tbl_int.h
                    460: Internal interfaces of the
                    461: .Xr tbl 7
                    462: parser, for use inside the
                    463: .Xr tbl 7
                    464: parser only.
                    465: .Pp
                    466: Requires
                    467: .Qq Pa tbl.h
                    468: for
                    469: .Vt struct tbl_opts .
                    470: .Pp
                    471: Provides
                    472: .Vt enum tbl_part ,
                    473: .Vt struct tbl_node ,
                    474: and the functions
                    475: .Fn tbl_option ,
                    476: .Fn tbl_layout ,
                    477: .Fn tbl_data ,
                    478: .Fn tbl_cdata ,
                    479: and
                    480: .Fn tbl_reset .
                    481: .Pp
                    482: When this header is included, the same file should not include
                    483: interfaces of different parsers.
1.1       schwarze  484: .El
                    485: .Ss Formatter interface
                    486: These headers should be included after any parser interface headers.
                    487: No parser internal headers should be included by the same file.
                    488: .Bl -tag -width Ds
                    489: .It Qq Pa out.h
                    490: Requires
                    491: .In sys/types.h
                    492: for
                    493: .Vt size_t .
                    494: .Pp
                    495: Provides
                    496: .Vt enum roffscale ,
                    497: .Vt struct roffcol ,
                    498: .Vt struct roffsu ,
                    499: .Vt struct rofftbl ,
                    500: .Fn a2roffsu ,
                    501: and
                    502: .Fn tblcalc .
                    503: .Pp
                    504: Uses
                    505: .Vt struct tbl_span
                    506: from
                    507: .Pa mandoc.h
                    508: as an opaque type for function prototypes.
                    509: .Pp
                    510: When this header is included, the same file should not include
                    511: .Pa mansearch.h .
                    512: .It Qq Pa term.h
                    513: Requires
                    514: .In sys/types.h
                    515: for
                    516: .Vt size_t
                    517: and
                    518: .Qq Pa out.h
                    519: for
                    520: .Vt struct roffsu
                    521: and
                    522: .Vt struct rofftbl .
                    523: .Pp
                    524: Provides
                    525: .Vt enum termenc ,
                    526: .Vt enum termfont ,
                    527: .Vt enum termtype ,
                    528: .Vt struct termp_tbl ,
                    529: .Vt struct termp ,
1.12      schwarze  530: .Fn roff_term_pre ,
1.1       schwarze  531: and many terminal formatting functions.
                    532: .Pp
1.7       schwarze  533: Uses the opaque type
1.1       schwarze  534: .Vt struct termp_ps
                    535: from
                    536: .Pa term_ps.c .
                    537: Uses
                    538: .Vt struct tbl_span
                    539: and
1.17      schwarze  540: .Vt struct eqn_box
1.1       schwarze  541: from
                    542: .Pa mandoc.h
1.6       schwarze  543: and
                    544: .Vt struct roff_meta
1.12      schwarze  545: and
                    546: .Vt struct roff_node
1.6       schwarze  547: from
1.8       schwarze  548: .Pa roff.h
1.1       schwarze  549: as opaque types for function prototypes.
                    550: .Pp
                    551: When this header is included, the same file should not include
1.3       schwarze  552: .Pa html.h
1.1       schwarze  553: or
                    554: .Pa mansearch.h .
                    555: .It Qq Pa html.h
                    556: Requires
                    557: .In sys/types.h
                    558: for
1.11      schwarze  559: .Vt size_t
1.1       schwarze  560: and
                    561: .Qq Pa out.h
                    562: for
                    563: .Vt struct roffsu
                    564: and
                    565: .Vt struct rofftbl .
                    566: .Pp
                    567: Provides
                    568: .Vt enum htmltag ,
                    569: .Vt enum htmlattr ,
                    570: .Vt enum htmlfont ,
                    571: .Vt struct tag ,
                    572: .Vt struct tagq ,
                    573: .Vt struct htmlpair ,
                    574: .Vt struct html ,
1.12      schwarze  575: .Fn roff_html_pre ,
1.1       schwarze  576: and many HTML formatting functions.
1.12      schwarze  577: .Pp
                    578: Uses
                    579: .Vt struct tbl_span
                    580: and
1.17      schwarze  581: .Vt struct eqn_box
1.12      schwarze  582: from
                    583: .Pa mandoc.h
                    584: and
                    585: .Vt struct roff_node
                    586: from
                    587: .Pa roff.h
                    588: as opaque types for function prototypes.
1.1       schwarze  589: .Pp
                    590: When this header is included, the same file should not include
1.3       schwarze  591: .Pa term.h
1.1       schwarze  592: or
                    593: .Pa mansearch.h .
1.8       schwarze  594: .It Qq Pa tag.h
                    595: Requires
                    596: .In sys/types.h
                    597: for
                    598: .Vt size_t .
                    599: .Pp
                    600: Provides an interface to generate
                    601: .Xr ctags 1
                    602: files for the
                    603: .Ic :t
                    604: functionality mentioned in
                    605: .Xr man 1 .
1.1       schwarze  606: .It Qq Pa main.h
                    607: Provides the top level steering functions for all formatters.
                    608: .Pp
1.8       schwarze  609: Uses the type
                    610: .Vt struct roff_man
1.1       schwarze  611: from
1.8       schwarze  612: .Pa roff.h
                    613: as an opaque type for function prototypes.
1.3       schwarze  614: .It Qq Pa manconf.h
1.1       schwarze  615: Requires
                    616: .In sys/types.h
                    617: for
                    618: .Vt size_t .
                    619: .Pp
                    620: Provides
1.3       schwarze  621: .Vt struct manconf ,
                    622: .Vt struct manpaths ,
                    623: .Vt struct manoutput ,
1.1       schwarze  624: and the functions
1.3       schwarze  625: .Fn manconf_parse ,
                    626: .Fn manconf_output ,
1.15      schwarze  627: .Fn manconf_free ,
1.1       schwarze  628: and
1.15      schwarze  629: .Fn manpath_base .
1.1       schwarze  630: .It Qq Pa mansearch.h
                    631: Requires
                    632: .In sys/types.h
                    633: for
                    634: .Vt size_t
                    635: and
                    636: .In stdint.h
                    637: for
                    638: .Vt uint64_t .
                    639: .Pp
                    640: Provides
                    641: .Vt enum argmode ,
                    642: .Vt struct manpage ,
                    643: .Vt struct mansearch ,
                    644: and the functions
1.9       schwarze  645: .Fn mansearch
1.1       schwarze  646: and
                    647: .Fn mansearch_free .
                    648: .Pp
                    649: Uses
                    650: .Vt struct manpaths
                    651: from
1.3       schwarze  652: .Pa manconf.h
1.1       schwarze  653: as an opaque type for function prototypes.
                    654: .Pp
                    655: When this header is included, the same file should not include
                    656: .Pa out.h ,
                    657: .Pa term.h ,
                    658: or
                    659: .Pa html.h .
                    660: .El

CVSweb