developer documentation regarding header files

2 files changed, 514 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index a8255fec..5a87ef00 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-# $Id: Makefile,v 1.448 2014/11/28 18:57:31 schwarze Exp $
+# $Id: Makefile,v 1.449 2014/12/01 08:09:26 schwarze Exp $
 #
 # Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 # Copyright (c) 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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