[BACK]Return to mandoc_headers.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc_headers.3 between version 1.24 and 1.35

version 1.24, 2018/12/13 06:18:20 version 1.35, 2022/04/14 16:43:44
Line 1 
Line 1 
   .\" $Id$
   .\"
   .\" 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$  .Dd $Mdocdate$
 .Dt MANDOC_HEADERS 3  .Dt MANDOC_HEADERS 3
 .Os  .Os
Line 9  To support a cleaner coding style, the mandoc header f
Line 25  To support a cleaner coding style, the mandoc header f
 contain any include directives and do not guard against multiple  contain any include directives and do not guard against multiple
 inclusion.  inclusion.
 The application developer has to make sure that the headers are  The application developer has to make sure that the headers are
 included in a proper order, and that no header is included more  included in the order shown in this manual page,
 than once.  and that no header is included more than once.
 .Pp  .Pp
 The headers and functions form three major groups:  The headers and functions form three major groups:
 .Sx Parser interface ,  .Sx Parser interface ,
Line 67  for
Line 83  for
 .Pp  .Pp
 Provides the functions documented in  Provides the functions documented in
 .Xr mandoc_malloc 3 .  .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  .It Qq Pa mandoc_ohash.h
 Hashing utility functions; can be used everywhere.  Hashing utility functions; can be used everywhere.
 .Pp  .Pp
Line 84  Includes
Line 127  Includes
 and provides  and provides
 .Fn mandoc_ohash_init .  .Fn mandoc_ohash_init .
 .It Qq Pa mandoc.h  .It Qq Pa mandoc.h
 Error handling utilities and top level parser interface;  Error handling, escape sequence, and character utilities;
 can be used everywhere.  can be used everywhere.
 .Pp  .Pp
 Requires  Requires
 .In sys/types.h  .In sys/types.h
 for  for
 .Vt size_t .  .Vt size_t
   and
   .In stdio.h
   for
   .Vt FILE .
 .Pp  .Pp
 Provides  Provides
 .Vt enum mandoc_esc ,  .Vt enum mandoc_esc ,
 .Vt enum mandocerr ,  .Vt enum mandocerr ,
 .Vt enum mandoclevel ,  .Vt enum mandoclevel ,
 .Vt enum mandoc_os ,  
 the function prototype typedef  
 .Fn mandocmsg ,  
 the function  the function
 .Xr mandoc_escape 3 ,  .Xr mandoc_escape 3 ,
 the functions described in  the functions described in
 .Xr mchars_alloc 3 ,  .Xr mchars_alloc 3 ,
 and the functions  and the
 .Fn mparse_*  .Fn mandoc_msg*
 described in  functions.
 .Xr mandoc 3 .  .It Qq Pa roff.h
   Common data types for all syntax trees and related functions;
   can be used everywhere.
 .Pp  .Pp
 Uses the opaque type  Provides
 .Vt struct mparse  .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  from
 .Pa read.c  .Qq Pa mandoc_ohash.h ,
 for function prototypes.  .Vt struct mdoc_arg
 Uses the type  and
 .Vt struct roff_man  .Vt union mdoc_data
 from  from
 .Pa roff.h  .Qq Pa mdoc.h ,
 as an opaque type for function prototypes.  .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  .It Qq Pa tbl.h
 Data structures for the  Data structures for the
 .Xr tbl 7  .Xr tbl 7
Line 126  parse tree; can be used everywhere.
Line 194  parse tree; can be used everywhere.
 Requires  Requires
 .In sys/types.h  .In sys/types.h
 for  for
 .Vt size_t .  .Vt size_t
   and
   .Qq Pa mandoc.h
   for
   .Vt enum mandoc_esc .
 .Pp  .Pp
 Provides  Provides
 .Vt enum tbl_cellt ,  .Vt enum tbl_cellt ,
Line 154  Provides
Line 226  Provides
 .Vt enum eqn_post ,  .Vt enum eqn_post ,
 and  and
 .Vt struct eqn_box .  .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  .It Qq Pa mandoc_xr.h
 Cross reference validation; intended for use in the main program  Cross reference validation; intended for use in the main program
 and in parsers, but not in formatters.  and in parsers, but not in formatters.
Line 166  and the functions
Line 263  and the functions
 .Fn mandoc_xr_get ,  .Fn mandoc_xr_get ,
 and  and
 .Fn mandoc_xr_free .  .Fn mandoc_xr_free .
 .It Qq Pa roff.h  .It Qq Pa tag.h
 Common data types for all syntax trees and related functions;  Internal interfaces to tag syntax tree nodes,
 can be used everywhere.  for use by validation modules only.
 .Pp  .Pp
 Requires  Requires
 .Qq Pa mandoc_ohash.h  .In limits.h
 for  for
 .Vt struct ohash  .Dv INT_MAX .
 and  
 .Qq Pa mandoc.h  
 for  
 .Vt enum mandoc_os .  
 .Pp  .Pp
 Provides  Provides the functions
 .Vt enum mdoc_endbody ,  .Fn tag_alloc ,
 .Vt enum roff_macroset ,  .Fn tag_put ,
 .Vt enum roff_next ,  .Fn tag_check ,
 .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 functions  
 .Fn deroff  
 and  and
 .Fn roff_validate .  .Fn tag_free
   and some
   .Dv TAG_*
   constants.
 .Pp  .Pp
 Uses pointers to the types  Uses the type
 .Vt struct mdoc_arg  .Vt struct roff_node
 and  
 .Vt union mdoc_data  
 from  from
 .Pa mdoc.h  .Qq Pa roff.h
 as opaque struct members.  as an opaque type for function prototypes.
 .El  .El
 .Pp  .Pp
 The following two require  The following two require
Line 235  and the functions
Line 319  and the functions
 described in  described in
 .Xr mandoc 3 .  .Xr mandoc 3 .
 .Pp  .Pp
 Uses the type  Uses the types
   .Vt struct roff_node
   from
   .Qq Pa roff.h
   and
 .Vt struct roff_man  .Vt struct roff_man
 from  from
 .Pa roff.h  .Qq Pa roff_int.h
 as an opaque type for function prototypes.  as opaque types for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
 internals of different parsers.  internals of different parsers.
Line 249  Provides the functions
Line 337  Provides the functions
 described in  described in
 .Xr mandoc 3 .  .Xr mandoc 3 .
 .Pp  .Pp
 Uses the opaque type  
 .Vt struct mparse  
 from  
 .Pa read.c  
 for function prototypes.  
 Uses the type  Uses the type
 .Vt struct roff_man  .Vt struct roff_man
 from  from
 .Pa roff.h  .Qq Pa roff.h
 as an opaque type for function prototypes.  as an opaque type for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
Line 285  Provides
Line 368  Provides
 utility functions needed by multiple parsers,  utility functions needed by multiple parsers,
 and the top-level functions to call the parsers.  and the top-level functions to call the parsers.
 .Pp  .Pp
 Uses the opaque types  Uses the opaque type
 .Vt struct mparse  
 from  
 .Pa read.c  
 and  
 .Vt struct roff  .Vt struct roff
 from  from
 .Pa roff.c  .Pa roff.c
Line 297  for function prototypes.
Line 376  for function prototypes.
 Uses the type  Uses the type
 .Vt struct roff_man  .Vt struct roff_man
 from  from
 .Pa roff.h  .Qq Pa roff.h
 as an opaque type for function prototypes.  as an opaque type for function prototypes.
 .It Qq Pa roff_int.h  .It Qq Pa roff_int.h
 Parser internals shared by multiple parsers.  Parser internals shared by multiple parsers.
Line 310  for
Line 389  for
 and  and
 .Vt enum roff_tok .  .Vt enum roff_tok .
 .Pp  .Pp
 Provides functions named  Provides
   .Vt enum roff_next ,
   .Vt struct roff_man ,
   functions named
 .Fn roff_*  .Fn roff_*
 to handle roff nodes,  to handle roff nodes,
 .Fn roffhash_alloc ,  .Fn roffhash_alloc ,
 .Fn roffhash_find ,  .Fn roffhash_find ,
 and  
 .Fn roffhash_free ,  .Fn roffhash_free ,
   and
   .Fn roff_validate ,
 and the two special functions  and the two special functions
 .Fn man_breakscope  .Fn man_breakscope
 and  and
 .Fn mdoc_argv_free  .Fn mdoc_argv_free
 because the latter two are needed by  because the latter two are needed by
 .Qq Pa roff.c .  .Pa roff.c .
 .Pp  .Pp
 Uses the types  Uses the types
 .Vt struct roff_man  .Vt struct ohash
 and  from
   .Qq Pa mandoc_ohash.h ,
 .Vt struct roff_node  .Vt struct roff_node
   and
   .Vt struct roff_meta
 from  from
 .Pa roff.h  .Qq Pa roff.h ,
   .Vt struct roff
   from
   .Pa roff.c ,
 and  and
 .Vt struct mdoc_arg  .Vt struct mdoc_arg
 from  from
 .Pa mdoc.h  .Qq Pa mdoc.h
 as opaque types for function prototypes.  as opaque types for function prototypes.
 .It Qq Pa libmdoc.h  .It Qq Pa libmdoc.h
 Requires  Requires
Line 341  Requires
Line 430  Requires
 for  for
 .Vt enum roff_tok  .Vt enum roff_tok
 and  and
 .Qq Pa mdoc.h  .Vt enum roff_sec .
 for  
 .Vt enum mdoc_*  
 and  
 .Vt struct mdoc_* .  
 .Pp  .Pp
 Provides  Provides
 .Vt enum margserr ,  .Vt enum margserr ,
Line 355  and many functions internal to the
Line 440  and many functions internal to the
 .Xr mdoc 7  .Xr mdoc 7
 parser.  parser.
 .Pp  .Pp
 Uses the opaque type  
 .Vt struct mparse  
 from  
 .Pa read.c .  
 Uses the types  Uses the types
   .Vt struct roff_node
   from
   .Qq Pa roff.h ,
 .Vt struct roff_man  .Vt struct roff_man
   from
   .Qq Pa roff_int.h ,
 and  and
 .Vt struct roff_node  .Vt struct mdoc_arg
 from  from
 .Pa roff.h  .Qq Pa mdoc.h
 as opaque types for function prototypes.  as opaque types for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
Line 382  and some functions internal to the
Line 468  and some functions internal to the
 parser.  parser.
 .Pp  .Pp
 Uses the types  Uses the types
 .Vt struct roff_man  
 and  
 .Vt struct roff_node  .Vt struct roff_node
 from  from
 .Pa roff.h  .Qq Pa roff.h
   and
   .Vt struct roff_man
   from
   .Qq Pa roff_int.h
 as opaque types for function prototypes.  as opaque types for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
Line 417  and the functions
Line 505  and the functions
 and  and
 .Fn eqn_reset .  .Fn eqn_reset .
 .Pp  .Pp
 Uses the opaque type  
 .Vt struct mparse  
 from  
 .Pa read.c  
 for function prototypes.  
 Uses the type  Uses the type
 .Vt struct eqn_box  .Vt struct eqn_box
 from  from
 .Pa mandoc.h  .Qq Pa mandoc.h
 as an opaque type for function prototypes.  as an opaque type for function prototypes.
 Uses the types  Uses the types
 .Vt struct roff_node  .Vt struct roff_node
 from  from
 .Pa roff.h  .Qq Pa roff.h
 and  and
 .Vt struct eqn_def  .Vt struct eqn_def
 from  from
Line 451  parsers only.
Line 534  parsers only.
 Provides the functions documented in  Provides the functions documented in
 .Xr tbl 3 .  .Xr tbl 3 .
 .Pp  .Pp
 Uses the opaque type  
 .Vt struct mparse  
 from  
 .Pa read.c .  
 Uses the types  Uses the types
 .Vt struct tbl_span  .Vt struct tbl_span
 from  from
 .Pa tbl.h  .Qq Pa tbl.h
 and  and
 .Vt struct tbl_node  .Vt struct tbl_node
 from  from
 .Pa tbl_int.h  .Qq Pa tbl_int.h
 as opaque types for function prototypes.  as opaque types for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
Line 490  and the functions
Line 569  and the functions
 and  and
 .Fn tbl_reset .  .Fn tbl_reset .
 .Pp  .Pp
 Uses a pointer to the opaque type  
 .Vt struct mparse  
 from  
 .Pa read.c  
 as an opaque struct member.  
 .Pp  
 When this header is included, the same file should not include  When this header is included, the same file should not include
 interfaces of different parsers.  interfaces of different parsers.
 .El  .El
Line 521  and
Line 594  and
 Uses  Uses
 .Vt struct tbl_span  .Vt struct tbl_span
 from  from
 .Pa mandoc.h  .Qq Pa mandoc.h
 as an opaque type for function prototypes.  as an opaque type for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
 .Pa mansearch.h .  .Qq Pa mansearch.h .
 .It Qq Pa term.h  .It Qq Pa term.h
 Requires  Requires
 .In sys/types.h  .In sys/types.h
Line 556  Uses
Line 629  Uses
 and  and
 .Vt struct eqn_box  .Vt struct eqn_box
 from  from
 .Pa mandoc.h  .Qq Pa mandoc.h
 and  and
 .Vt struct roff_meta  .Vt struct roff_meta
 and  and
 .Vt struct roff_node  .Vt struct roff_node
 from  from
 .Pa roff.h  .Qq Pa roff.h
 as opaque types for function prototypes.  as opaque types for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
 .Pa html.h  .Qq Pa html.h
 or  or
 .Pa mansearch.h .  .Qq Pa mansearch.h .
 .It Qq Pa html.h  .It Qq Pa tag_term.h
 Requires  Requires
 .In sys/types.h  .In sys/types.h
 for  for
 .Vt size_t  .Vt size_t
 and  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  .Qq Pa out.h
 for  for
 .Vt struct roffsu  .Vt struct roffsu
Line 597  Uses
Line 703  Uses
 and  and
 .Vt struct eqn_box  .Vt struct eqn_box
 from  from
 .Pa mandoc.h  .Qq Pa mandoc.h
 and  and
 .Vt struct roff_node  .Vt struct roff_node
 from  from
 .Pa roff.h  .Qq Pa roff.h
 as opaque types for function prototypes.  as opaque types for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
 .Pa term.h  .Qq Pa term.h ,
   .Qq Pa tab_term.h ,
 or  or
 .Pa mansearch.h .  .Qq Pa mansearch.h .
 .It Qq Pa tag.h  
 Requires  
 .In sys/types.h  
 for  
 .Vt size_t .  
 .Pp  
 Provides an interface to generate  
 .Xr ctags 1  
 files for the  
 .Ic :t  
 functionality mentioned in  
 .Xr man 1 .  
 .It Qq Pa main.h  .It Qq Pa main.h
 Provides the top level steering functions for all formatters.  Provides the top level steering functions for all formatters.
 .Pp  .Pp
 Uses the type  Uses the type
 .Vt struct roff_man  .Vt struct roff_meta
 from  from
 .Pa roff.h  .Qq Pa roff.h
 as an opaque type for function prototypes.  as an opaque type for function prototypes.
 .It Qq Pa manconf.h  .It Qq Pa manconf.h
 Requires  Requires
Line 666  and
Line 761  and
 Uses  Uses
 .Vt struct manpaths  .Vt struct manpaths
 from  from
 .Pa manconf.h  .Qq Pa manconf.h
 as an opaque type for function prototypes.  as an opaque type for function prototypes.
 .Pp  .Pp
 When this header is included, the same file should not include  When this header is included, the same file should not include
 .Pa out.h ,  .Qq Pa out.h ,
 .Pa term.h ,  .Qq Pa term.h ,
   .Qq Pa tab_term.h ,
 or  or
 .Pa html.h .  .Qq Pa html.h .
 .El  .El
Legend:
Removed from v.1.24  
changed lines
  Added in v.1.35
CVSweb