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

Annotation of mandoc/mandoc_headers.3, Revision 1.1

1.1     ! schwarze    1: .Dd December 1, 2014
        !             2: .Dt MANDOC_HEADERS 3
        !             3: .Os
        !             4: .Sh NAME
        !             5: .Nm mandoc_headers
        !             6: .Nd ordering of mandoc include files
        !             7: .Sh DESCRIPTION
        !             8: To support a cleaner coding style, the mandoc header files do not
        !             9: contain any include directives and do not guard against multiple
        !            10: inclusion.
        !            11: The application developer has to make sure that the headers are
        !            12: included in a proper order, and that no header is included more
        !            13: than once.
        !            14: .Pp
        !            15: The headers and functions form three major groups:
        !            16: .Sx Parser interface ,
        !            17: .Sx Parser internals ,
        !            18: and
        !            19: .Sx Formatter interface .
        !            20: .Pp
        !            21: Various rules are given below prohibiting the inclusion of certain
        !            22: combinations of headers into the same file.
        !            23: The intention is to keep the following functional components
        !            24: separate from each other:
        !            25: .Pp
        !            26: .Bl -dash -offset indent -compact
        !            27: .It
        !            28: .Xr mdoc 7
        !            29: parser
        !            30: .It
        !            31: .Xr man 7
        !            32: parser
        !            33: .It
        !            34: .Xr roff 7
        !            35: parser
        !            36: .It
        !            37: .Xr tbl 7
        !            38: parser
        !            39: .It
        !            40: .Xr eqn 7
        !            41: parser
        !            42: .It
        !            43: terminal formatters
        !            44: .It
        !            45: HTML formatters
        !            46: .It
        !            47: search tools
        !            48: .El
        !            49: .Pp
        !            50: Note that mere usage of an opaque type does
        !            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: Afterwards, any other mandoc headers can be included as needed.
        !            58: .Bl -tag -width Ds
        !            59: .It Qq Pa mandoc_aux.h
        !            60: Requires
        !            61: .In sys/types.h
        !            62: for
        !            63: .Vt size_t .
        !            64: Provides the utility functions documented in
        !            65: .Xr mandoc_malloc 3 .
        !            66: .It Qq Pa mandoc.h
        !            67: Requires
        !            68: .In sys/types.h
        !            69: for
        !            70: .Vt size_t .
        !            71: .Pp
        !            72: Provides
        !            73: .Vt enum mandoc_esc ,
        !            74: .Vt enum mandocerr ,
        !            75: .Vt enum mandoclevel ,
        !            76: .Vt enum tbl_cellt ,
        !            77: .Vt enum tbl_datt ,
        !            78: .Vt enum tbl_spant ,
        !            79: .Vt enum eqn_boxt ,
        !            80: .Vt enum eqn_fontt ,
        !            81: .Vt enum eqn_pilet ,
        !            82: .Vt enum eqn_post ,
        !            83: .Vt struct tbl_opts ,
        !            84: .Vt struct tbl_head ,
        !            85: .Vt struct tbl_cell ,
        !            86: .Vt struct tbl_row ,
        !            87: .Vt struct tbl_dat ,
        !            88: .Vt struct tbl_span ,
        !            89: .Vt struct eqn_box ,
        !            90: .Vt struct eqn ,
        !            91: the function prototype typedef
        !            92: .Fn mandocmsg ,
        !            93: the function
        !            94: .Xr mandoc_escape 3 ,
        !            95: the functions described in
        !            96: .Xr mchars_alloc 3 ,
        !            97: and the functions
        !            98: .Fn mparse_*
        !            99: described in
        !           100: .Xr mandoc 3 .
        !           101: .Pp
        !           102: Uses the opaque types
        !           103: .Vt struct mparse
        !           104: from
        !           105: .Pa read.c
        !           106: and
        !           107: .Vt struct mchars
        !           108: from
        !           109: .Pa chars.c
        !           110: for function prototypes.
        !           111: Uses the types
        !           112: .Vt struct mdoc
        !           113: from
        !           114: .Pa libmdoc.h
        !           115: and
        !           116: .Vt struct man
        !           117: from
        !           118: .Pa libman.h
        !           119: as opaque types for function prototypes.
        !           120: .It Qq Pa mdoc.h
        !           121: Requires
        !           122: .In sys/types.h
        !           123: for
        !           124: .Vt size_t .
        !           125: .Pp
        !           126: Provides
        !           127: .Vt enum mdoct ,
        !           128: .Vt enum mdocargt ,
        !           129: .Vt enum mdoc_type ,
        !           130: .Vt enum mdoc_sec ,
        !           131: .Vt enum mdoc_endbody ,
        !           132: .Vt enum mdoc_disp ,
        !           133: .Vt enum mdoc_list ,
        !           134: .Vt enum mdoc_auth ,
        !           135: .Vt enum mdoc_font ,
        !           136: .Vt struct mdoc_meta ,
        !           137: .Vt struct mdoc_argv ,
        !           138: .Vt struct mdoc_arg ,
        !           139: .Vt struct mdoc_bd ,
        !           140: .Vt struct mdoc_bl ,
        !           141: .Vt struct mdoc_an ,
        !           142: .Vt struct mdoc_bf ,
        !           143: .Vt struct mdoc_rs ,
        !           144: .Vt struct mdoc_node ,
        !           145: and the functions
        !           146: .Fn mdoc_*
        !           147: described in
        !           148: .Xr mandoc 3 .
        !           149: .Pp
        !           150: Uses the type
        !           151: .Vt struct mdoc
        !           152: from
        !           153: .Pa libmdoc.h
        !           154: as an opaque type for function prototypes.
        !           155: Uses pointers to the types
        !           156: .Vt struct tbl_span
        !           157: and
        !           158: .Vt struct eqn
        !           159: as opaque struct members.
        !           160: .Pp
        !           161: When this header is included, the same file should not include
        !           162: .Pa libman.h
        !           163: or
        !           164: .Pa libroff.h .
        !           165: .It Qq Pa man.h
        !           166: Provides
        !           167: .Vt enum mant ,
        !           168: .Vt enum man_type ,
        !           169: .Vt struct man_meta ,
        !           170: .Vt struct man_node ,
        !           171: and the functions
        !           172: .Fn man_*
        !           173: described in
        !           174: .Xr mandoc 3 .
        !           175: .Pp
        !           176: Uses the opaque type
        !           177: .Vt struct mparse
        !           178: from
        !           179: .Pa read.c
        !           180: for function prototypes.
        !           181: Uses the type
        !           182: .Vt struct man
        !           183: from
        !           184: .Pa libman.h
        !           185: as an opaque type for function prototypes.
        !           186: Uses pointers to the types
        !           187: .Vt struct tbl_span
        !           188: and
        !           189: .Vt struct eqn
        !           190: as opaque struct members.
        !           191: .Pp
        !           192: When this header is included, the same file should not include
        !           193: .Pa libmdoc.h
        !           194: or
        !           195: .Pa libroff.h .
        !           196: .El
        !           197: .Ss Parser internals
        !           198: The following headers require inclusion of a parser interface header
        !           199: before they can be included.  All parser interface headers should
        !           200: precede all parser internal headers.  When any parser internal headers
        !           201: are included, the same file should not include any formatter headers.
        !           202: .Bl -tag -width Ds
        !           203: .It Qq Pa libmandoc.h
        !           204: Requires
        !           205: .In sys/types.h
        !           206: for
        !           207: .Vt size_t .
        !           208: .Pp
        !           209: Provides
        !           210: .Vt enum rofferr ,
        !           211: .Vt struct buf ,
        !           212: utility functions needed by multiple parsers,
        !           213: and the top-level functions to call the parsers.
        !           214: .Pp
        !           215: Uses the opaque types
        !           216: .Vt struct mparse
        !           217: from
        !           218: .Pa read.c
        !           219: and
        !           220: .Vt struct roff
        !           221: from
        !           222: .Pa roff.c
        !           223: for function prototypes.
        !           224: Uses the types
        !           225: .Vt enum mandocerr ,
        !           226: .Vt struct tbl_span ,
        !           227: and
        !           228: .Vt struct eqn
        !           229: from
        !           230: .Pa mandoc.h ,
        !           231: .Vt struct mdoc
        !           232: from
        !           233: .Pa libmdoc.h ,
        !           234: and
        !           235: .Vt struct man
        !           236: from
        !           237: .Pa libman.h
        !           238: as opaque types for function prototypes.
        !           239: .It Qq Pa libmdoc.h
        !           240: Requires
        !           241: .Qq Pa mdoc.h
        !           242: for
        !           243: .Vt enum mdoct ,
        !           244: .Vt enum mdoc_* ,
        !           245: and
        !           246: .Vt struct mdoc_* .
        !           247: .Pp
        !           248: Provides
        !           249: .Vt enum mdoc_next ,
        !           250: .Vt enum margserr ,
        !           251: .Vt enum mdelim ,
        !           252: .Vt struct mdoc ,
        !           253: .Vt struct mdoc_macro ,
        !           254: and many functions internal to the
        !           255: .Xr mdoc 7
        !           256: parser.
        !           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: .Pp
        !           267: When this header is included, the same file should not include
        !           268: .Pa man.h ,
        !           269: .Pa libman.h ,
        !           270: or
        !           271: .Pa libroff.h .
        !           272: .It Qq Pa libman.h
        !           273: Requires
        !           274: .Qq Pa man.h
        !           275: for
        !           276: .Vt enum mant
        !           277: and
        !           278: .Vt struct man_node.
        !           279: .Pp
        !           280: Provides
        !           281: .Vt enum man_next ,
        !           282: .Vt struct man ,
        !           283: .Vt struct man_macro ,
        !           284: and many functions internal to the
        !           285: .Xr man 7
        !           286: parser.
        !           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: .Pp
        !           297: When this header is included, the same file should not include
        !           298: .Pa mdoc.h ,
        !           299: .Pa libmdoc.h ,
        !           300: or
        !           301: .Pa libroff.h .
        !           302: .It Qq Pa libroff.h
        !           303: Requires
        !           304: .In sys/types.h
        !           305: for
        !           306: .Vt size_t ,
        !           307: .Qq Pa mandoc.h
        !           308: for
        !           309: .Vt struct tbl_*
        !           310: and
        !           311: .Vt struct eqn ,
        !           312: and
        !           313: .Qq Pa libmandoc.h
        !           314: for
        !           315: .Vt enum rofferr .
        !           316: .Pp
        !           317: Provides
        !           318: .Vt enum tbl_part ,
        !           319: .Vt struct tbl_node ,
        !           320: .Vt struct eqn_def ,
        !           321: .Vt struct eqn_node ,
        !           322: and many functions internal to the
        !           323: .Xr tbl 7
        !           324: and
        !           325: .Xr eqn 7
        !           326: parsers.
        !           327: .Pp
        !           328: Uses the opaque type
        !           329: .Vt struct mparse
        !           330: from
        !           331: .Pa read.c .
        !           332: .Pp
        !           333: When this header is included, the same file should not include
        !           334: .Pa man.h ,
        !           335: .Pa mdoc.h ,
        !           336: .Pa libman.h ,
        !           337: or
        !           338: .Pa libmdoc.h .
        !           339: .El
        !           340: .Ss Formatter interface
        !           341: These headers should be included after any parser interface headers.
        !           342: No parser internal headers should be included by the same file.
        !           343: .Bl -tag -width Ds
        !           344: .It Qq Pa out.h
        !           345: Requires
        !           346: .In sys/types.h
        !           347: for
        !           348: .Vt size_t .
        !           349: .Pp
        !           350: Provides
        !           351: .Vt enum roffscale ,
        !           352: .Vt struct roffcol ,
        !           353: .Vt struct roffsu ,
        !           354: .Vt struct rofftbl ,
        !           355: .Fn a2roffsu ,
        !           356: and
        !           357: .Fn tblcalc .
        !           358: .Pp
        !           359: Uses
        !           360: .Vt struct tbl_span
        !           361: from
        !           362: .Pa mandoc.h
        !           363: as an opaque type for function prototypes.
        !           364: .Pp
        !           365: When this header is included, the same file should not include
        !           366: .Pa manpath.h
        !           367: or
        !           368: .Pa mansearch.h .
        !           369: .It Qq Pa term.h
        !           370: Requires
        !           371: .In sys/types.h
        !           372: for
        !           373: .Vt size_t
        !           374: and
        !           375: .Qq Pa out.h
        !           376: for
        !           377: .Vt struct roffsu
        !           378: and
        !           379: .Vt struct rofftbl .
        !           380: .Pp
        !           381: Provides
        !           382: .Vt enum termenc ,
        !           383: .Vt enum termfont ,
        !           384: .Vt enum termtype ,
        !           385: .Vt struct termp_tbl ,
        !           386: .Vt struct termp ,
        !           387: and many terminal formatting functions.
        !           388: .Pp
        !           389: Uses the opaque types
        !           390: .Vt struct mchars
        !           391: from
        !           392: .Pa chars.c
        !           393: and
        !           394: .Vt struct termp_ps
        !           395: from
        !           396: .Pa term_ps.c .
        !           397: Uses
        !           398: .Vt struct tbl_span
        !           399: and
        !           400: .Vt struct eqn
        !           401: from
        !           402: .Pa mandoc.h
        !           403: as opaque types for function prototypes.
        !           404: .Pp
        !           405: When this header is included, the same file should not include
        !           406: .Pa html.h ,
        !           407: .Pa manpath.h
        !           408: or
        !           409: .Pa mansearch.h .
        !           410: .It Qq Pa html.h
        !           411: Requires
        !           412: .In sys/types.h
        !           413: for
        !           414: .Vt size_t ,
        !           415: .In stdio.h
        !           416: for
        !           417: .Dv BUFSIZ ,
        !           418: and
        !           419: .Qq Pa out.h
        !           420: for
        !           421: .Vt struct roffsu
        !           422: and
        !           423: .Vt struct rofftbl .
        !           424: .Pp
        !           425: Provides
        !           426: .Vt enum htmltag ,
        !           427: .Vt enum htmlattr ,
        !           428: .Vt enum htmlfont ,
        !           429: .Vt struct tag ,
        !           430: .Vt struct tagq ,
        !           431: .Vt struct htmlpair ,
        !           432: .Vt struct html ,
        !           433: and many HTML formatting functions.
        !           434: .Pp
        !           435: Uses the opaque type
        !           436: .Vt struct mchars
        !           437: from
        !           438: .Pa chars.c .
        !           439: .Pp
        !           440: When this header is included, the same file should not include
        !           441: .Pa term.h ,
        !           442: .Pa manpath.h
        !           443: or
        !           444: .Pa mansearch.h .
        !           445: .It Qq Pa main.h
        !           446: Provides the top level steering functions for all formatters.
        !           447: .Pp
        !           448: Uses the opaque type
        !           449: .Vt struct mchars
        !           450: from
        !           451: .Pa chars.c .
        !           452: Uses the types
        !           453: .Vt struct mdoc
        !           454: from
        !           455: .Pa libmdoc.h
        !           456: and
        !           457: .Vt struct man
        !           458: from
        !           459: .Pa libman.h
        !           460: as opaque types for function prototypes.
        !           461: .It Qq Pa manpath.h
        !           462: Requires
        !           463: .In sys/types.h
        !           464: for
        !           465: .Vt size_t .
        !           466: .Pp
        !           467: Provides
        !           468: .Vt struct manpaths
        !           469: and the functions
        !           470: .Fn manpath_manconf ,
        !           471: .Fn manpath_parse ,
        !           472: and
        !           473: .Fn manpath_free .
        !           474: .Pp
        !           475: When this header is included, the same file should not include
        !           476: .Pa out.h ,
        !           477: .Pa term.h ,
        !           478: or
        !           479: .Pa html.h .
        !           480: .It Qq Pa mansearch.h
        !           481: Requires
        !           482: .In sys/types.h
        !           483: for
        !           484: .Vt size_t
        !           485: and
        !           486: .In stdint.h
        !           487: for
        !           488: .Vt uint64_t .
        !           489: .Pp
        !           490: Provides
        !           491: .Vt enum argmode ,
        !           492: .Vt struct manpage ,
        !           493: .Vt struct mansearch ,
        !           494: and the functions
        !           495: .Fn mansearch_setup ,
        !           496: .Fn mansearch ,
        !           497: and
        !           498: .Fn mansearch_free .
        !           499: .Pp
        !           500: Uses
        !           501: .Vt struct manpaths
        !           502: from
        !           503: .Pa manpath.h
        !           504: as an opaque type for function prototypes.
        !           505: .Pp
        !           506: When this header is included, the same file should not include
        !           507: .Pa out.h ,
        !           508: .Pa term.h ,
        !           509: or
        !           510: .Pa html.h .
        !           511: .El

CVSweb