===================================================================
RCS file: /cvs/mandoc/mandoc.3,v
retrieving revision 1.25
retrieving revision 1.32
diff -u -p -r1.25 -r1.32
--- mandoc/mandoc.3	2014/08/05 05:48:56	1.25
+++ mandoc/mandoc.3	2015/07/19 06:05:16	1.32
@@ -1,7 +1,7 @@
-.\"	$Id: mandoc.3,v 1.25 2014/08/05 05:48:56 schwarze Exp $
+.\"	$Id: mandoc.3,v 1.32 2015/07/19 06:05:16 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2013, 2014, 2015 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,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 5 2014 $
+.Dd $Mdocdate: July 19 2015 $
 .Dt MANDOC 3
 .Os
 .Sh NAME
@@ -31,17 +31,17 @@
 .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
 .Nd mandoc macro compiler library
-.Sh LIBRARY
-.Lb libmandoc
 .Sh SYNOPSIS
 .In sys/types.h
 .In mandoc.h
+.Pp
 .Fd "#define ASCII_NBRSP"
 .Fd "#define ASCII_HYPH"
 .Fd "#define ASCII_BREAK"
@@ -50,6 +50,7 @@
 .Fa "int options"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"
+.Fa "const struct mchars *mchars"
 .Fa "char *defos"
 .Fc
 .Ft void
@@ -74,6 +75,12 @@
 .Fa "struct mparse *parse"
 .Fc
 .Ft "enum mandoclevel"
+.Fo mparse_open
+.Fa "struct mparse *parse"
+.Fa "int *fd"
+.Fa "const char *fname"
+.Fc
+.Ft "enum mandoclevel"
 .Fo mparse_readfd
 .Fa "struct mparse *parse"
 .Fa "int fd"
@@ -159,12 +166,19 @@ The following describes a general parse sequence:
 .Bl -enum
 .It
 initiate a parsing sequence with
+.Xr mchars_alloc 3
+and
 .Fn mparse_alloc ;
 .It
-parse files or file descriptors with
+open a file with
+.Xr open 2
+or
+.Fn mparse_open ;
+.It
+parse it with
 .Fn mparse_readfd ;
 .It
-retrieve a parsed syntax tree, if the parse was successful, with
+retrieve the syntax tree with
 .Fn mparse_result ;
 .It
 iterate over parse nodes with
@@ -173,7 +187,9 @@ or
 .Fn man_node ;
 .It
 free all allocated memory with
-.Fn mparse_free ,
+.Fn mparse_free
+and
+.Xr mchars_free 3 ,
 or invoke
 .Fn mparse_reset
 and parse new files.
@@ -189,11 +205,17 @@ and
 .Ss Types
 .Bl -ohang
 .It Vt "enum mandocerr"
-A fatal error, error, or warning message during parsing.
+An error or warning message during parsing.
 .It Vt "enum mandoclevel"
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.
+.It Vt "struct mchars"
+An opaque pointer to a a character table.
+Created with
+.Xr mchars_alloc 3
+and freed with
+.Xr mchars_free 3 .
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with
@@ -204,7 +226,7 @@ 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 fatal error, error, and warning
+A prototype for a function to handle error and warning
 messages emitted by the parser.
 .El
 .Ss Functions
@@ -308,7 +330,7 @@ This is for example useful in
 to quickly build minimal databases.
 .It Ar wlevel
 Can be set to
-.Dv MANDOCLEVEL_FATAL ,
+.Dv MANDOCLEVEL_BADARG ,
 .Dv MANDOCLEVEL_ERROR ,
 or
 .Dv MANDOCLEVEL_WARNING .
@@ -318,6 +340,9 @@ A callback function to handle errors and warnings.
 See
 .Pa main.c
 for an example.
+.It Ar mchars
+An opaque pointer to a a character table obtained from
+.Xr mchars_alloc 3 .
 .It Ar defos
 A default string for the
 .Xr mdoc 7
@@ -361,18 +386,33 @@ Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
+.It Fn mparse_open
+Open the file for reading.
+If that fails and
+.Fa fname
+does not already end in
+.Ql .gz ,
+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.
+It can be passed to
+.Fn mparse_readfd
+or used directly.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
 .It Fn mparse_readfd
-Parse a file or file descriptor.
-If
-.Va fd
-is -1,
-.Va fname
-is opened for reading.
-Otherwise,
-.Va fname
-is assumed to be the name associated with
-.Va fd .
-This may be called multiple times with different parameters; however,
+Parse a file descriptor opened with
+.Xr open 2
+or
+.Fn mparse_open .
+Pass the associated filename in
+.Va fname .
+This function may be called multiple times with different parameters; however,
 .Fn mparse_reset
 should be invoked between parses.
 Declared in
@@ -389,14 +429,7 @@ implemented in
 .Pa read.c .
 .It Fn mparse_result
 Obtain the result of a parse.
-Only successful parses
-.Po
-i.e., those where
-.Fn mparse_readfd
-returned less than MANDOCLEVEL_FATAL
-.Pc
-should invoke this function, in which case one of the three pointers will
-be filled in.
+One of the three pointers will be filled in.
 Declared in
 .In mandoc.h ,
 implemented in