docs: Added All FreeBSD Manuals

1 files changed, 773 insertions, 0 deletions

diff --git a/static/freebsd/man3/mandoc_headers.3 b/static/freebsd/man3/mandoc_headers.3
new file mode 100644
index 00000000..ae01c7bf
--- /dev/null
+++ b/static/freebsd/man3/mandoc_headers.3
@@ -0,0 +1,773 @@
+.\" $Id: mandoc_headers.3,v 1.35 2022/04/14 16:43:44 schwarze Exp $
+.\"
+.\" Copyright (c) 2014-2022 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 14 2022 $
+.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 the order shown in this manual page,
+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 roff 7
+parser
+.It
+.Xr mdoc 7
+parser
+.It
+.Xr man 7
+parser
+.It
+.Xr tbl 7
+parser
+.It
+.Xr eqn 7
+parser
+.It
+terminal formatters
+.It
+HTML formatters
+.It
+search tools
+.It
+main programs
+.El
+.Pp
+Note that mere usage of an opaque struct 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.
+.Bl -tag -width Ds
+.It Qq Pa mandoc_aux.h
+Memory allocation utility functions; can be used everywhere.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides the functions documented in
+.Xr mandoc_malloc 3 .
+.Pp
+When this header is included, the same file must not include
+.Qq Pa mandoc_dbg.h
+because
+.Qq Pa mandoc_aux.h
+automatically includes
+.Qq Pa mandoc_dbg.h
+if and only if the preprocessor symbol
+.Dv DEBUG_MEMORY
+is defined.
+.It Qq Pa mandoc_dbg.h
+Debugging utility functions and
+debugging wrappers around memory allocation functions.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides the functions documented in
+.Xr mandoc_dbg_init 3 .
+.Pp
+This header must not be included unless the preprocessor symbol
+.Dv DEBUG_MEMORY
+is defined.
+When this header is included, the same file must not include
+.Qq Pa mandoc_aux.h .
+.It Qq Pa mandoc_ohash.h
+Hashing utility functions; can be used everywhere.
+.Pp
+Requires
+.In stddef.h
+for
+.Vt ptrdiff_t
+and
+.In stdint.h
+for
+.Vt uint32_t .
+.Pp
+Includes
+.In ohash.h
+and provides
+.Fn mandoc_ohash_init .
+.It Qq Pa mandoc.h
+Error handling, escape sequence, and character utilities;
+can be used everywhere.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t
+and
+.In stdio.h
+for
+.Vt FILE .
+.Pp
+Provides
+.Vt enum mandoc_esc ,
+.Vt enum mandocerr ,
+.Vt enum mandoclevel ,
+the function
+.Xr mandoc_escape 3 ,
+the functions described in
+.Xr mchars_alloc 3 ,
+and the
+.Fn mandoc_msg*
+functions.
+.It Qq Pa roff.h
+Common data types for all syntax trees and related functions;
+can be used everywhere.
+.Pp
+Provides
+.Vt enum mandoc_os ,
+.Vt enum mdoc_endbody ,
+.Vt enum roff_macroset ,
+.Vt enum roff_sec ,
+.Vt enum roff_tok ,
+.Vt enum roff_type ,
+.Vt struct roff_man ,
+.Vt struct roff_meta ,
+.Vt struct roff_node ,
+the constant array
+.Va roff_name
+and the function
+.Fn deroff .
+.Pp
+Uses pointers to the types
+.Vt struct ohash
+from
+.Qq Pa mandoc_ohash.h ,
+.Vt struct mdoc_arg
+and
+.Vt union mdoc_data
+from
+.Qq Pa mdoc.h ,
+.Vt struct tbl_span
+from
+.Qq Pa tbl.h ,
+and
+.Vt struct eqn_box
+from
+.Qq Pa eqn.h
+as opaque struct members.
+.It Qq Pa tbl.h
+Data structures for the
+.Xr tbl 7
+parse tree; can be used everywhere.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t
+and
+.Qq Pa mandoc.h
+for
+.Vt enum mandoc_esc .
+.Pp
+Provides
+.Vt enum tbl_cellt ,
+.Vt enum tbl_datt ,
+.Vt enum tbl_spant ,
+.Vt struct tbl_opts ,
+.Vt struct tbl_cell ,
+.Vt struct tbl_row ,
+.Vt struct tbl_dat ,
+and
+.Vt struct tbl_span .
+.It Qq Pa eqn.h
+Data structures for the
+.Xr eqn 7
+parse tree; can be used everywhere.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides
+.Vt enum eqn_boxt ,
+.Vt enum eqn_fontt ,
+.Vt enum eqn_post ,
+and
+.Vt struct eqn_box .
+.It Qq Pa mandoc_parse.h
+Top level parser interface, for use in the main program
+and in the main parser, but not in formatters.
+.Pp
+Requires
+.Qq Pa mandoc.h
+for
+.Vt enum mandocerr
+and
+.Vt enum mandoclevel
+and
+.Qq Pa roff.h
+for
+.Vt enum mandoc_os .
+.Pp
+Uses the opaque type
+.Vt struct mparse
+from
+.Pa read.c
+for function prototypes.
+Uses
+.Vt struct roff_meta
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.It Qq Pa mandoc_xr.h
+Cross reference validation; intended for use in the main program
+and in parsers, but not in formatters.
+.Pp
+Provides
+.Vt struct mandoc_xr
+and the functions
+.Fn mandoc_xr_reset ,
+.Fn mandoc_xr_add ,
+.Fn mandoc_xr_get ,
+and
+.Fn mandoc_xr_free .
+.It Qq Pa tag.h
+Internal interfaces to tag syntax tree nodes,
+for use by validation modules only.
+.Pp
+Requires
+.In limits.h
+for
+.Dv INT_MAX .
+.Pp
+Provides the functions
+.Fn tag_alloc ,
+.Fn tag_put ,
+.Fn tag_check ,
+and
+.Fn tag_free
+and some
+.Dv TAG_*
+constants.
+.Pp
+Uses the type
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.El
+.Pp
+The following two require
+.Qq Pa roff.h
+but no other mandoc headers.
+Afterwards, any other mandoc headers can be included as needed.
+.Bl -tag -width Ds
+.It Qq Pa mdoc.h
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides
+.Vt enum mdocargt ,
+.Vt enum mdoc_auth ,
+.Vt enum mdoc_disp ,
+.Vt enum mdoc_font ,
+.Vt enum mdoc_list ,
+.Vt struct mdoc_argv ,
+.Vt struct mdoc_arg ,
+.Vt struct mdoc_an ,
+.Vt struct mdoc_bd ,
+.Vt struct mdoc_bf ,
+.Vt struct mdoc_bl ,
+.Vt struct mdoc_rs ,
+.Vt union mdoc_data ,
+and the functions
+.Fn mdoc_*
+described in
+.Xr mandoc 3 .
+.Pp
+Uses the types
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+and
+.Vt struct roff_man
+from
+.Qq Pa roff_int.h
+as opaque types for function prototypes.
+.Pp
+When this header is included, the same file should not include
+internals of different parsers.
+.It Qq Pa man.h
+Provides the functions
+.Fn man_*
+described in
+.Xr mandoc 3 .
+.Pp
+Uses the type
+.Vt struct roff_man
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.Pp
+When this header is included, the same file should not include
+internals of different parsers.
+.El
+.Ss Parser internals
+Most of 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
+and
+.Qq Pa mandoc.h
+for
+.Vt enum mandocerr .
+.Pp
+Provides
+.Vt struct buf ,
+utility functions needed by multiple parsers,
+and the top-level functions to call the parsers.
+.Pp
+Uses the opaque type
+.Vt struct roff
+from
+.Pa roff.c
+for function prototypes.
+Uses the type
+.Vt struct roff_man
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.It Qq Pa roff_int.h
+Parser internals shared by multiple parsers.
+Can be used in all parsers, but not in main programs or formatters.
+.Pp
+Requires
+.Qq Pa roff.h
+for
+.Vt enum roff_type
+and
+.Vt enum roff_tok .
+.Pp
+Provides
+.Vt enum roff_next ,
+.Vt struct roff_man ,
+functions named
+.Fn roff_*
+to handle roff nodes,
+.Fn roffhash_alloc ,
+.Fn roffhash_find ,
+.Fn roffhash_free ,
+and
+.Fn roff_validate ,
+and the two special functions
+.Fn man_breakscope
+and
+.Fn mdoc_argv_free
+because the latter two are needed by
+.Pa roff.c .
+.Pp
+Uses the types
+.Vt struct ohash
+from
+.Qq Pa mandoc_ohash.h ,
+.Vt struct roff_node
+and
+.Vt struct roff_meta
+from
+.Qq Pa roff.h ,
+.Vt struct roff
+from
+.Pa roff.c ,
+and
+.Vt struct mdoc_arg
+from
+.Qq Pa mdoc.h
+as opaque types for function prototypes.
+.It Qq Pa libmdoc.h
+Requires
+.Qq Pa roff.h
+for
+.Vt enum roff_tok
+and
+.Vt enum roff_sec .
+.Pp
+Provides
+.Vt enum margserr ,
+.Vt enum mdelim ,
+.Vt struct mdoc_macro ,
+and many functions internal to the
+.Xr mdoc 7
+parser.
+.Pp
+Uses the types
+.Vt struct roff_node
+from
+.Qq Pa roff.h ,
+.Vt struct roff_man
+from
+.Qq Pa roff_int.h ,
+and
+.Vt struct mdoc_arg
+from
+.Qq Pa mdoc.h
+as opaque types for function prototypes.
+.Pp
+When this header is included, the same file should not include
+interfaces of different parsers.
+.It Qq Pa libman.h
+Requires
+.Qq Pa roff.h
+for
+.Vt enum roff_tok .
+.Pp
+Provides
+.Vt struct man_macro
+and some functions internal to the
+.Xr man 7
+parser.
+.Pp
+Uses the types
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+and
+.Vt struct roff_man
+from
+.Qq Pa roff_int.h
+as opaque types for function prototypes.
+.Pp
+When this header is included, the same file should not include
+interfaces of different parsers.
+.It Qq Pa eqn_parse.h
+External interface of the
+.Xr eqn 7
+parser, for use in the
+.Xr roff 7
+and
+.Xr eqn 7
+parsers only.
+.Pp
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides
+.Vt struct eqn_node
+and the functions
+.Fn eqn_alloc ,
+.Fn eqn_box_new ,
+.Fn eqn_box_free ,
+.Fn eqn_free ,
+.Fn eqn_parse ,
+.Fn eqn_read ,
+and
+.Fn eqn_reset .
+.Pp
+Uses the type
+.Vt struct eqn_box
+from
+.Qq Pa mandoc.h
+as an opaque type for function prototypes.
+Uses the types
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+and
+.Vt struct eqn_def
+from
+.Pa eqn.c
+as opaque struct members.
+.Pp
+When this header is included, the same file should not include
+internals of different parsers.
+.It Qq Pa tbl_parse.h
+External interface of the
+.Xr tbl 7
+parser, for use in the
+.Xr roff 7
+and
+.Xr tbl 7
+parsers only.
+.Pp
+Provides the functions documented in
+.Xr tbl 3 .
+.Pp
+Uses the types
+.Vt struct tbl_span
+from
+.Qq Pa tbl.h
+and
+.Vt struct tbl_node
+from
+.Qq Pa tbl_int.h
+as opaque types for function prototypes.
+.Pp
+When this header is included, the same file should not include
+internals of different parsers.
+.It Qq Pa tbl_int.h
+Internal interfaces of the
+.Xr tbl 7
+parser, for use inside the
+.Xr tbl 7
+parser only.
+.Pp
+Requires
+.Qq Pa tbl.h
+for
+.Vt struct tbl_opts .
+.Pp
+Provides
+.Vt enum tbl_part ,
+.Vt struct tbl_node ,
+and the functions
+.Fn tbl_option ,
+.Fn tbl_layout ,
+.Fn tbl_data ,
+.Fn tbl_cdata ,
+and
+.Fn tbl_reset .
+.Pp
+When this header is included, the same file should not include
+interfaces of different parsers.
+.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
+.Qq Pa mandoc.h
+as an opaque type for function prototypes.
+.Pp
+When this header is included, the same file should not include
+.Qq 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 ,
+.Fn roff_term_pre ,
+and many terminal formatting functions.
+.Pp
+Uses the opaque type
+.Vt struct termp_ps
+from
+.Pa term_ps.c .
+Uses
+.Vt struct tbl_span
+and
+.Vt struct eqn_box
+from
+.Qq Pa mandoc.h
+and
+.Vt struct roff_meta
+and
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+as opaque types for function prototypes.
+.Pp
+When this header is included, the same file should not include
+.Qq Pa html.h
+or
+.Qq Pa mansearch.h .
+.It Qq Pa tag_term.h
+Requires
+.In sys/types.h
+for
+.Vt size_t
+and
+.In stdio.h
+for
+.Vt FILE .
+.Pp
+Provides an interface to generate
+.Xr ctags 1
+files for the
+.Ic :t
+functionality mentioned in
+.Xr man 1 .
+.Pp
+Uses the type
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.Pp
+When this header is included, the same file should not include
+.Qq Pa html.h
+or
+.Qq Pa mansearch.h .
+.It Qq Pa html.h
+Requires
+.In sys/types.h
+for
+.Vt size_t ,
+.Qq Pa mandoc.h
+for
+.Vt enum mandoc_esc ,
+.Qq Pa roff.h
+for
+.Vt enum roff_tok ,
+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 ,
+.Fn roff_html_pre ,
+and many HTML formatting functions.
+.Pp
+Uses
+.Vt struct tbl_span
+and
+.Vt struct eqn_box
+from
+.Qq Pa mandoc.h
+and
+.Vt struct roff_node
+from
+.Qq Pa roff.h
+as opaque types for function prototypes.
+.Pp
+When this header is included, the same file should not include
+.Qq Pa term.h ,
+.Qq Pa tab_term.h ,
+or
+.Qq Pa mansearch.h .
+.It Qq Pa main.h
+Provides the top level steering functions for all formatters.
+.Pp
+Uses the type
+.Vt struct roff_meta
+from
+.Qq Pa roff.h
+as an opaque type for function prototypes.
+.It Qq Pa manconf.h
+Requires
+.In sys/types.h
+for
+.Vt size_t .
+.Pp
+Provides
+.Vt struct manconf ,
+.Vt struct manpaths ,
+.Vt struct manoutput ,
+and the functions
+.Fn manconf_parse ,
+.Fn manconf_output ,
+.Fn manconf_free ,
+and
+.Fn manpath_base .
+.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
+and
+.Fn mansearch_free .
+.Pp
+Uses
+.Vt struct manpaths
+from
+.Qq Pa manconf.h
+as an opaque type for function prototypes.
+.Pp
+When this header is included, the same file should not include
+.Qq Pa out.h ,
+.Qq Pa term.h ,
+.Qq Pa tab_term.h ,
+or
+.Qq Pa html.h .
+.El