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