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