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