Provide a cleanup function for the term_tab module, freeing memory

[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>
@@ -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.
 .\"
-.Dd $Mdocdate: December 14 2018 $
+.Dd $Mdocdate: December 30 2018 $
 .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 ,
@@ -68,11 +66,9 @@
 .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
 .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;
-.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 void
-.Fo man_validate
-.Fa "struct roff_man *man"
-.Fc
 .Sh DESCRIPTION
 The
 .Nm mandoc
@@ -137,27 +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;
-.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 ;
+.Vt struct roff_meta ;
 .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
-.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_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:
@@ -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
-argument of
-.Fn mparse_result .
+field of
+.Vt struct roff_meta .
 .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.
+.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
@@ -347,7 +311,6 @@ 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