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