Annotation of mandoc/mandoc_headers.3, Revision 1.25
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
1.14 schwarze 174: .Qq Pa mandoc.h
175: for
176: .Vt enum mandoc_os .
1.11 schwarze 177: .Pp
1.4 schwarze 178: Provides
1.5 schwarze 179: .Vt enum mdoc_endbody ,
1.8 schwarze 180: .Vt enum roff_macroset ,
181: .Vt enum roff_next ,
1.5 schwarze 182: .Vt enum roff_sec ,
1.10 schwarze 183: .Vt enum roff_tok ,
1.5 schwarze 184: .Vt enum roff_type ,
1.8 schwarze 185: .Vt struct roff_man ,
1.6 schwarze 186: .Vt struct roff_meta ,
1.8 schwarze 187: .Vt struct roff_node ,
1.10 schwarze 188: the constant array
189: .Va roff_name
1.11 schwarze 190: and the functions
1.24 schwarze 191: .Fn deroff
1.11 schwarze 192: and
1.13 schwarze 193: .Fn roff_validate .
1.5 schwarze 194: .Pp
195: Uses pointers to the types
1.25 ! schwarze 196: .Vt struct ohash
! 197: from
! 198: .Pa mandoc_ohash.h
! 199: and
1.5 schwarze 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.25 ! schwarze 344: .Vt enum roff_sec .
1.1 schwarze 345: .Pp
346: Provides
347: .Vt enum margserr ,
348: .Vt enum mdelim ,
349: .Vt struct mdoc_macro ,
350: and many functions internal to the
351: .Xr mdoc 7
352: parser.
353: .Pp
1.8 schwarze 354: Uses the types
355: .Vt struct roff_man
1.1 schwarze 356: and
1.8 schwarze 357: .Vt struct roff_node
1.1 schwarze 358: from
1.8 schwarze 359: .Pa roff.h
1.25 ! schwarze 360: and
! 361: .Vt struct mdoc_arg
! 362: from
! 363: .Pa mdoc.h
1.8 schwarze 364: as opaque types for function prototypes.
1.1 schwarze 365: .Pp
366: When this header is included, the same file should not include
1.22 schwarze 367: interfaces of different parsers.
1.1 schwarze 368: .It Qq Pa libman.h
1.10 schwarze 369: Requires
370: .Qq Pa roff.h
371: for
372: .Vt enum roff_tok .
1.11 schwarze 373: .Pp
1.1 schwarze 374: Provides
1.8 schwarze 375: .Vt struct man_macro
376: and some functions internal to the
1.1 schwarze 377: .Xr man 7
378: parser.
379: .Pp
1.8 schwarze 380: Uses the types
381: .Vt struct roff_man
1.1 schwarze 382: and
1.8 schwarze 383: .Vt struct roff_node
1.1 schwarze 384: from
1.8 schwarze 385: .Pa roff.h
386: as opaque types for function prototypes.
1.1 schwarze 387: .Pp
388: When this header is included, the same file should not include
1.22 schwarze 389: interfaces of different parsers.
390: .It Qq Pa eqn_parse.h
391: External interface of the
392: .Xr eqn 7
393: parser, for use in the
394: .Xr roff 7
395: and
396: .Xr eqn 7
397: parsers only.
398: .Pp
1.1 schwarze 399: Requires
400: .In sys/types.h
401: for
1.22 schwarze 402: .Vt size_t .
1.1 schwarze 403: .Pp
404: Provides
1.22 schwarze 405: .Vt struct eqn_node
406: and the functions
407: .Fn eqn_alloc ,
1.23 schwarze 408: .Fn eqn_box_new ,
1.22 schwarze 409: .Fn eqn_box_free ,
410: .Fn eqn_free ,
411: .Fn eqn_parse ,
412: .Fn eqn_read ,
413: and
414: .Fn eqn_reset .
1.1 schwarze 415: .Pp
416: Uses the opaque type
417: .Vt struct mparse
418: from
1.22 schwarze 419: .Pa read.c
420: for function prototypes.
421: Uses the type
422: .Vt struct eqn_box
423: from
424: .Pa mandoc.h
425: as an opaque type for function prototypes.
426: Uses the types
427: .Vt struct roff_node
428: from
429: .Pa roff.h
430: and
431: .Vt struct eqn_def
432: from
433: .Pa eqn.c
434: as opaque struct members.
1.1 schwarze 435: .Pp
436: When this header is included, the same file should not include
1.22 schwarze 437: internals of different parsers.
1.21 schwarze 438: .It Qq Pa tbl_parse.h
439: External interface of the
440: .Xr tbl 7
441: parser, for use in the
442: .Xr roff 7
443: and
444: .Xr tbl 7
445: parsers only.
446: .Pp
447: Provides the functions documented in
448: .Xr tbl 3 .
449: .Pp
450: Uses the opaque type
451: .Vt struct mparse
452: from
453: .Pa read.c .
454: Uses the types
455: .Vt struct tbl_span
456: from
457: .Pa tbl.h
458: and
459: .Vt struct tbl_node
460: from
461: .Pa tbl_int.h
462: as opaque types for function prototypes.
463: .Pp
464: When this header is included, the same file should not include
1.22 schwarze 465: internals of different parsers.
1.21 schwarze 466: .It Qq Pa tbl_int.h
467: Internal interfaces of the
468: .Xr tbl 7
469: parser, for use inside the
470: .Xr tbl 7
471: parser only.
472: .Pp
473: Requires
474: .Qq Pa tbl.h
475: for
476: .Vt struct tbl_opts .
477: .Pp
478: Provides
479: .Vt enum tbl_part ,
480: .Vt struct tbl_node ,
481: and the functions
482: .Fn tbl_option ,
483: .Fn tbl_layout ,
484: .Fn tbl_data ,
485: .Fn tbl_cdata ,
486: and
487: .Fn tbl_reset .
488: .Pp
489: Uses a pointer to the opaque type
490: .Vt struct mparse
491: from
492: .Pa read.c
493: as an opaque struct member.
494: .Pp
495: When this header is included, the same file should not include
496: interfaces of different parsers.
1.1 schwarze 497: .El
498: .Ss Formatter interface
499: These headers should be included after any parser interface headers.
500: No parser internal headers should be included by the same file.
501: .Bl -tag -width Ds
502: .It Qq Pa out.h
503: Requires
504: .In sys/types.h
505: for
506: .Vt size_t .
507: .Pp
508: Provides
509: .Vt enum roffscale ,
510: .Vt struct roffcol ,
511: .Vt struct roffsu ,
512: .Vt struct rofftbl ,
513: .Fn a2roffsu ,
514: and
515: .Fn tblcalc .
516: .Pp
517: Uses
518: .Vt struct tbl_span
519: from
520: .Pa mandoc.h
521: as an opaque type for function prototypes.
522: .Pp
523: When this header is included, the same file should not include
524: .Pa mansearch.h .
525: .It Qq Pa term.h
526: Requires
527: .In sys/types.h
528: for
529: .Vt size_t
530: and
531: .Qq Pa out.h
532: for
533: .Vt struct roffsu
534: and
535: .Vt struct rofftbl .
536: .Pp
537: Provides
538: .Vt enum termenc ,
539: .Vt enum termfont ,
540: .Vt enum termtype ,
541: .Vt struct termp_tbl ,
542: .Vt struct termp ,
1.12 schwarze 543: .Fn roff_term_pre ,
1.1 schwarze 544: and many terminal formatting functions.
545: .Pp
1.7 schwarze 546: Uses the opaque type
1.1 schwarze 547: .Vt struct termp_ps
548: from
549: .Pa term_ps.c .
550: Uses
551: .Vt struct tbl_span
552: and
1.17 schwarze 553: .Vt struct eqn_box
1.1 schwarze 554: from
555: .Pa mandoc.h
1.6 schwarze 556: and
557: .Vt struct roff_meta
1.12 schwarze 558: and
559: .Vt struct roff_node
1.6 schwarze 560: from
1.8 schwarze 561: .Pa roff.h
1.1 schwarze 562: as opaque types for function prototypes.
563: .Pp
564: When this header is included, the same file should not include
1.3 schwarze 565: .Pa html.h
1.1 schwarze 566: or
567: .Pa mansearch.h .
568: .It Qq Pa html.h
569: Requires
570: .In sys/types.h
571: for
1.11 schwarze 572: .Vt size_t
1.1 schwarze 573: and
574: .Qq Pa out.h
575: for
576: .Vt struct roffsu
577: and
578: .Vt struct rofftbl .
579: .Pp
580: Provides
581: .Vt enum htmltag ,
582: .Vt enum htmlattr ,
583: .Vt enum htmlfont ,
584: .Vt struct tag ,
585: .Vt struct tagq ,
586: .Vt struct htmlpair ,
587: .Vt struct html ,
1.12 schwarze 588: .Fn roff_html_pre ,
1.1 schwarze 589: and many HTML formatting functions.
1.12 schwarze 590: .Pp
591: Uses
592: .Vt struct tbl_span
593: and
1.17 schwarze 594: .Vt struct eqn_box
1.12 schwarze 595: from
596: .Pa mandoc.h
597: and
598: .Vt struct roff_node
599: from
600: .Pa roff.h
601: as opaque types for function prototypes.
1.1 schwarze 602: .Pp
603: When this header is included, the same file should not include
1.3 schwarze 604: .Pa term.h
1.1 schwarze 605: or
606: .Pa mansearch.h .
1.8 schwarze 607: .It Qq Pa tag.h
608: Requires
609: .In sys/types.h
610: for
611: .Vt size_t .
612: .Pp
613: Provides an interface to generate
614: .Xr ctags 1
615: files for the
616: .Ic :t
617: functionality mentioned in
618: .Xr man 1 .
1.1 schwarze 619: .It Qq Pa main.h
620: Provides the top level steering functions for all formatters.
621: .Pp
1.8 schwarze 622: Uses the type
623: .Vt struct roff_man
1.1 schwarze 624: from
1.8 schwarze 625: .Pa roff.h
626: as an opaque type for function prototypes.
1.3 schwarze 627: .It Qq Pa manconf.h
1.1 schwarze 628: Requires
629: .In sys/types.h
630: for
631: .Vt size_t .
632: .Pp
633: Provides
1.3 schwarze 634: .Vt struct manconf ,
635: .Vt struct manpaths ,
636: .Vt struct manoutput ,
1.1 schwarze 637: and the functions
1.3 schwarze 638: .Fn manconf_parse ,
639: .Fn manconf_output ,
1.15 schwarze 640: .Fn manconf_free ,
1.1 schwarze 641: and
1.15 schwarze 642: .Fn manpath_base .
1.1 schwarze 643: .It Qq Pa mansearch.h
644: Requires
645: .In sys/types.h
646: for
647: .Vt size_t
648: and
649: .In stdint.h
650: for
651: .Vt uint64_t .
652: .Pp
653: Provides
654: .Vt enum argmode ,
655: .Vt struct manpage ,
656: .Vt struct mansearch ,
657: and the functions
1.9 schwarze 658: .Fn mansearch
1.1 schwarze 659: and
660: .Fn mansearch_free .
661: .Pp
662: Uses
663: .Vt struct manpaths
664: from
1.3 schwarze 665: .Pa manconf.h
1.1 schwarze 666: as an opaque type for function prototypes.
667: .Pp
668: When this header is included, the same file should not include
669: .Pa out.h ,
670: .Pa term.h ,
671: or
672: .Pa html.h .
673: .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