Annotation of mandoc/mandoc_headers.3, Revision 1.2
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 manpath.h
370: or
371: .Pa mansearch.h .
372: .It Qq Pa term.h
373: Requires
374: .In sys/types.h
375: for
376: .Vt size_t
377: and
378: .Qq Pa out.h
379: for
380: .Vt struct roffsu
381: and
382: .Vt struct rofftbl .
383: .Pp
384: Provides
385: .Vt enum termenc ,
386: .Vt enum termfont ,
387: .Vt enum termtype ,
388: .Vt struct termp_tbl ,
389: .Vt struct termp ,
390: and many terminal formatting functions.
391: .Pp
392: Uses the opaque types
393: .Vt struct mchars
394: from
395: .Pa chars.c
396: and
397: .Vt struct termp_ps
398: from
399: .Pa term_ps.c .
400: Uses
401: .Vt struct tbl_span
402: and
403: .Vt struct eqn
404: from
405: .Pa mandoc.h
406: as opaque types for function prototypes.
407: .Pp
408: When this header is included, the same file should not include
409: .Pa html.h ,
410: .Pa manpath.h
411: or
412: .Pa mansearch.h .
413: .It Qq Pa html.h
414: Requires
415: .In sys/types.h
416: for
417: .Vt size_t ,
418: .In stdio.h
419: for
420: .Dv BUFSIZ ,
421: and
422: .Qq Pa out.h
423: for
424: .Vt struct roffsu
425: and
426: .Vt struct rofftbl .
427: .Pp
428: Provides
429: .Vt enum htmltag ,
430: .Vt enum htmlattr ,
431: .Vt enum htmlfont ,
432: .Vt struct tag ,
433: .Vt struct tagq ,
434: .Vt struct htmlpair ,
435: .Vt struct html ,
436: and many HTML formatting functions.
437: .Pp
438: Uses the opaque type
439: .Vt struct mchars
440: from
441: .Pa chars.c .
442: .Pp
443: When this header is included, the same file should not include
444: .Pa term.h ,
445: .Pa manpath.h
446: or
447: .Pa mansearch.h .
448: .It Qq Pa main.h
449: Provides the top level steering functions for all formatters.
450: .Pp
451: Uses the opaque type
452: .Vt struct mchars
453: from
454: .Pa chars.c .
455: Uses the types
456: .Vt struct mdoc
457: from
458: .Pa libmdoc.h
459: and
460: .Vt struct man
461: from
462: .Pa libman.h
463: as opaque types for function prototypes.
464: .It Qq Pa manpath.h
465: Requires
466: .In sys/types.h
467: for
468: .Vt size_t .
469: .Pp
470: Provides
471: .Vt struct manpaths
472: and the functions
473: .Fn manpath_manconf ,
474: .Fn manpath_parse ,
475: and
476: .Fn manpath_free .
477: .Pp
478: When this header is included, the same file should not include
479: .Pa out.h ,
480: .Pa term.h ,
481: or
482: .Pa html.h .
483: .It Qq Pa mansearch.h
484: Requires
485: .In sys/types.h
486: for
487: .Vt size_t
488: and
489: .In stdint.h
490: for
491: .Vt uint64_t .
492: .Pp
493: Provides
494: .Vt enum argmode ,
495: .Vt struct manpage ,
496: .Vt struct mansearch ,
497: and the functions
498: .Fn mansearch_setup ,
499: .Fn mansearch ,
500: and
501: .Fn mansearch_free .
502: .Pp
503: Uses
504: .Vt struct manpaths
505: from
506: .Pa manpath.h
507: as an opaque type for function prototypes.
508: .Pp
509: When this header is included, the same file should not include
510: .Pa out.h ,
511: .Pa term.h ,
512: or
513: .Pa html.h .
514: .El
CVSweb