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