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