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