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