Annotation of mandoc/mandoc_headers.3, Revision 1.16
1.16 ! schwarze 1: .Dd $Mdocdate$
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
28: .Xr mdoc 7
29: parser
30: .It
31: .Xr man 7
32: parser
33: .It
34: .Xr roff 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
48: .El
49: .Pp
1.2 schwarze 50: Note that mere usage of an opaque struct type does
1.1 schwarze 51: .Em not
52: require inclusion of the header where that type is defined.
53: .Ss Parser interface
54: Each of the following headers can be included without including
55: any other mandoc header.
56: These headers should be included before any other mandoc headers.
57: .Bl -tag -width Ds
58: .It Qq Pa mandoc_aux.h
59: Requires
60: .In sys/types.h
61: for
62: .Vt size_t .
1.11 schwarze 63: .Pp
1.1 schwarze 64: Provides the utility functions documented in
65: .Xr mandoc_malloc 3 .
1.8 schwarze 66: .It Qq Pa mandoc_ohash.h
1.11 schwarze 67: Requires
68: .In stddef.h
69: for
70: .Vt ptrdiff_t
71: and
72: .In stdint.h
73: for
74: .Vt uint32_t .
75: .Pp
1.8 schwarze 76: Includes
77: .In ohash.h
78: and provides
79: .Fn mandoc_ohash_init .
1.1 schwarze 80: .It Qq Pa mandoc.h
81: Requires
82: .In sys/types.h
83: for
84: .Vt size_t .
85: .Pp
86: Provides
87: .Vt enum mandoc_esc ,
88: .Vt enum mandocerr ,
89: .Vt enum mandoclevel ,
1.14 schwarze 90: .Vt enum mandoc_os ,
1.1 schwarze 91: .Vt enum tbl_cellt ,
92: .Vt enum tbl_datt ,
93: .Vt enum tbl_spant ,
94: .Vt enum eqn_boxt ,
95: .Vt enum eqn_fontt ,
96: .Vt enum eqn_pilet ,
97: .Vt enum eqn_post ,
98: .Vt struct tbl_opts ,
99: .Vt struct tbl_cell ,
100: .Vt struct tbl_row ,
101: .Vt struct tbl_dat ,
102: .Vt struct tbl_span ,
103: .Vt struct eqn_box ,
104: .Vt struct eqn ,
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.15 schwarze 126: .It Qq Pa mandoc_xr.h
127: Provides
128: .Vt struct mandoc_xr
129: and the functions
130: .Fn mandoc_xr_reset ,
131: .Fn mandoc_xr_add ,
132: .Fn mandoc_xr_get ,
133: and
134: .Fn mandoc_xr_free .
1.4 schwarze 135: .It Qq Pa roff.h
1.11 schwarze 136: Requires
137: .Qq Pa mandoc_ohash.h
138: for
1.14 schwarze 139: .Vt struct ohash
140: and
141: .Qq Pa mandoc.h
142: for
143: .Vt enum mandoc_os .
1.11 schwarze 144: .Pp
1.4 schwarze 145: Provides
1.5 schwarze 146: .Vt enum mdoc_endbody ,
1.8 schwarze 147: .Vt enum roff_macroset ,
148: .Vt enum roff_next ,
1.5 schwarze 149: .Vt enum roff_sec ,
1.10 schwarze 150: .Vt enum roff_tok ,
1.5 schwarze 151: .Vt enum roff_type ,
1.8 schwarze 152: .Vt struct roff_man ,
1.6 schwarze 153: .Vt struct roff_meta ,
1.8 schwarze 154: .Vt struct roff_node ,
1.10 schwarze 155: the constant array
156: .Va roff_name
1.11 schwarze 157: and the functions
158: .Fn deroff ,
159: .Fn roffhash_alloc ,
160: .Fn roffhash_find ,
1.13 schwarze 161: .Fn roffhash_free ,
1.11 schwarze 162: and
1.13 schwarze 163: .Fn roff_validate .
1.5 schwarze 164: .Pp
165: Uses pointers to the types
166: .Vt struct mdoc_arg
167: and
168: .Vt union mdoc_data
169: from
1.8 schwarze 170: .Pa mdoc.h
1.5 schwarze 171: as opaque struct members.
1.4 schwarze 172: .El
173: .Pp
174: The following two require
175: .Qq Pa roff.h
176: but no other mandoc headers.
177: Afterwards, any other mandoc headers can be included as needed.
178: .Bl -tag -width Ds
1.1 schwarze 179: .It Qq Pa mdoc.h
180: Requires
181: .In sys/types.h
182: for
1.8 schwarze 183: .Vt size_t .
1.1 schwarze 184: .Pp
185: Provides
186: .Vt enum mdocargt ,
1.8 schwarze 187: .Vt enum mdoc_auth ,
1.1 schwarze 188: .Vt enum mdoc_disp ,
1.8 schwarze 189: .Vt enum mdoc_font ,
1.1 schwarze 190: .Vt enum mdoc_list ,
191: .Vt struct mdoc_argv ,
192: .Vt struct mdoc_arg ,
1.8 schwarze 193: .Vt struct mdoc_an ,
1.1 schwarze 194: .Vt struct mdoc_bd ,
1.8 schwarze 195: .Vt struct mdoc_bf ,
1.1 schwarze 196: .Vt struct mdoc_bl ,
197: .Vt struct mdoc_rs ,
1.8 schwarze 198: .Vt union mdoc_data ,
1.1 schwarze 199: and the functions
200: .Fn mdoc_*
201: described in
202: .Xr mandoc 3 .
203: .Pp
204: Uses the type
1.8 schwarze 205: .Vt struct roff_man
1.1 schwarze 206: from
1.8 schwarze 207: .Pa roff.h
1.1 schwarze 208: as an opaque type for function prototypes.
209: .Pp
210: When this header is included, the same file should not include
211: .Pa libman.h
212: or
213: .Pa libroff.h .
214: .It Qq Pa man.h
1.6 schwarze 215: Provides the functions
1.1 schwarze 216: .Fn man_*
217: described in
218: .Xr mandoc 3 .
219: .Pp
220: Uses the opaque type
221: .Vt struct mparse
222: from
223: .Pa read.c
224: for function prototypes.
225: Uses the type
1.8 schwarze 226: .Vt struct roff_man
1.1 schwarze 227: from
1.8 schwarze 228: .Pa roff.h
1.1 schwarze 229: as an opaque type for function prototypes.
230: .Pp
231: When this header is included, the same file should not include
232: .Pa libmdoc.h
233: or
234: .Pa libroff.h .
235: .El
236: .Ss Parser internals
237: The following headers require inclusion of a parser interface header
1.9 schwarze 238: before they can be included.
239: All parser interface headers should precede all parser internal headers.
240: When any parser internal headers are included, the same file should
241: not include any formatter headers.
1.1 schwarze 242: .Bl -tag -width Ds
243: .It Qq Pa libmandoc.h
244: Requires
245: .In sys/types.h
246: for
1.8 schwarze 247: .Vt size_t
248: and
1.6 schwarze 249: .Qq Pa mandoc.h
250: for
1.8 schwarze 251: .Vt enum mandocerr .
1.1 schwarze 252: .Pp
253: Provides
254: .Vt enum rofferr ,
255: .Vt struct buf ,
256: utility functions needed by multiple parsers,
257: and the top-level functions to call the parsers.
258: .Pp
259: Uses the opaque types
260: .Vt struct mparse
261: from
262: .Pa read.c
263: and
264: .Vt struct roff
265: from
266: .Pa roff.c
267: for function prototypes.
268: Uses the types
1.2 schwarze 269: .Vt struct tbl_span
1.1 schwarze 270: and
271: .Vt struct eqn
272: from
1.8 schwarze 273: .Pa mandoc.h
274: and
275: .Vt struct roff_man
276: from
277: .Pa roff.h
278: as opaque types for function prototypes.
279: .It Qq Pa roff_int.h
280: Requires
281: .Qq Pa roff.h
282: for
283: .Vt enum roff_type .
284: .Pp
285: Provides functions named
286: .Fn roff_*
287: to handle roff nodes and the two special functions
288: .Fn man_breakscope
289: and
290: .Fn mdoc_argv_free
291: because the latter two are needed by
292: .Qq Pa roff.c .
293: .Pp
294: Uses the types
295: .Vt struct eqn
296: and
297: .Vt struct tbl_span
298: from
1.1 schwarze 299: .Pa mandoc.h ,
1.8 schwarze 300: .Vt struct roff_man
301: and
302: .Vt struct roff_node
1.1 schwarze 303: from
1.8 schwarze 304: .Pa roff.h ,
1.1 schwarze 305: and
1.8 schwarze 306: .Vt struct mdoc_arg
1.1 schwarze 307: from
1.8 schwarze 308: .Pa mdoc.h
1.1 schwarze 309: as opaque types for function prototypes.
310: .It Qq Pa libmdoc.h
311: Requires
1.10 schwarze 312: .Qq Pa roff.h
313: for
314: .Vt enum roff_tok
315: and
1.1 schwarze 316: .Qq Pa mdoc.h
317: for
1.5 schwarze 318: .Vt enum mdoc_*
1.1 schwarze 319: and
320: .Vt struct mdoc_* .
321: .Pp
322: Provides
323: .Vt enum margserr ,
324: .Vt enum mdelim ,
325: .Vt struct mdoc_macro ,
326: and many functions internal to the
327: .Xr mdoc 7
328: parser.
329: .Pp
1.8 schwarze 330: Uses the opaque type
1.1 schwarze 331: .Vt struct mparse
332: from
1.8 schwarze 333: .Pa read.c .
334: Uses the types
335: .Vt struct roff_man
1.1 schwarze 336: and
1.8 schwarze 337: .Vt struct roff_node
1.1 schwarze 338: from
1.8 schwarze 339: .Pa roff.h
340: as opaque types for function prototypes.
1.1 schwarze 341: .Pp
342: When this header is included, the same file should not include
343: .Pa man.h ,
344: .Pa libman.h ,
345: or
346: .Pa libroff.h .
347: .It Qq Pa libman.h
1.10 schwarze 348: Requires
349: .Qq Pa roff.h
350: for
351: .Vt enum roff_tok .
1.11 schwarze 352: .Pp
1.1 schwarze 353: Provides
1.8 schwarze 354: .Vt struct man_macro
355: and some functions internal to the
1.1 schwarze 356: .Xr man 7
357: parser.
358: .Pp
1.8 schwarze 359: Uses the types
360: .Vt struct roff_man
1.1 schwarze 361: and
1.8 schwarze 362: .Vt struct roff_node
1.1 schwarze 363: from
1.8 schwarze 364: .Pa roff.h
365: as opaque types for function prototypes.
1.1 schwarze 366: .Pp
367: When this header is included, the same file should not include
368: .Pa mdoc.h ,
369: .Pa libmdoc.h ,
370: or
371: .Pa libroff.h .
372: .It Qq Pa libroff.h
373: Requires
374: .In sys/types.h
375: for
376: .Vt size_t ,
377: .Qq Pa mandoc.h
378: for
379: .Vt struct tbl_*
380: and
381: .Vt struct eqn ,
382: and
383: .Qq Pa libmandoc.h
384: for
385: .Vt enum rofferr .
386: .Pp
387: Provides
388: .Vt enum tbl_part ,
389: .Vt struct tbl_node ,
390: .Vt struct eqn_def ,
391: .Vt struct eqn_node ,
392: and many functions internal to the
393: .Xr tbl 7
394: and
395: .Xr eqn 7
396: parsers.
397: .Pp
398: Uses the opaque type
399: .Vt struct mparse
400: from
401: .Pa read.c .
402: .Pp
403: When this header is included, the same file should not include
404: .Pa man.h ,
405: .Pa mdoc.h ,
406: .Pa libman.h ,
407: or
408: .Pa libmdoc.h .
409: .El
410: .Ss Formatter interface
411: These headers should be included after any parser interface headers.
412: No parser internal headers should be included by the same file.
413: .Bl -tag -width Ds
414: .It Qq Pa out.h
415: Requires
416: .In sys/types.h
417: for
418: .Vt size_t .
419: .Pp
420: Provides
421: .Vt enum roffscale ,
422: .Vt struct roffcol ,
423: .Vt struct roffsu ,
424: .Vt struct rofftbl ,
425: .Fn a2roffsu ,
426: and
427: .Fn tblcalc .
428: .Pp
429: Uses
430: .Vt struct tbl_span
431: from
432: .Pa mandoc.h
433: as an opaque type for function prototypes.
434: .Pp
435: When this header is included, the same file should not include
436: .Pa mansearch.h .
437: .It Qq Pa term.h
438: Requires
439: .In sys/types.h
440: for
441: .Vt size_t
442: and
443: .Qq Pa out.h
444: for
445: .Vt struct roffsu
446: and
447: .Vt struct rofftbl .
448: .Pp
449: Provides
450: .Vt enum termenc ,
451: .Vt enum termfont ,
452: .Vt enum termtype ,
453: .Vt struct termp_tbl ,
454: .Vt struct termp ,
1.12 schwarze 455: .Fn roff_term_pre ,
1.1 schwarze 456: and many terminal formatting functions.
457: .Pp
1.7 schwarze 458: Uses the opaque type
1.1 schwarze 459: .Vt struct termp_ps
460: from
461: .Pa term_ps.c .
462: Uses
463: .Vt struct tbl_span
464: and
465: .Vt struct eqn
466: from
467: .Pa mandoc.h
1.6 schwarze 468: and
469: .Vt struct roff_meta
1.12 schwarze 470: and
471: .Vt struct roff_node
1.6 schwarze 472: from
1.8 schwarze 473: .Pa roff.h
1.1 schwarze 474: as opaque types for function prototypes.
475: .Pp
476: When this header is included, the same file should not include
1.3 schwarze 477: .Pa html.h
1.1 schwarze 478: or
479: .Pa mansearch.h .
480: .It Qq Pa html.h
481: Requires
482: .In sys/types.h
483: for
1.11 schwarze 484: .Vt size_t
1.1 schwarze 485: and
486: .Qq Pa out.h
487: for
488: .Vt struct roffsu
489: and
490: .Vt struct rofftbl .
491: .Pp
492: Provides
493: .Vt enum htmltag ,
494: .Vt enum htmlattr ,
495: .Vt enum htmlfont ,
496: .Vt struct tag ,
497: .Vt struct tagq ,
498: .Vt struct htmlpair ,
499: .Vt struct html ,
1.12 schwarze 500: .Fn roff_html_pre ,
1.1 schwarze 501: and many HTML formatting functions.
1.12 schwarze 502: .Pp
503: Uses
504: .Vt struct tbl_span
505: and
506: .Vt struct eqn
507: from
508: .Pa mandoc.h
509: and
510: .Vt struct roff_node
511: from
512: .Pa roff.h
513: as opaque types for function prototypes.
1.1 schwarze 514: .Pp
515: When this header is included, the same file should not include
1.3 schwarze 516: .Pa term.h
1.1 schwarze 517: or
518: .Pa mansearch.h .
1.8 schwarze 519: .It Qq Pa tag.h
520: Requires
521: .In sys/types.h
522: for
523: .Vt size_t .
524: .Pp
525: Provides an interface to generate
526: .Xr ctags 1
527: files for the
528: .Ic :t
529: functionality mentioned in
530: .Xr man 1 .
1.1 schwarze 531: .It Qq Pa main.h
532: Provides the top level steering functions for all formatters.
533: .Pp
1.8 schwarze 534: Uses the type
535: .Vt struct roff_man
1.1 schwarze 536: from
1.8 schwarze 537: .Pa roff.h
538: as an opaque type for function prototypes.
1.3 schwarze 539: .It Qq Pa manconf.h
1.1 schwarze 540: Requires
541: .In sys/types.h
542: for
543: .Vt size_t .
544: .Pp
545: Provides
1.3 schwarze 546: .Vt struct manconf ,
547: .Vt struct manpaths ,
548: .Vt struct manoutput ,
1.1 schwarze 549: and the functions
1.3 schwarze 550: .Fn manconf_parse ,
551: .Fn manconf_output ,
1.15 schwarze 552: .Fn manconf_free ,
1.1 schwarze 553: and
1.15 schwarze 554: .Fn manpath_base .
1.1 schwarze 555: .It Qq Pa mansearch.h
556: Requires
557: .In sys/types.h
558: for
559: .Vt size_t
560: and
561: .In stdint.h
562: for
563: .Vt uint64_t .
564: .Pp
565: Provides
566: .Vt enum argmode ,
567: .Vt struct manpage ,
568: .Vt struct mansearch ,
569: and the functions
1.9 schwarze 570: .Fn mansearch
1.1 schwarze 571: and
572: .Fn mansearch_free .
573: .Pp
574: Uses
575: .Vt struct manpaths
576: from
1.3 schwarze 577: .Pa manconf.h
1.1 schwarze 578: as an opaque type for function prototypes.
579: .Pp
580: When this header is included, the same file should not include
581: .Pa out.h ,
582: .Pa term.h ,
583: or
584: .Pa html.h .
585: .El
CVSweb