garbage collect the unused "#define INDENT"

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 61012edec95e27b36833575d0daca4fd512307ab..6914a76808f7d773ae223963159204d91c0e7fda 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,7 +1,7 @@
-.\"    $Id: mandoc.3,v 1.36 2016/01/08 17:48:09 schwarze Exp $
+.\"    $Id: mandoc.3,v 1.41 2017/07/04 23:40:01 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>

-.\" Copyright (c) 2010-2016 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010-2017 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
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -15,18 +15,16 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: January 8 2016 $
+.Dd $Mdocdate: July 4 2017 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,
 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,

-.Nm man_deroff ,
-.Nm man_meta ,
+.Nm deroff ,
+.Nm mandocmsg ,

 .Nm man_mparse ,
 .Nm man_mparse ,

-.Nm man_node ,
-.Nm mdoc_deroff ,
-.Nm mdoc_meta ,
-.Nm mdoc_node ,
+.Nm man_validate ,
+.Nm mdoc_validate ,

 .Nm mparse_alloc ,
 .Nm mparse_free ,
 .Nm mparse_getkeep ,
 .Nm mparse_alloc ,
 .Nm mparse_free ,
 .Nm mparse_getkeep ,


@@ -36,7 +34,8 @@
 .Nm mparse_reset ,
 .Nm mparse_result ,
 .Nm mparse_strerror ,
 .Nm mparse_reset ,
 .Nm mparse_result ,
 .Nm mparse_strerror ,

-.Nm mparse_strlevel
+.Nm mparse_strlevel ,
+.Nm mparse_updaterc

 .Nd mandoc macro compiler library
 .Sh SYNOPSIS
 .In sys/types.h
 .Nd mandoc macro compiler library
 .Sh SYNOPSIS
 .In sys/types.h


@@ -48,9 +47,10 @@
 .Ft struct mparse *
 .Fo mparse_alloc
 .Fa "int options"
 .Ft struct mparse *
 .Fo mparse_alloc
 .Fa "int options"

-.Fa "enum mandoclevel wlevel"
+.Fa "enum mandocerr mmin"

 .Fa "mandocmsg mmsg"
 .Fa "mandocmsg mmsg"

-.Fa "char *defos"
+.Fa "enum mandoc_os oe_e"
+.Fa "char *os_s"

 .Fc
 .Ft void
 .Fo (*mandocmsg)
 .Fc
 .Ft void
 .Fo (*mandocmsg)


@@ -91,8 +91,7 @@
 .Ft void
 .Fo mparse_result
 .Fa "struct mparse *parse"
 .Ft void
 .Fo mparse_result
 .Fa "struct mparse *parse"

-.Fa "struct mdoc **mdoc"
-.Fa "struct man **man"
+.Fa "struct roff_man **man"

 .Fa "char **sodest"
 .Fc
 .Ft "const char *"
 .Fa "char **sodest"
 .Fc
 .Ft "const char *"


@@ -103,45 +102,38 @@
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc

-.In sys/types.h
-.In mandoc.h
-.In mdoc.h

 .Ft void
 .Ft void

-.Fo mdoc_deroff
-.Fa "char **dest"
-.Fa "const struct mdoc_node *node"
-.Fc
-.Ft "const struct mdoc_meta *"
-.Fo mdoc_meta
-.Fa "const struct mdoc *mdoc"
+.Fo mparse_updaterc
+.Fa "struct mparse *parse"
+.Fa "enum mandoclevel *rc"

 .Fc
 .Fc

-.Ft "const struct mdoc_node *"
-.Fo mdoc_node
-.Fa "const struct mdoc *mdoc"
+.In roff.h
+.Ft void
+.Fo deroff
+.Fa "char **dest"
+.Fa "const struct roff_node *node"

 .Fc
 .Fc

+.In sys/types.h
+.In mandoc.h
+.In mdoc.h

 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;

+.Ft void
+.Fo mdoc_validate
+.Fa "struct roff_man *mdoc"
+.Fc

 .In sys/types.h
 .In mandoc.h
 .In man.h
 .In sys/types.h
 .In mandoc.h
 .In man.h

-.Ft void
-.Fo man_deroff
-.Fa "char **dest"
-.Fa "const struct man_node *node"
-.Fc
-.Ft "const struct man_meta *"
-.Fo man_meta
-.Fa "const struct man *man"
-.Fc
+.Vt extern const char * const * man_macronames;

 .Ft "const struct mparse *"
 .Fo man_mparse
 .Ft "const struct mparse *"
 .Fo man_mparse

-.Fa "const struct man *man"
+.Fa "const struct roff_man *man"

 .Fc
 .Fc

-.Ft "const struct man_node *"
-.Fo man_node
-.Fa "const struct man *man"
+.Ft void
+.Fo man_validate
+.Fa "struct roff_man *man"

 .Fc
 .Fc

-.Vt extern const char * const * man_macronames;

 .Sh DESCRIPTION
 The
 .Nm mandoc
 .Sh DESCRIPTION
 The
 .Nm mandoc


@@ -182,10 +174,27 @@ close it with
 retrieve the syntax tree with
 .Fn mparse_result ;
 .It
 retrieve the syntax tree with
 .Fn mparse_result ;
 .It

-iterate over parse nodes with
-.Fn mdoc_node
+depending on whether the
+.Fa macroset
+member of the returned
+.Vt struct roff_man
+is
+.Dv MACROSET_MDOC

 or
 or

-.Fn man_node ;
+.Dv MACROSET_MAN ,
+validate it with
+.Fn mdoc_validate
+or
+.Fn man_validate ,
+respectively;
+.It
+if information about the validity of the input is needed, fetch it with
+.Fn mparse_updaterc ;
+.It
+iterate over parse nodes with starting from the
+.Fa first
+member of the returned
+.Vt struct roff_man ;

 .It
 free all allocated memory with
 .Fn mparse_free
 .It
 free all allocated memory with
 .Fn mparse_free


@@ -193,7 +202,7 @@ and
 .Xr mchars_free 3 ,
 or invoke
 .Fn mparse_reset
 .Xr mchars_free 3 ,
 or invoke
 .Fn mparse_reset

-and parse new files.
+and go back to step 2 to parse new files.

 .El
 .Sh REFERENCE
 This section documents the functions, types, and variables available
 .El
 .Sh REFERENCE
 This section documents the functions, types, and variables available


@@ -211,6 +220,9 @@ An error or warning message during parsing.
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.

+See the DIAGNOSTICS section in
+.Xr mandoc 1
+regarding the meanings of the levels.

 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with


@@ -226,67 +238,37 @@ messages emitted by the parser.
 .El
 .Ss Functions
 .Bl -ohang
 .El
 .Ss Functions
 .Bl -ohang

-.It Fn man_deroff
+.It Fn deroff

 Obtain a text-only representation of a
 Obtain a text-only representation of a

-.Vt struct man_node ,
+.Vt struct roff_node ,

 including text contained in its child nodes.
 including text contained in its child nodes.

-To be used on children of the pointer returned from
-.Fn man_node .
+To be used on children of the
+.Fa first
+member of
+.Vt struct roff_man .

 When it is no longer needed, the pointer returned from
 When it is no longer needed, the pointer returned from

-.Fn man_deroff
+.Fn deroff

 can be passed to
 .Xr free 3 .
 can be passed to
 .Xr free 3 .

-.It Fn man_meta
-Obtain the meta-data of a successful
-.Xr man 7
-parse.
-This may only be used on a pointer returned by
-.Fn mparse_result .
-Declared in
-.In man.h ,
-implemented in
-.Pa man.c .

 .It Fn man_mparse
 Get the parser used for the current output.
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .
 .It Fn man_mparse
 Get the parser used for the current output.
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .

-.It Fn man_node
-Obtain the root node of a successful
-.Xr man 7
-parse.
-This may only be used on a pointer returned by
+.It Fn man_validate
+Validate the
+.Dv MACROSET_MAN
+parse tree obtained with

 .Fn mparse_result .
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .
 .Fn mparse_result .
 Declared in
 .In man.h ,
 implemented in
 .Pa man.c .

-.It Fn mdoc_deroff
-Obtain a text-only representation of a
-.Vt struct mdoc_node ,
-including text contained in its child nodes.
-To be used on children of the pointer returned from
-.Fn mdoc_node .
-When it is no longer needed, the pointer returned from
-.Fn mdoc_deroff
-can be passed to
-.Xr free 3 .
-.It Fn mdoc_meta
-Obtain the meta-data of a successful
-.Xr mdoc
-parse.
-This may only be used on a pointer returned by
-.Fn mparse_result .
-Declared in
-.In mdoc.h ,
-implemented in
-.Pa mdoc.c .
-.It Fn mdoc_node
-Obtain the root node of a successful
-.Xr mdoc
-parse.
-This may only be used on a pointer returned by
+.It Fn mdoc_validate
+Validate the
+.Dv MACROSET_MDOC
+parse tree obtained with

 .Fn mparse_result .
 Declared in
 .In mdoc.h ,
 .Fn mparse_result .
 Declared in
 .In mdoc.h ,


@@ -323,26 +305,44 @@ This is for example useful in
 .Xr makewhatis 8
 .Fl Q
 to quickly build minimal databases.
 .Xr makewhatis 8
 .Fl Q
 to quickly build minimal databases.

-.It Ar wlevel
+.It Ar mmin

 Can be set to
 Can be set to

-.Dv MANDOCLEVEL_BADARG ,
-.Dv MANDOCLEVEL_ERROR ,
+.Dv MANDOCERR_BASE ,
+.Dv MANDOCERR_STYLE ,
+.Dv MANDOCERR_WARNING ,
+.Dv MANDOCERR_ERROR ,
+.Dv MANDOCERR_UNSUPP ,

 or
 or

-.Dv MANDOCLEVEL_WARNING .
+.Dv MANDOCERR_MAX .

 Messages below the selected level will be suppressed.
 .It Ar mmsg
 A callback function to handle errors and warnings.
 See
 .Pa main.c
 for an example.
 Messages below the selected level will be suppressed.
 .It Ar mmsg
 A callback function to handle errors and warnings.
 See
 .Pa main.c
 for an example.

-.It Ar defos
+If printing of error messages is not desired,
+.Dv NULL
+may be passed.
+.It Ar os_e
+Operating system to check base system conventions for.
+If
+.Dv MANDOC_OS_OTHER ,
+the system is automatically detected from
+.Ic \&Os ,
+.Fl Ios ,
+or
+.Xr uname 3 .
+.It Ar os_s

 A default string for the
 .Xr mdoc 7
 A default string for the
 .Xr mdoc 7

-.Sq \&Os
+.Ic \&Os

 macro, overriding the
 .Dv OSNAME
 preprocessor definition and the results of
 .Xr uname 3 .
 macro, overriding the
 .Dv OSNAME
 preprocessor definition and the results of
 .Xr uname 3 .

+Passing
+.Dv NULL
+sets no default.

 .El
 .Pp
 The same parser may be used for multiple files so long as
 .El
 .Pp
 The same parser may be used for multiple files so long as


@@ -421,7 +421,7 @@ implemented in
 .Pa read.c .
 .It Fn mparse_result
 Obtain the result of a parse.
 .Pa read.c .
 .It Fn mparse_result
 Obtain the result of a parse.

-One of the three pointers will be filled in.
+One of the two pointers will be filled in.

 Declared in
 .In mandoc.h ,
 implemented in
 Declared in
 .In mandoc.h ,
 implemented in


@@ -438,17 +438,39 @@ Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
 .In mandoc.h ,
 implemented in
 .Pa read.c .

+.It Fn mparse_updaterc
+If the highest warning or error level that occurred during the current
+.Fa parse
+is higher than
+.Pf * Fa rc ,
+update
+.Pf * Fa rc
+accordingly.
+This is useful after calling
+.Fn mdoc_validate
+or
+.Fn man_validate .
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .

 .El
 .Ss Variables
 .Bl -ohang
 .It Va man_macronames
 .El
 .Ss Variables
 .Bl -ohang
 .It Va man_macronames

-The string representation of a man macro as indexed by
+The string representation of a
+.Xr man 7
+macro as indexed by

 .Vt "enum mant" .
 .It Va mdoc_argnames
 .Vt "enum mant" .
 .It Va mdoc_argnames

-The string representation of a mdoc macro argument as indexed by
+The string representation of an
+.Xr mdoc 7
+macro argument as indexed by

 .Vt "enum mdocargt" .
 .It Va mdoc_macronames
 .Vt "enum mdocargt" .
 .It Va mdoc_macronames

-The string representation of a mdoc macro as indexed by
+The string representation of an
+.Xr mdoc 7
+macro as indexed by

 .Vt "enum mdoct" .
 .El
 .Sh IMPLEMENTATION NOTES
 .Vt "enum mdoct" .
 .El
 .Sh IMPLEMENTATION NOTES


@@ -492,15 +514,15 @@ This AST is governed by the ontological rules dictated in
 and derives its terminology accordingly.
 .Pp
 The AST is composed of
 and derives its terminology accordingly.
 .Pp
 The AST is composed of

-.Vt struct man_node
+.Vt struct roff_node

 nodes with element, root and text types as declared by the
 .Va type
 field.
 Each node also provides its parse point (the
 .Va line ,
 nodes with element, root and text types as declared by the
 .Va type
 field.
 Each node also provides its parse point (the
 .Va line ,

-.Va sec ,
+.Va pos ,

 and
 and

-.Va pos
+.Va sec

 fields), its position in the tree (the
 .Va parent ,
 .Va child ,
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,


@@ -544,16 +566,16 @@ are described simply as
 .Qq elements .
 .Pp
 The AST is composed of
 .Qq elements .
 .Pp
 The AST is composed of

-.Vt struct mdoc_node
+.Vt struct roff_node

 nodes with block, head, body, element, root and text types as declared
 by the
 .Va type
 field.
 Each node also provides its parse point (the
 .Va line ,
 nodes with block, head, body, element, root and text types as declared
 by the
 .Va type
 field.
 Each node also provides its parse point (the
 .Va line ,

-.Va sec ,
+.Va pos ,

 and
 and

-.Va pos
+.Va sec

 fields), its position in the tree (the
 .Va parent ,
 .Va child ,
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,


@@ -641,10 +663,10 @@ TEXT end
 .Ed
 .Pp
 Here, the formatting of the
 .Ed
 .Pp
 Here, the formatting of the

-.Sq \&Ao
+.Ic \&Ao

 block extends from TEXT ao to TEXT ac,
 while the formatting of the
 block extends from TEXT ao to TEXT ac,
 while the formatting of the

-.Sq \&Bo
+.Ic \&Bo

 block extends from TEXT bo to TEXT bc.
 It renders as follows in
 .Fl T Ns Cm ascii
 block extends from TEXT bo to TEXT bc.
 It renders as follows in
 .Fl T Ns Cm ascii


@@ -660,19 +682,21 @@ Using badly-nested blocks is
 .Em strongly discouraged ;
 for example, the
 .Fl T Ns Cm html
 .Em strongly discouraged ;
 for example, the
 .Fl T Ns Cm html

-and
-.Fl T Ns Cm xhtml
-front-ends to
+front-end to

 .Xr mandoc 1
 .Xr mandoc 1

-are unable to render them in any meaningful way.
+is unable to render them in any meaningful way.

 Furthermore, behaviour when encountering badly-nested blocks is not
 consistent across troff implementations, especially when using multiple
 levels of badly-nested blocks.
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 Furthermore, behaviour when encountering badly-nested blocks is not
 consistent across troff implementations, especially when using multiple
 levels of badly-nested blocks.
 .Sh SEE ALSO
 .Xr mandoc 1 ,

+.Xr man.cgi 3 ,

 .Xr mandoc_escape 3 ,
 .Xr mandoc_escape 3 ,

+.Xr mandoc_headers 3 ,

 .Xr mandoc_malloc 3 ,
 .Xr mandoc_malloc 3 ,

+.Xr mansearch 3 ,

 .Xr mchars_alloc 3 ,
 .Xr mchars_alloc 3 ,

+.Xr tbl 3 ,

 .Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,
 .Xr eqn 7 ,
 .Xr man 7 ,
 .Xr mandoc_char 7 ,


@@ -680,7 +704,10 @@ levels of badly-nested blocks.
 .Xr roff 7 ,
 .Xr tbl 7
 .Sh AUTHORS
 .Xr roff 7 ,
 .Xr tbl 7
 .Sh AUTHORS

+.An -nosplit

 The
 .Nm
 library was written by
 The
 .Nm
 library was written by

-.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
+and is maintained by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .