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