diff options
| -rw-r--r-- | Makefile | 2 | ||||
| -rw-r--r-- | mandoc_headers.3 | 511 |
2 files changed, 513 insertions, 0 deletions
@@ -131,6 +131,7 @@ DISTFILES = INSTALL \ mandoc_aux.h \ mandoc_char.7 \ mandoc_escape.3 \ + mandoc_headers.3 \ mandoc_html.3 \ mandoc_malloc.3 \ manpath.h \ @@ -237,6 +238,7 @@ WWW_MANS = apropos.1.html \ mandoc.1.html \ mandoc.3.html \ mandoc_escape.3.html \ + mandoc_headers.3.html \ mandoc_html.3.html \ mandoc_malloc.3.html \ mansearch.3.html \ diff --git a/mandoc_headers.3 b/mandoc_headers.3 new file mode 100644 index 00000000..aa8754e4 --- /dev/null +++ b/mandoc_headers.3 @@ -0,0 +1,511 @@ +.Dd December 1, 2014 +.Dt MANDOC_HEADERS 3 +.Os +.Sh NAME +.Nm mandoc_headers +.Nd ordering of mandoc include files +.Sh DESCRIPTION +To support a cleaner coding style, the mandoc header files do not +contain any include directives and do not guard against multiple +inclusion. +The application developer has to make sure that the headers are +included in a proper order, and that no header is included more +than once. +.Pp +The headers and functions form three major groups: +.Sx Parser interface , +.Sx Parser internals , +and +.Sx Formatter interface . +.Pp +Various rules are given below prohibiting the inclusion of certain +combinations of headers into the same file. +The intention is to keep the following functional components +separate from each other: +.Pp +.Bl -dash -offset indent -compact +.It +.Xr mdoc 7 +parser +.It +.Xr man 7 +parser +.It +.Xr roff 7 +parser +.It +.Xr tbl 7 +parser +.It +.Xr eqn 7 +parser +.It +terminal formatters +.It +HTML formatters +.It +search tools +.El +.Pp +Note that mere usage of an opaque type does +.Em not +require inclusion of the header where that type is defined. +.Ss Parser interface +Each of the following headers can be included without including +any other mandoc header. +These headers should be included before any other mandoc headers. +Afterwards, any other mandoc headers can be included as needed. +.Bl -tag -width Ds +.It Qq Pa mandoc_aux.h +Requires +.In sys/types.h +for +.Vt size_t . +Provides the utility functions documented in +.Xr mandoc_malloc 3 . +.It Qq Pa mandoc.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt enum mandoc_esc , +.Vt enum mandocerr , +.Vt enum mandoclevel , +.Vt enum tbl_cellt , +.Vt enum tbl_datt , +.Vt enum tbl_spant , +.Vt enum eqn_boxt , +.Vt enum eqn_fontt , +.Vt enum eqn_pilet , +.Vt enum eqn_post , +.Vt struct tbl_opts , +.Vt struct tbl_head , +.Vt struct tbl_cell , +.Vt struct tbl_row , +.Vt struct tbl_dat , +.Vt struct tbl_span , +.Vt struct eqn_box , +.Vt struct eqn , +the function prototype typedef +.Fn mandocmsg , +the function +.Xr mandoc_escape 3 , +the functions described in +.Xr mchars_alloc 3 , +and the functions +.Fn mparse_* +described in +.Xr mandoc 3 . +.Pp +Uses the opaque types +.Vt struct mparse +from +.Pa read.c +and +.Vt struct mchars +from +.Pa chars.c +for function prototypes. +Uses the types +.Vt struct mdoc +from +.Pa libmdoc.h +and +.Vt struct man +from +.Pa libman.h +as opaque types for function prototypes. +.It Qq Pa mdoc.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt enum mdoct , +.Vt enum mdocargt , +.Vt enum mdoc_type , +.Vt enum mdoc_sec , +.Vt enum mdoc_endbody , +.Vt enum mdoc_disp , +.Vt enum mdoc_list , +.Vt enum mdoc_auth , +.Vt enum mdoc_font , +.Vt struct mdoc_meta , +.Vt struct mdoc_argv , +.Vt struct mdoc_arg , +.Vt struct mdoc_bd , +.Vt struct mdoc_bl , +.Vt struct mdoc_an , +.Vt struct mdoc_bf , +.Vt struct mdoc_rs , +.Vt struct mdoc_node , +and the functions +.Fn mdoc_* +described in +.Xr mandoc 3 . +.Pp +Uses the type +.Vt struct mdoc +from +.Pa libmdoc.h +as an opaque type for function prototypes. +Uses pointers to the types +.Vt struct tbl_span +and +.Vt struct eqn +as opaque struct members. +.Pp +When this header is included, the same file should not include +.Pa libman.h +or +.Pa libroff.h . +.It Qq Pa man.h +Provides +.Vt enum mant , +.Vt enum man_type , +.Vt struct man_meta , +.Vt struct man_node , +and the functions +.Fn man_* +described in +.Xr mandoc 3 . +.Pp +Uses the opaque type +.Vt struct mparse +from +.Pa read.c +for function prototypes. +Uses the type +.Vt struct man +from +.Pa libman.h +as an opaque type for function prototypes. +Uses pointers to the types +.Vt struct tbl_span +and +.Vt struct eqn +as opaque struct members. +.Pp +When this header is included, the same file should not include +.Pa libmdoc.h +or +.Pa libroff.h . +.El +.Ss Parser internals +The following headers require inclusion of a parser interface header +before they can be included. All parser interface headers should +precede all parser internal headers. When any parser internal headers +are included, the same file should not include any formatter headers. +.Bl -tag -width Ds +.It Qq Pa libmandoc.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt enum rofferr , +.Vt struct buf , +utility functions needed by multiple parsers, +and the top-level functions to call the parsers. +.Pp +Uses the opaque types +.Vt struct mparse +from +.Pa read.c +and +.Vt struct roff +from +.Pa roff.c +for function prototypes. +Uses the types +.Vt enum mandocerr , +.Vt struct tbl_span , +and +.Vt struct eqn +from +.Pa mandoc.h , +.Vt struct mdoc +from +.Pa libmdoc.h , +and +.Vt struct man +from +.Pa libman.h +as opaque types for function prototypes. +.It Qq Pa libmdoc.h +Requires +.Qq Pa mdoc.h +for +.Vt enum mdoct , +.Vt enum mdoc_* , +and +.Vt struct mdoc_* . +.Pp +Provides +.Vt enum mdoc_next , +.Vt enum margserr , +.Vt enum mdelim , +.Vt struct mdoc , +.Vt struct mdoc_macro , +and many functions internal to the +.Xr mdoc 7 +parser. +.Pp +Uses the opaque types +.Vt struct mparse +from +.Pa read.c +and +.Vt struct roff +from +.Pa roff.c . +.Pp +When this header is included, the same file should not include +.Pa man.h , +.Pa libman.h , +or +.Pa libroff.h . +.It Qq Pa libman.h +Requires +.Qq Pa man.h +for +.Vt enum mant +and +.Vt struct man_node. +.Pp +Provides +.Vt enum man_next , +.Vt struct man , +.Vt struct man_macro , +and many functions internal to the +.Xr man 7 +parser. +.Pp +Uses the opaque types +.Vt struct mparse +from +.Pa read.c +and +.Vt struct roff +from +.Pa roff.c . +.Pp +When this header is included, the same file should not include +.Pa mdoc.h , +.Pa libmdoc.h , +or +.Pa libroff.h . +.It Qq Pa libroff.h +Requires +.In sys/types.h +for +.Vt size_t , +.Qq Pa mandoc.h +for +.Vt struct tbl_* +and +.Vt struct eqn , +and +.Qq Pa libmandoc.h +for +.Vt enum rofferr . +.Pp +Provides +.Vt enum tbl_part , +.Vt struct tbl_node , +.Vt struct eqn_def , +.Vt struct eqn_node , +and many functions internal to the +.Xr tbl 7 +and +.Xr eqn 7 +parsers. +.Pp +Uses the opaque type +.Vt struct mparse +from +.Pa read.c . +.Pp +When this header is included, the same file should not include +.Pa man.h , +.Pa mdoc.h , +.Pa libman.h , +or +.Pa libmdoc.h . +.El +.Ss Formatter interface +These headers should be included after any parser interface headers. +No parser internal headers should be included by the same file. +.Bl -tag -width Ds +.It Qq Pa out.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt enum roffscale , +.Vt struct roffcol , +.Vt struct roffsu , +.Vt struct rofftbl , +.Fn a2roffsu , +and +.Fn tblcalc . +.Pp +Uses +.Vt struct tbl_span +from +.Pa mandoc.h +as an opaque type for function prototypes. +.Pp +When this header is included, the same file should not include +.Pa manpath.h +or +.Pa mansearch.h . +.It Qq Pa term.h +Requires +.In sys/types.h +for +.Vt size_t +and +.Qq Pa out.h +for +.Vt struct roffsu +and +.Vt struct rofftbl . +.Pp +Provides +.Vt enum termenc , +.Vt enum termfont , +.Vt enum termtype , +.Vt struct termp_tbl , +.Vt struct termp , +and many terminal formatting functions. +.Pp +Uses the opaque types +.Vt struct mchars +from +.Pa chars.c +and +.Vt struct termp_ps +from +.Pa term_ps.c . +Uses +.Vt struct tbl_span +and +.Vt struct eqn +from +.Pa mandoc.h +as opaque types for function prototypes. +.Pp +When this header is included, the same file should not include +.Pa html.h , +.Pa manpath.h +or +.Pa mansearch.h . +.It Qq Pa html.h +Requires +.In sys/types.h +for +.Vt size_t , +.In stdio.h +for +.Dv BUFSIZ , +and +.Qq Pa out.h +for +.Vt struct roffsu +and +.Vt struct rofftbl . +.Pp +Provides +.Vt enum htmltag , +.Vt enum htmlattr , +.Vt enum htmlfont , +.Vt struct tag , +.Vt struct tagq , +.Vt struct htmlpair , +.Vt struct html , +and many HTML formatting functions. +.Pp +Uses the opaque type +.Vt struct mchars +from +.Pa chars.c . +.Pp +When this header is included, the same file should not include +.Pa term.h , +.Pa manpath.h +or +.Pa mansearch.h . +.It Qq Pa main.h +Provides the top level steering functions for all formatters. +.Pp +Uses the opaque type +.Vt struct mchars +from +.Pa chars.c . +Uses the types +.Vt struct mdoc +from +.Pa libmdoc.h +and +.Vt struct man +from +.Pa libman.h +as opaque types for function prototypes. +.It Qq Pa manpath.h +Requires +.In sys/types.h +for +.Vt size_t . +.Pp +Provides +.Vt struct manpaths +and the functions +.Fn manpath_manconf , +.Fn manpath_parse , +and +.Fn manpath_free . +.Pp +When this header is included, the same file should not include +.Pa out.h , +.Pa term.h , +or +.Pa html.h . +.It Qq Pa mansearch.h +Requires +.In sys/types.h +for +.Vt size_t +and +.In stdint.h +for +.Vt uint64_t . +.Pp +Provides +.Vt enum argmode , +.Vt struct manpage , +.Vt struct mansearch , +and the functions +.Fn mansearch_setup , +.Fn mansearch , +and +.Fn mansearch_free . +.Pp +Uses +.Vt struct manpaths +from +.Pa manpath.h +as an opaque type for function prototypes. +.Pp +When this header is included, the same file should not include +.Pa out.h , +.Pa term.h , +or +.Pa html.h . +.El |