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