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