===================================================================
RCS file: /cvs/mandoc/mandoc.3,v
retrieving revision 1.37
retrieving revision 1.44
diff -u -p -r1.37 -r1.44
--- mandoc/mandoc.3	2016/07/07 19:19:01	1.37
+++ mandoc/mandoc.3	2018/12/30 00:49:55	1.44
@@ -1,7 +1,7 @@
-.\"	$Id: mandoc.3,v 1.37 2016/07/07 19:19:01 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-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
@@ -15,29 +15,23 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 7 2016 $
+.Dd $Mdocdate: December 30 2018 $
 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Nm mandoc ,
 .Nm deroff ,
-.Nm mandocmsg ,
-.Nm man_mparse ,
-.Nm man_validate ,
-.Nm mdoc_validate ,
 .Nm mparse_alloc ,
+.Nm mparse_copy ,
 .Nm mparse_free ,
-.Nm mparse_getkeep ,
-.Nm mparse_keep ,
 .Nm mparse_open ,
 .Nm mparse_readfd ,
 .Nm mparse_reset ,
-.Nm mparse_result ,
-.Nm mparse_strerror ,
-.Nm mparse_strlevel
+.Nm mparse_result
 .Nd mandoc macro compiler library
 .Sh SYNOPSIS
 .In sys/types.h
+.In stdio.h
 .In mandoc.h
 .Pp
 .Fd "#define ASCII_NBRSP"
@@ -46,37 +40,23 @@
 .Ft struct mparse *
 .Fo mparse_alloc
 .Fa "int options"
-.Fa "enum mandoclevel wlevel"
-.Fa "mandocmsg mmsg"
-.Fa "char *defos"
+.Fa "enum mandoc_os oe_e"
+.Fa "char *os_s"
 .Fc
 .Ft void
-.Fo (*mandocmsg)
-.Fa "enum mandocerr errtype"
-.Fa "enum mandoclevel level"
-.Fa "const char *file"
-.Fa "int line"
-.Fa "int col"
-.Fa "const char *msg"
-.Fc
-.Ft void
 .Fo mparse_free
 .Fa "struct mparse *parse"
 .Fc
-.Ft const char *
-.Fo mparse_getkeep
+.Ft void
+.Fo mparse_copy
 .Fa "const struct mparse *parse"
 .Fc
-.Ft void
-.Fo mparse_keep
-.Fa "struct mparse *parse"
-.Fc
 .Ft int
 .Fo mparse_open
 .Fa "struct mparse *parse"
 .Fa "const char *fname"
 .Fc
-.Ft "enum mandoclevel"
+.Ft void
 .Fo mparse_readfd
 .Fa "struct mparse *parse"
 .Fa "int fd"
@@ -86,20 +66,10 @@
 .Fo mparse_reset
 .Fa "struct mparse *parse"
 .Fc
-.Ft void
+.Ft struct roff_meta *
 .Fo mparse_result
 .Fa "struct mparse *parse"
-.Fa "struct roff_man **man"
-.Fa "char **sodest"
 .Fc
-.Ft "const char *"
-.Fo mparse_strerror
-.Fa "enum mandocerr"
-.Fc
-.Ft "const char *"
-.Fo mparse_strlevel
-.Fa "enum mandoclevel"
-.Fc
 .In roff.h
 .Ft void
 .Fo deroff
@@ -111,22 +81,10 @@
 .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;
-.Ft "const struct mparse *"
-.Fo man_mparse
-.Fa "const struct roff_man *man"
-.Fc
-.Ft void
-.Fo man_validate
-.Fa "struct roff_man *man"
-.Fc
 .Sh DESCRIPTION
 The
 .Nm mandoc
@@ -167,24 +125,13 @@ close it with
 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;
+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
@@ -222,9 +169,6 @@ and freed with
 This may be used across parsed input if
 .Fn mparse_reset
 is called between parses.
-.It Vt "mandocmsg"
-A prototype for a function to handle error and warning
-messages emitted by the parser.
 .El
 .Ss Functions
 .Bl -ohang
@@ -235,35 +179,11 @@ including text contained in its child nodes.
 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 .
-.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_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:
@@ -285,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
-argument of
-.Fn mparse_result .
+field of
+.Vt struct roff_meta .
 .Pp
 When the
 .Dv MPARSE_QUICK
@@ -295,25 +215,27 @@ This is for example useful in
 .Xr makewhatis 8
 .Fl Q
 to quickly build minimal databases.
-.It Ar wlevel
-Can be set to
-.Dv MANDOCLEVEL_BADARG ,
-.Dv MANDOCLEVEL_ERROR ,
+.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
+.Dv MANDOC_OS_OTHER ,
+the system is automatically detected from
+.Ic \&Os ,
+.Fl Ios ,
 or
-.Dv MANDOCLEVEL_WARNING .
-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.
-If printing of error messages is not desired,
-.Dv NULL
-may be passed.
-.It Ar defos
+.Xr uname 3 .
+.It Ar os_s
 A default string for the
 .Xr mdoc 7
-.Sq \&Os
+.Ic \&Os
 macro, overriding the
 .Dv OSNAME
 preprocessor definition and the results of
@@ -339,23 +261,13 @@ Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
-.It Fn mparse_getkeep
-Acquire the keep buffer.
-Must follow a call of
-.Fn mparse_keep .
+.It Fn mparse_copy
+Dump a copy of the input to the standard output; used for
+.Fl man T Ns Cm man .
 Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
-.It Fn mparse_keep
-Instruct the parser to retain a copy of its parsed input.
-This can be acquired with subsequent
-.Fn mparse_getkeep
-calls.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa read.c .
 .It Fn mparse_open
 Open the file for reading.
 If that fails and
@@ -399,23 +311,10 @@ implemented in
 .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
 .Pa read.c .
-.It Fn mparse_strerror
-Return a statically-allocated string representation of an error code.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa read.c .
-.It Fn mparse_strlevel
-Return a statically-allocated string representation of a level code.
-Declared in
-.In mandoc.h ,
-implemented in
-.Pa read.c .
 .El
 .Ss Variables
 .Bl -ohang
@@ -625,10 +524,10 @@ TEXT end
 .Ed
 .Pp
 Here, the formatting of the
-.Sq \&Ao
+.Ic \&Ao
 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
@@ -644,11 +543,9 @@ Using badly-nested blocks is
 .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
-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.