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