747 lines
13 KiB
Groff
747 lines
13 KiB
Groff
.\" $Id: mandoc_headers.3,v 1.34 2021/08/10 12:55:03 schwarze Exp $
|
|
.\"
|
|
.\" Copyright (c) 2014-2021 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: August 10 2021 $
|
|
.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 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 .
|
|
.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
|