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