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

Annotation of mandoc/mandoc_headers.3, Revision 1.18

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

CVSweb