Annotation of mandoc/mandoc_headers.3, Revision 1.19
1.18 schwarze 1: .Dd $Mdocdate: July 8 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 struct buf ,
254: utility functions needed by multiple parsers,
255: and the top-level functions to call the parsers.
256: .Pp
257: Uses the opaque types
258: .Vt struct mparse
259: from
260: .Pa read.c
261: and
262: .Vt struct roff
263: from
264: .Pa roff.c
265: for function prototypes.
1.18 schwarze 266: Uses the type
1.8 schwarze 267: .Vt struct roff_man
268: from
269: .Pa roff.h
1.18 schwarze 270: as an opaque type for function prototypes.
1.8 schwarze 271: .It Qq Pa roff_int.h
272: Requires
273: .Qq Pa roff.h
274: for
275: .Vt enum roff_type .
276: .Pp
277: Provides functions named
278: .Fn roff_*
279: to handle roff nodes and the two special functions
280: .Fn man_breakscope
281: and
282: .Fn mdoc_argv_free
283: because the latter two are needed by
284: .Qq Pa roff.c .
285: .Pp
286: Uses the types
287: .Vt struct roff_man
288: and
289: .Vt struct roff_node
1.1 schwarze 290: from
1.18 schwarze 291: .Pa roff.h
1.1 schwarze 292: and
1.8 schwarze 293: .Vt struct mdoc_arg
1.1 schwarze 294: from
1.8 schwarze 295: .Pa mdoc.h
1.1 schwarze 296: as opaque types for function prototypes.
297: .It Qq Pa libmdoc.h
298: Requires
1.10 schwarze 299: .Qq Pa roff.h
300: for
301: .Vt enum roff_tok
302: and
1.1 schwarze 303: .Qq Pa mdoc.h
304: for
1.5 schwarze 305: .Vt enum mdoc_*
1.1 schwarze 306: and
307: .Vt struct mdoc_* .
308: .Pp
309: Provides
310: .Vt enum margserr ,
311: .Vt enum mdelim ,
312: .Vt struct mdoc_macro ,
313: and many functions internal to the
314: .Xr mdoc 7
315: parser.
316: .Pp
1.8 schwarze 317: Uses the opaque type
1.1 schwarze 318: .Vt struct mparse
319: from
1.8 schwarze 320: .Pa read.c .
321: Uses the types
322: .Vt struct roff_man
1.1 schwarze 323: and
1.8 schwarze 324: .Vt struct roff_node
1.1 schwarze 325: from
1.8 schwarze 326: .Pa roff.h
327: as opaque types for function prototypes.
1.1 schwarze 328: .Pp
329: When this header is included, the same file should not include
330: .Pa man.h ,
331: .Pa libman.h ,
332: or
333: .Pa libroff.h .
334: .It Qq Pa libman.h
1.10 schwarze 335: Requires
336: .Qq Pa roff.h
337: for
338: .Vt enum roff_tok .
1.11 schwarze 339: .Pp
1.1 schwarze 340: Provides
1.8 schwarze 341: .Vt struct man_macro
342: and some functions internal to the
1.1 schwarze 343: .Xr man 7
344: parser.
345: .Pp
1.8 schwarze 346: Uses the types
347: .Vt struct roff_man
1.1 schwarze 348: and
1.8 schwarze 349: .Vt struct roff_node
1.1 schwarze 350: from
1.8 schwarze 351: .Pa roff.h
352: as opaque types for function prototypes.
1.1 schwarze 353: .Pp
354: When this header is included, the same file should not include
355: .Pa mdoc.h ,
356: .Pa libmdoc.h ,
357: or
358: .Pa libroff.h .
359: .It Qq Pa libroff.h
360: Requires
361: .In sys/types.h
362: for
1.18 schwarze 363: .Vt size_t
364: and
1.1 schwarze 365: .Qq Pa mandoc.h
366: for
367: .Vt struct tbl_*
368: and
1.18 schwarze 369: .Vt struct eqn_box .
1.1 schwarze 370: .Pp
371: Provides
372: .Vt enum tbl_part ,
373: .Vt struct tbl_node ,
374: .Vt struct eqn_def ,
375: .Vt struct eqn_node ,
376: and many functions internal to the
377: .Xr tbl 7
378: and
379: .Xr eqn 7
380: parsers.
381: .Pp
382: Uses the opaque type
383: .Vt struct mparse
384: from
385: .Pa read.c .
386: .Pp
387: When this header is included, the same file should not include
388: .Pa man.h ,
389: .Pa mdoc.h ,
390: .Pa libman.h ,
391: or
392: .Pa libmdoc.h .
393: .El
394: .Ss Formatter interface
395: These headers should be included after any parser interface headers.
396: No parser internal headers should be included by the same file.
397: .Bl -tag -width Ds
398: .It Qq Pa out.h
399: Requires
400: .In sys/types.h
401: for
402: .Vt size_t .
403: .Pp
404: Provides
405: .Vt enum roffscale ,
406: .Vt struct roffcol ,
407: .Vt struct roffsu ,
408: .Vt struct rofftbl ,
409: .Fn a2roffsu ,
410: and
411: .Fn tblcalc .
412: .Pp
413: Uses
414: .Vt struct tbl_span
415: from
416: .Pa mandoc.h
417: as an opaque type for function prototypes.
418: .Pp
419: When this header is included, the same file should not include
420: .Pa mansearch.h .
421: .It Qq Pa term.h
422: Requires
423: .In sys/types.h
424: for
425: .Vt size_t
426: and
427: .Qq Pa out.h
428: for
429: .Vt struct roffsu
430: and
431: .Vt struct rofftbl .
432: .Pp
433: Provides
434: .Vt enum termenc ,
435: .Vt enum termfont ,
436: .Vt enum termtype ,
437: .Vt struct termp_tbl ,
438: .Vt struct termp ,
1.12 schwarze 439: .Fn roff_term_pre ,
1.1 schwarze 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
1.17 schwarze 449: .Vt struct eqn_box
1.1 schwarze 450: from
451: .Pa mandoc.h
1.6 schwarze 452: and
453: .Vt struct roff_meta
1.12 schwarze 454: and
455: .Vt struct roff_node
1.6 schwarze 456: from
1.8 schwarze 457: .Pa roff.h
1.1 schwarze 458: as opaque types for function prototypes.
459: .Pp
460: When this header is included, the same file should not include
1.3 schwarze 461: .Pa html.h
1.1 schwarze 462: or
463: .Pa mansearch.h .
464: .It Qq Pa html.h
465: Requires
466: .In sys/types.h
467: for
1.11 schwarze 468: .Vt size_t
1.1 schwarze 469: and
470: .Qq Pa out.h
471: for
472: .Vt struct roffsu
473: and
474: .Vt struct rofftbl .
475: .Pp
476: Provides
477: .Vt enum htmltag ,
478: .Vt enum htmlattr ,
479: .Vt enum htmlfont ,
480: .Vt struct tag ,
481: .Vt struct tagq ,
482: .Vt struct htmlpair ,
483: .Vt struct html ,
1.12 schwarze 484: .Fn roff_html_pre ,
1.1 schwarze 485: and many HTML formatting functions.
1.12 schwarze 486: .Pp
487: Uses
488: .Vt struct tbl_span
489: and
1.17 schwarze 490: .Vt struct eqn_box
1.12 schwarze 491: from
492: .Pa mandoc.h
493: and
494: .Vt struct roff_node
495: from
496: .Pa roff.h
497: as opaque types for function prototypes.
1.1 schwarze 498: .Pp
499: When this header is included, the same file should not include
1.3 schwarze 500: .Pa term.h
1.1 schwarze 501: or
502: .Pa mansearch.h .
1.8 schwarze 503: .It Qq Pa tag.h
504: Requires
505: .In sys/types.h
506: for
507: .Vt size_t .
508: .Pp
509: Provides an interface to generate
510: .Xr ctags 1
511: files for the
512: .Ic :t
513: functionality mentioned in
514: .Xr man 1 .
1.1 schwarze 515: .It Qq Pa main.h
516: Provides the top level steering functions for all formatters.
517: .Pp
1.8 schwarze 518: Uses the type
519: .Vt struct roff_man
1.1 schwarze 520: from
1.8 schwarze 521: .Pa roff.h
522: as an opaque type for function prototypes.
1.3 schwarze 523: .It Qq Pa manconf.h
1.1 schwarze 524: Requires
525: .In sys/types.h
526: for
527: .Vt size_t .
528: .Pp
529: Provides
1.3 schwarze 530: .Vt struct manconf ,
531: .Vt struct manpaths ,
532: .Vt struct manoutput ,
1.1 schwarze 533: and the functions
1.3 schwarze 534: .Fn manconf_parse ,
535: .Fn manconf_output ,
1.15 schwarze 536: .Fn manconf_free ,
1.1 schwarze 537: and
1.15 schwarze 538: .Fn manpath_base .
1.1 schwarze 539: .It Qq Pa mansearch.h
540: Requires
541: .In sys/types.h
542: for
543: .Vt size_t
544: and
545: .In stdint.h
546: for
547: .Vt uint64_t .
548: .Pp
549: Provides
550: .Vt enum argmode ,
551: .Vt struct manpage ,
552: .Vt struct mansearch ,
553: and the functions
1.9 schwarze 554: .Fn mansearch
1.1 schwarze 555: and
556: .Fn mansearch_free .
557: .Pp
558: Uses
559: .Vt struct manpaths
560: from
1.3 schwarze 561: .Pa manconf.h
1.1 schwarze 562: as an opaque type for function prototypes.
563: .Pp
564: When this header is included, the same file should not include
565: .Pa out.h ,
566: .Pa term.h ,
567: or
568: .Pa html.h .
569: .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