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