Merge from OpenBSD (similar to my original fix committed on Oct 15, 2010):

[mandoc.git] / man.3

diff --git a/man.3 b/man.3
index 826c6bdad5b9485b22d9673ec4a645d8cf1b6227..2b2d0a910ee018a95bda79a2bacb15420ea26931 100644 (file)
--- a/man.3
+++ b/man.3
@@ -1,4 +1,4 @@
-.\"    $Id: man.3,v 1.27 2010/12/17 11:41:45 kristaps Exp $
+.\"    $Id: man.3,v 1.29 2011/01/03 11:31:26 kristaps Exp $

 .\"
 .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"


@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" 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 17 2010 $
+.Dd $Mdocdate: January 3 2011 $

 .Dt MAN 3
 .Os
 .Sh NAME
 .Dt MAN 3
 .Os
 .Sh NAME


@@ -31,6 +31,11 @@
 .In mandoc.h
 .In man.h
 .Vt extern const char * const * man_macronames;
 .In mandoc.h
 .In man.h
 .Vt extern const char * const * man_macronames;

+.Ft int
+.Fo man_addspan
+.Fa "struct man *man"
+.Fa "const struct tbl_span *span"
+.Fc

 .Ft "struct man *"
 .Fo man_alloc
 .Fa "struct regset *regs"
 .Ft "struct man *"
 .Fo man_alloc
 .Fa "struct regset *regs"


@@ -100,15 +105,28 @@ See
 for details.
 .El
 .Ss Functions
 for details.
 .El
 .Ss Functions

+If
+.Fn man_addspan ,
+.Fn man_parseln ,
+or
+.Fn man_endparse
+return 0, calls to any function but
+.Fn man_reset
+or
+.Fn man_free
+will raise an assertion.

 .Bl -ohang
 .Bl -ohang

+.It Fn man_addspan
+Add a table span to the parsing stream.
+Returns 0 on failure, 1 on success.

 .It Fn man_alloc
 Allocates a parsing structure.
 The
 .Fa data
 pointer is passed to
 .Fa msgs .
 .It Fn man_alloc
 Allocates a parsing structure.
 The
 .Fa data
 pointer is passed to
 .Fa msgs .

-Returns NULL on failure.
-If non-NULL, the pointer must be freed with
+Always returns a valid pointer.
+The pointer must be freed with

 .Fn man_free .
 .It Fn man_reset
 Reset the parser for another parse routine.
 .Fn man_free .
 .It Fn man_reset
 Reset the parser for another parse routine.


@@ -127,26 +145,11 @@ The input buffer
 is modified by this function.
 .It Fn man_endparse
 Signals that the parse is complete.
 is modified by this function.
 .It Fn man_endparse
 Signals that the parse is complete.

-Note that if
-.Fn man_endparse
-is called subsequent to
-.Fn man_node ,
-the resulting tree is incomplete.

 Returns 0 on failure, 1 on success.
 .It Fn man_node
 Returns the first node of the parse.
 Returns 0 on failure, 1 on success.
 .It Fn man_node
 Returns the first node of the parse.

-Note that if
-.Fn man_parseln
-or
-.Fn man_endparse
-return 0, the tree will be incomplete.

 .It Fn man_meta
 Returns the document's parsed meta-data.
 .It Fn man_meta
 Returns the document's parsed meta-data.

-If this information has not yet been supplied or
-.Fn man_parseln
-or
-.Fn man_endparse
-return 0, the data will be incomplete.

 .El
 .Ss Variables
 The following variables are also defined:
 .El
 .Ss Variables
 The following variables are also defined: