-.\" $Id: mandoc.3,v 1.36 2016/01/08 17:48:09 schwarze Exp $
+.\" $Id: mandoc.3,v 1.37 2016/07/07 19:19:01 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010-2016 Ingo Schwarze <schwarze@openbsd.org>
.\" 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 7 2016 $
.Dt MANDOC 3
.Os
.Sh NAME
.Nm mandoc ,
-.Nm man_deroff ,
-.Nm man_meta ,
+.Nm deroff ,
+.Nm mandocmsg ,
.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 ,
.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 *"
.Fo mparse_strlevel
.Fa "enum mandoclevel"
.Fc
-.In sys/types.h
-.In mandoc.h
-.In mdoc.h
+.In roff.h
.Ft void
-.Fo mdoc_deroff
+.Fo deroff
.Fa "char **dest"
-.Fa "const struct mdoc_node *node"
-.Fc
-.Ft "const struct mdoc_meta *"
-.Fo mdoc_meta
-.Fa "const struct mdoc *mdoc"
-.Fc
-.Ft "const struct mdoc_node *"
-.Fo mdoc_node
-.Fa "const struct mdoc *mdoc"
+.Fa "const struct roff_node *node"
.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;
+.Ft void
+.Fo mdoc_validate
+.Fa "struct roff_man *mdoc"
+.Fc
.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
-.Fa "const struct man *man"
+.Fa "const struct roff_man *man"
.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
-.Vt extern const char * const * man_macronames;
.Sh DESCRIPTION
The
.Nm mandoc
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
+.Dv MACROSET_MAN ,
+validate it with
+.Fn mdoc_validate
or
-.Fn man_node ;
+.Fn man_validate ,
+respectively;
+.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
.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
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
.El
.Ss Functions
.Bl -ohang
-.It Fn man_deroff
+.It Fn deroff
Obtain a text-only representation of a
-.Vt struct man_node ,
+.Vt struct roff_node ,
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
-.Fn man_deroff
+.Fn deroff
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_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 .
-.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 ,
See
.Pa main.c
for an example.
+If printing of error messages is not desired,
+.Dv NULL
+may be passed.
.It Ar defos
A default string for the
.Xr mdoc 7
.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
.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
.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
-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
-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
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 ,
-.Va sec ,
+.Va pos ,
and
-.Va pos
+.Va sec
fields), its position in the tree (the
.Va parent ,
.Va child ,
.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 ,
-.Va sec ,
+.Va pos ,
and
-.Va pos
+.Va sec
fields), its position in the tree (the
.Va parent ,
.Va child ,
levels of badly-nested blocks.
.Sh SEE ALSO
.Xr mandoc 1 ,
+.Xr man.cgi 3 ,
.Xr mandoc_escape 3 ,
+.Xr mandoc_headers 3 ,
.Xr mandoc_malloc 3 ,
+.Xr mansearch 3 ,
.Xr mchars_alloc 3 ,
+.Xr tbl 3 ,
.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
.Xr roff 7 ,
.Xr tbl 7
.Sh AUTHORS
+.An -nosplit
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 .
git.ckatri.com / mandoc.git / blobdiff