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