Digit-width and narrow spaces are non-breaking.

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 8ef7ff1beb4723374fb49197da220389349af253..4ecfbdebd8c2e60dfbfd8684da20299a5067b2ba 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.43 2018/12/14 01:18:25 schwarze Exp $
+.\"    $Id: mandoc.3,v 1.44 2018/12/30 00:49:55 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,14 +15,12 @@
 .\" 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: December 14 2018 $
+.Dd $Mdocdate: December 30 2018 $

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

-.Nm man_validate ,
-.Nm mdoc_validate ,

 .Nm mparse_alloc ,
 .Nm mparse_copy ,
 .Nm mparse_free ,
 .Nm mparse_alloc ,
 .Nm mparse_copy ,
 .Nm mparse_free ,


@@ -68,11 +66,9 @@
 .Fo mparse_reset
 .Fa "struct mparse *parse"
 .Fc
 .Fo mparse_reset
 .Fa "struct mparse *parse"
 .Fc

-.Ft void
+.Ft struct roff_meta *

 .Fo mparse_result
 .Fa "struct mparse *parse"
 .Fo mparse_result
 .Fa "struct mparse *parse"

-.Fa "struct roff_man **man"
-.Fa "char **sodest"

 .Fc
 .In roff.h
 .Ft void
 .Fc
 .In roff.h
 .Ft void


@@ -85,18 +81,10 @@
 .In mdoc.h
 .Vt extern const char * const * mdoc_argnames;
 .Vt extern const char * const * mdoc_macronames;
 .In mdoc.h
 .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
 .Vt extern const char * const * man_macronames;
 .In sys/types.h
 .In mandoc.h
 .In man.h
 .Vt extern const char * const * man_macronames;

-.Ft void
-.Fo man_validate
-.Fa "struct roff_man *man"
-.Fc

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


@@ -137,27 +125,13 @@ close it with
 retrieve the syntax tree with
 .Fn mparse_result ;
 .It
 retrieve the syntax tree with
 .Fn mparse_result ;
 .It

-depending on whether the
-.Fa macroset
-member of the returned
-.Vt struct roff_man
-is
-.Dv MACROSET_MDOC
-or
-.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
 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 ;
+.Vt struct roff_meta ;

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


@@ -205,29 +179,11 @@ including text contained in its child nodes.
 To be used on children of the
 .Fa first
 member of
 To be used on children of the
 .Fa first
 member of

-.Vt struct roff_man .
+.Vt struct roff_meta .

 When it is no longer needed, the pointer returned from
 .Fn deroff
 can be passed to
 .Xr free 3 .
 When it is no longer needed, the pointer returned from
 .Fn deroff
 can be passed to
 .Xr free 3 .

-.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 .
-.It Fn mdoc_validate
-Validate the
-.Dv MACROSET_MDOC
-parse tree obtained with
-.Fn mparse_result .
-Declared in
-.In mdoc.h ,
-implemented in
-.Pa mdoc.c .

 .It Fn mparse_alloc
 Allocate a parser.
 The arguments have the following effect:
 .It Fn mparse_alloc
 Allocate a parser.
 The arguments have the following effect:


@@ -249,8 +205,8 @@ file inclusion requests are always honoured.
 Otherwise, if the request is the only content in an input file,
 only the file name is remembered, to be returned in the
 .Fa sodest
 Otherwise, if the request is the only content in an input file,
 only the file name is remembered, to be returned in the
 .Fa sodest

-argument of
-.Fn mparse_result .
+field of
+.Vt struct roff_meta .

 .Pp
 When the
 .Dv MPARSE_QUICK
 .Pp
 When the
 .Dv MPARSE_QUICK


@@ -259,6 +215,14 @@ 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.

+.Pp
+When the
+.Dv MARSE_VALIDATE
+bit is set,
+.Fn mparse_result
+runs the validation functions before returning the syntax tree.
+This is almost always required, except in certain debugging scenarios,
+for example to dump unvalidated syntax trees.

 .It Ar os_e
 Operating system to check base system conventions for.
 If
 .It Ar os_e
 Operating system to check base system conventions for.
 If


@@ -347,7 +311,6 @@ 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 two pointers will be filled in.

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