\"      Id: mandoc_headers.3,v 1.34 2021/08/10 12:55:03 schwarze Exp
\"
\" Copyright (c) 2014-2021 Ingo Schwarze <[email protected]>
\"
\" 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 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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.