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