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