Tiny bits in place for tbl horizontal spans. This will wait for the next

[mandoc.git] / man.3

diff --git a/man.3 b/man.3
index 1a703ae9357db41bed49fed61c685eeb62a0fdfe..2b2d0a910ee018a95bda79a2bacb15420ea26931 100644 (file)
--- a/man.3
+++ b/man.3
@@ -1,4 +1,4 @@
-.\"    $Id: man.3,v 1.25 2010/10/10 09:47:05 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: October 10 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"


@@ -81,27 +86,11 @@ Beyond the full set of macros defined in
 .Xr man 7 ,
 the
 .Nm
 .Xr man 7 ,
 the
 .Nm

-library also accepts the following macros:
+library also accepts the following macro:

 .Pp
 .Bl -tag -width Ds -compact
 .It PD
 .Pp
 .Bl -tag -width Ds -compact
 .It PD

-Has no effect.  Handled as a current-scope line macro.
-.It Sp
-A synonym for
-.Sq sp 0.5v
-.Pq part of the standard preamble for Perl documentation .
-Handled as a line macro.
-.It Vb
-A synonym for
-.Sq nf
-.Pq part of the standard preamble for Perl documentation .
-Handled as a current-scope line macro.
-.It Ve
-A synonym for
-.Sq fi ,
-closing
-.Sq Vb
-.Pq part of the standard preamble for Perl documentation .
+Has no effect.

 Handled as a current-scope line macro.
 .El
 .Ss Types
 Handled as a current-scope line macro.
 .El
 .Ss Types


@@ -116,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.


@@ -143,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:


@@ -270,7 +257,7 @@ man_free(man);
 .Pp
 To compile this, execute
 .Pp
 .Pp
 To compile this, execute
 .Pp

-.D1 % cc main.c libman.a libmandoc.a
+.Dl % cc main.c libman.a libmandoc.a

 .Pp
 where
 .Pa main.c
 .Pp
 where
 .Pa main.c