xref: /freebsd/contrib/mandoc/mandoc_headers.3 (revision fab66680b3df4792fb0d3d13b2c9cdd88538d3d2)
1.Dd $Mdocdate: December 30 2018 $
2.Dt MANDOC_HEADERS 3
3.Os
4.Sh NAME
5.Nm mandoc_headers
6.Nd ordering of mandoc include files
7.Sh DESCRIPTION
8To support a cleaner coding style, the mandoc header files do not
9contain any include directives and do not guard against multiple
10inclusion.
11The application developer has to make sure that the headers are
12included in a proper order, and that no header is included more
13than once.
14.Pp
15The headers and functions form three major groups:
16.Sx Parser interface ,
17.Sx Parser internals ,
18and
19.Sx Formatter interface .
20.Pp
21Various rules are given below prohibiting the inclusion of certain
22combinations of headers into the same file.
23The intention is to keep the following functional components
24separate from each other:
25.Pp
26.Bl -dash -offset indent -compact
27.It
28.Xr roff 7
29parser
30.It
31.Xr mdoc 7
32parser
33.It
34.Xr man 7
35parser
36.It
37.Xr tbl 7
38parser
39.It
40.Xr eqn 7
41parser
42.It
43terminal formatters
44.It
45HTML formatters
46.It
47search tools
48.It
49main programs
50.El
51.Pp
52Note that mere usage of an opaque struct type does
53.Em not
54require inclusion of the header where that type is defined.
55.Ss Parser interface
56Each of the following headers can be included without including
57any other mandoc header.
58These headers should be included before any other mandoc headers.
59.Bl -tag -width Ds
60.It Qq Pa mandoc_aux.h
61Memory allocation utility functions; can be used everywhere.
62.Pp
63Requires
64.In sys/types.h
65for
66.Vt size_t .
67.Pp
68Provides the functions documented in
69.Xr mandoc_malloc 3 .
70.It Qq Pa mandoc_ohash.h
71Hashing utility functions; can be used everywhere.
72.Pp
73Requires
74.In stddef.h
75for
76.Vt ptrdiff_t
77and
78.In stdint.h
79for
80.Vt uint32_t .
81.Pp
82Includes
83.In ohash.h
84and provides
85.Fn mandoc_ohash_init .
86.It Qq Pa mandoc.h
87Error handling, escape sequence, and character utilities;
88can be used everywhere.
89.Pp
90Requires
91.In sys/types.h
92for
93.Vt size_t
94and
95.In stdio.h
96for
97.Vt FILE .
98.Pp
99Provides
100.Vt enum mandoc_esc ,
101.Vt enum mandocerr ,
102.Vt enum mandoclevel ,
103the function
104.Xr mandoc_escape 3 ,
105the functions described in
106.Xr mchars_alloc 3 ,
107and the
108.Fn mandoc_msg*
109functions.
110.It Qq Pa roff.h
111Common data types for all syntax trees and related functions;
112can be used everywhere.
113.Pp
114Provides
115.Vt enum mandoc_os ,
116.Vt enum mdoc_endbody ,
117.Vt enum roff_macroset ,
118.Vt enum roff_sec ,
119.Vt enum roff_tok ,
120.Vt enum roff_type ,
121.Vt struct roff_man ,
122.Vt struct roff_meta ,
123.Vt struct roff_node ,
124the constant array
125.Va roff_name
126and the function
127.Fn deroff .
128.Pp
129Uses pointers to the types
130.Vt struct ohash
131from
132.Pa mandoc_ohash.h ,
133.Vt struct mdoc_arg
134and
135.Vt union mdoc_data
136from
137.Pa mdoc.h ,
138.Vt struct tbl_span
139from
140.Pa tbl.h ,
141and
142.Vt struct eqn_box
143from
144.Pa eqn.h
145as opaque struct members.
146.It Qq Pa tbl.h
147Data structures for the
148.Xr tbl 7
149parse tree; can be used everywhere.
150.Pp
151Requires
152.In sys/types.h
153for
154.Vt size_t .
155.Pp
156Provides
157.Vt enum tbl_cellt ,
158.Vt enum tbl_datt ,
159.Vt enum tbl_spant ,
160.Vt struct tbl_opts ,
161.Vt struct tbl_cell ,
162.Vt struct tbl_row ,
163.Vt struct tbl_dat ,
164and
165.Vt struct tbl_span .
166.It Qq Pa eqn.h
167Data structures for the
168.Xr eqn 7
169parse tree; can be used everywhere.
170.Pp
171Requires
172.In sys/types.h
173for
174.Vt size_t .
175.Pp
176Provides
177.Vt enum eqn_boxt ,
178.Vt enum eqn_fontt ,
179.Vt enum eqn_post ,
180and
181.Vt struct eqn_box .
182.It Qq Pa mandoc_parse.h
183Top level parser interface, for use in the main program
184and in the main parser, but not in formatters.
185.Pp
186Requires
187.Pa mandoc.h
188for
189.Vt enum mandocerr
190and
191.Vt enum mandoclevel
192and
193.Pa roff.h
194for
195.Vt enum mandoc_os .
196.Pp
197Uses the opaque type
198.Vt struct mparse
199from
200.Pa read.c
201for function prototypes.
202Uses
203.Vt struct roff_meta
204from
205.Pa roff.h
206as an opaque type for function prototypes.
207.It Qq Pa mandoc_xr.h
208Cross reference validation; intended for use in the main program
209and in parsers, but not in formatters.
210.Pp
211Provides
212.Vt struct mandoc_xr
213and the functions
214.Fn mandoc_xr_reset ,
215.Fn mandoc_xr_add ,
216.Fn mandoc_xr_get ,
217and
218.Fn mandoc_xr_free .
219.El
220.Pp
221The following two require
222.Qq Pa roff.h
223but no other mandoc headers.
224Afterwards, any other mandoc headers can be included as needed.
225.Bl -tag -width Ds
226.It Qq Pa mdoc.h
227Requires
228.In sys/types.h
229for
230.Vt size_t .
231.Pp
232Provides
233.Vt enum mdocargt ,
234.Vt enum mdoc_auth ,
235.Vt enum mdoc_disp ,
236.Vt enum mdoc_font ,
237.Vt enum mdoc_list ,
238.Vt struct mdoc_argv ,
239.Vt struct mdoc_arg ,
240.Vt struct mdoc_an ,
241.Vt struct mdoc_bd ,
242.Vt struct mdoc_bf ,
243.Vt struct mdoc_bl ,
244.Vt struct mdoc_rs ,
245.Vt union mdoc_data ,
246and the functions
247.Fn mdoc_*
248described in
249.Xr mandoc 3 .
250.Pp
251Uses the types
252.Vt struct roff_node
253from
254.Pa roff.h
255and
256.Vt struct roff_man
257from
258.Pa roff_int.h
259as opaque types for function prototypes.
260.Pp
261When this header is included, the same file should not include
262internals of different parsers.
263.It Qq Pa man.h
264Provides the functions
265.Fn man_*
266described in
267.Xr mandoc 3 .
268.Pp
269Uses the type
270.Vt struct roff_man
271from
272.Pa roff.h
273as an opaque type for function prototypes.
274.Pp
275When this header is included, the same file should not include
276internals of different parsers.
277.El
278.Ss Parser internals
279Most of the following headers require inclusion of a parser interface header
280before they can be included.
281All parser interface headers should precede all parser internal headers.
282When any parser internal headers are included, the same file should
283not include any formatter headers.
284.Bl -tag -width Ds
285.It Qq Pa libmandoc.h
286Requires
287.In sys/types.h
288for
289.Vt size_t
290and
291.Qq Pa mandoc.h
292for
293.Vt enum mandocerr .
294.Pp
295Provides
296.Vt struct buf ,
297utility functions needed by multiple parsers,
298and the top-level functions to call the parsers.
299.Pp
300Uses the opaque type
301.Vt struct roff
302from
303.Pa roff.c
304for function prototypes.
305Uses the type
306.Vt struct roff_man
307from
308.Pa roff.h
309as an opaque type for function prototypes.
310.It Qq Pa roff_int.h
311Parser internals shared by multiple parsers.
312Can be used in all parsers, but not in main programs or formatters.
313.Pp
314Requires
315.Qq Pa roff.h
316for
317.Vt enum roff_type
318and
319.Vt enum roff_tok .
320.Pp
321Provides
322.Vt enum roff_next ,
323.Vt struct roff_man ,
324functions named
325.Fn roff_*
326to handle roff nodes,
327.Fn roffhash_alloc ,
328.Fn roffhash_find ,
329.Fn roffhash_free ,
330and
331.Fn roff_validate ,
332and the two special functions
333.Fn man_breakscope
334and
335.Fn mdoc_argv_free
336because the latter two are needed by
337.Qq Pa roff.c .
338.Pp
339Uses the types
340.Vt struct ohash
341from
342.Pa mandoc_ohash.h ,
343.Vt struct roff_node
344and
345.Vt struct roff_meta
346from
347.Pa roff.h ,
348.Vt struct roff
349from
350.Pa roff.c ,
351and
352.Vt struct mdoc_arg
353from
354.Pa mdoc.h
355as opaque types for function prototypes.
356.It Qq Pa libmdoc.h
357Requires
358.Qq Pa roff.h
359for
360.Vt enum roff_tok
361and
362.Vt enum roff_sec .
363.Pp
364Provides
365.Vt enum margserr ,
366.Vt enum mdelim ,
367.Vt struct mdoc_macro ,
368and many functions internal to the
369.Xr mdoc 7
370parser.
371.Pp
372Uses the types
373.Vt struct roff_node
374from
375.Pa roff.h ,
376.Vt struct roff_man
377from
378.Pa roff_int.h ,
379and
380.Vt struct mdoc_arg
381from
382.Pa mdoc.h
383as opaque types for function prototypes.
384.Pp
385When this header is included, the same file should not include
386interfaces of different parsers.
387.It Qq Pa libman.h
388Requires
389.Qq Pa roff.h
390for
391.Vt enum roff_tok .
392.Pp
393Provides
394.Vt struct man_macro
395and some functions internal to the
396.Xr man 7
397parser.
398.Pp
399Uses the types
400.Vt struct roff_node
401from
402.Pa roff.h
403and
404.Vt struct roff_man
405from
406.Pa roff_int.h
407as opaque types for function prototypes.
408.Pp
409When this header is included, the same file should not include
410interfaces of different parsers.
411.It Qq Pa eqn_parse.h
412External interface of the
413.Xr eqn 7
414parser, for use in the
415.Xr roff 7
416and
417.Xr eqn 7
418parsers only.
419.Pp
420Requires
421.In sys/types.h
422for
423.Vt size_t .
424.Pp
425Provides
426.Vt struct eqn_node
427and the functions
428.Fn eqn_alloc ,
429.Fn eqn_box_new ,
430.Fn eqn_box_free ,
431.Fn eqn_free ,
432.Fn eqn_parse ,
433.Fn eqn_read ,
434and
435.Fn eqn_reset .
436.Pp
437Uses the type
438.Vt struct eqn_box
439from
440.Pa mandoc.h
441as an opaque type for function prototypes.
442Uses the types
443.Vt struct roff_node
444from
445.Pa roff.h
446and
447.Vt struct eqn_def
448from
449.Pa eqn.c
450as opaque struct members.
451.Pp
452When this header is included, the same file should not include
453internals of different parsers.
454.It Qq Pa tbl_parse.h
455External interface of the
456.Xr tbl 7
457parser, for use in the
458.Xr roff 7
459and
460.Xr tbl 7
461parsers only.
462.Pp
463Provides the functions documented in
464.Xr tbl 3 .
465.Pp
466Uses the types
467.Vt struct tbl_span
468from
469.Pa tbl.h
470and
471.Vt struct tbl_node
472from
473.Pa tbl_int.h
474as opaque types for function prototypes.
475.Pp
476When this header is included, the same file should not include
477internals of different parsers.
478.It Qq Pa tbl_int.h
479Internal interfaces of the
480.Xr tbl 7
481parser, for use inside the
482.Xr tbl 7
483parser only.
484.Pp
485Requires
486.Qq Pa tbl.h
487for
488.Vt struct tbl_opts .
489.Pp
490Provides
491.Vt enum tbl_part ,
492.Vt struct tbl_node ,
493and the functions
494.Fn tbl_option ,
495.Fn tbl_layout ,
496.Fn tbl_data ,
497.Fn tbl_cdata ,
498and
499.Fn tbl_reset .
500.Pp
501When this header is included, the same file should not include
502interfaces of different parsers.
503.El
504.Ss Formatter interface
505These headers should be included after any parser interface headers.
506No parser internal headers should be included by the same file.
507.Bl -tag -width Ds
508.It Qq Pa out.h
509Requires
510.In sys/types.h
511for
512.Vt size_t .
513.Pp
514Provides
515.Vt enum roffscale ,
516.Vt struct roffcol ,
517.Vt struct roffsu ,
518.Vt struct rofftbl ,
519.Fn a2roffsu ,
520and
521.Fn tblcalc .
522.Pp
523Uses
524.Vt struct tbl_span
525from
526.Pa mandoc.h
527as an opaque type for function prototypes.
528.Pp
529When this header is included, the same file should not include
530.Pa mansearch.h .
531.It Qq Pa term.h
532Requires
533.In sys/types.h
534for
535.Vt size_t
536and
537.Qq Pa out.h
538for
539.Vt struct roffsu
540and
541.Vt struct rofftbl .
542.Pp
543Provides
544.Vt enum termenc ,
545.Vt enum termfont ,
546.Vt enum termtype ,
547.Vt struct termp_tbl ,
548.Vt struct termp ,
549.Fn roff_term_pre ,
550and many terminal formatting functions.
551.Pp
552Uses the opaque type
553.Vt struct termp_ps
554from
555.Pa term_ps.c .
556Uses
557.Vt struct tbl_span
558and
559.Vt struct eqn_box
560from
561.Pa mandoc.h
562and
563.Vt struct roff_meta
564and
565.Vt struct roff_node
566from
567.Pa roff.h
568as opaque types for function prototypes.
569.Pp
570When this header is included, the same file should not include
571.Pa html.h
572or
573.Pa mansearch.h .
574.It Qq Pa html.h
575Requires
576.In sys/types.h
577for
578.Vt size_t ,
579.Pa mandoc.h
580for
581.Vt enum mandoc_esc ,
582and
583.Qq Pa out.h
584for
585.Vt struct roffsu
586and
587.Vt struct rofftbl .
588.Pp
589Provides
590.Vt enum htmltag ,
591.Vt enum htmlattr ,
592.Vt enum htmlfont ,
593.Vt struct tag ,
594.Vt struct tagq ,
595.Vt struct htmlpair ,
596.Vt struct html ,
597.Fn roff_html_pre ,
598and many HTML formatting functions.
599.Pp
600Uses
601.Vt struct tbl_span
602and
603.Vt struct eqn_box
604from
605.Pa mandoc.h
606and
607.Vt struct roff_node
608from
609.Pa roff.h
610as opaque types for function prototypes.
611.Pp
612When this header is included, the same file should not include
613.Pa term.h
614or
615.Pa mansearch.h .
616.It Qq Pa tag.h
617Requires
618.In sys/types.h
619for
620.Vt size_t .
621.Pp
622Provides an interface to generate
623.Xr ctags 1
624files for the
625.Ic :t
626functionality mentioned in
627.Xr man 1 .
628.It Qq Pa main.h
629Provides the top level steering functions for all formatters.
630.Pp
631Uses the type
632.Vt struct roff_meta
633from
634.Pa roff.h
635as an opaque type for function prototypes.
636.It Qq Pa manconf.h
637Requires
638.In sys/types.h
639for
640.Vt size_t .
641.Pp
642Provides
643.Vt struct manconf ,
644.Vt struct manpaths ,
645.Vt struct manoutput ,
646and the functions
647.Fn manconf_parse ,
648.Fn manconf_output ,
649.Fn manconf_free ,
650and
651.Fn manpath_base .
652.It Qq Pa mansearch.h
653Requires
654.In sys/types.h
655for
656.Vt size_t
657and
658.In stdint.h
659for
660.Vt uint64_t .
661.Pp
662Provides
663.Vt enum argmode ,
664.Vt struct manpage ,
665.Vt struct mansearch ,
666and the functions
667.Fn mansearch
668and
669.Fn mansearch_free .
670.Pp
671Uses
672.Vt struct manpaths
673from
674.Pa manconf.h
675as an opaque type for function prototypes.
676.Pp
677When this header is included, the same file should not include
678.Pa out.h ,
679.Pa term.h ,
680or
681.Pa html.h .
682.El
683