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