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