-.\" $Id: mandoc.3,v 1.33 2015/10/13 22:59:54 schwarze Exp $
+.\" $Id: mandoc.3,v 1.38 2017/01/09 01:37:03 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2013, 2014, 2015 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
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: October 13 2015 $
+.Dd $Mdocdate: January 9 2017 $
.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 ,
.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
.Fo mparse_keep
.Fa "struct mparse *parse"
.Fc
-.Ft "enum mandoclevel"
+.Ft int
.Fo mparse_open
.Fa "struct mparse *parse"
-.Fa "int *fd"
.Fa "const char *fname"
.Fc
.Ft "enum mandoclevel"
.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
.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
-.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
+.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
parse it with
.Fn mparse_readfd ;
.It
+close it with
+.Xr close 2 ;
+.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
+.Dv MACROSET_MAN ,
+validate it with
+.Fn mdoc_validate
or
-.Fn man_node ;
+.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
.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
try again after appending
.Ql .gz .
Save the information whether the file is zipped or not.
-Return a file descriptor open for reading in
-.Fa fd ,
-or -1 on failure.
+Return a file descriptor open for reading or -1 on failure.
It can be passed to
.Fn mparse_readfd
or used directly.
Pass the associated filename in
.Va fname .
This function may be called multiple times with different parameters; however,
+.Xr close 2
+and
.Fn mparse_reset
should be invoked between parses.
Declared in
.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
.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
-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 ,
-.Va nchild ,
+.Va last ,
.Va next
and
.Va prev
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