===================================================================
RCS file: /cvs/mandoc/Attic/mdoc.3,v
retrieving revision 1.1
retrieving revision 1.4
diff -u -p -r1.1 -r1.4
--- mandoc/Attic/mdoc.3	2009/01/16 14:04:26	1.1
+++ mandoc/Attic/mdoc.3	2009/01/19 17:51:33	1.4
@@ -1,5 +1,5 @@
 .\" 
-.Dd $Mdocdate: January 16 2009 $
+.Dd $Mdocdate: January 19 2009 $
 .Dt mdoc 3
 .Os
 .\"
@@ -7,22 +7,27 @@
 .Nm mdoc_alloc ,
 .Nm mdoc_parseln ,
 .Nm mdoc_endparse ,
-.Nm mdoc_result ,
+.Nm mdoc_node ,
+.Nm mdoc_meta ,
 .Nm mdoc_free
-.Nd mdoc macro compiler
+.Nd mdoc macro compiler library
 .\"
 .Sh SYNOPSIS
-.In mdoc.h
+.Fd #include <mdoc.h>
+.Vt extern const char * const * mdoc_macronames;
+.Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"
 .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
 .Ft void
-.Fn mdoc_free "struct mdoc *"
+.Fn mdoc_free "struct mdoc *mdoc"
 .Ft int
-.Fn mdoc_parseln "struct mdoc *" "int" "char *buf"
+.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
 .Ft "const struct mdoc_node *"
-.Fn mdoc_result "struct mdoc *"
+.Fn mdoc_node "struct mdoc *mdoc"
+.Ft "const struct mdoc_meta *"
+.Fn mdoc_meta "struct mdoc *mdoc"
 .Ft int
-.Fn mdoc_endparse "struct mdoc *"
+.Fn mdoc_endparse "struct mdoc *mdoc"
 .\"
 .Sh DESCRIPTION
 The
@@ -35,22 +40,143 @@ parse each line in a document with 
 close the parsing session with
 .Fn mdoc_endparse ,
 operate over the syntax tree returned by
-.Fn mdoc_result ,
+.Fn mdoc_node 
+and
+.Fn mdoc_meta ,
 then free all allocated memory with
 .Fn mdoc_free .
 See the
 .Sx EXAMPLES
 section for a full example.
-.\" The following requests should be uncommented and used where appropriate.
-.\" This next request is for sections 2, 3, and 9 function return values only.
-.\" .Sh RETURN VALUES
-.\" .Sh EXAMPLES
-.\" The next request is for sections 2, 3, and 9 error and signal handling only.
-.\" .Sh ERRORS
-.\" .Sh SEE ALSO
-.\" .Xr foobar 1
-.\" .Sh STANDARDS
-.\" .Sh HISTORY
-.\" .Sh AUTHORS
-.\" .Sh CAVEATS
-.\" .Sh BUGS
+.Pp
+.\" Function descriptions.
+Function descriptions follow:
+.Bl -ohang -offset indent
+.It Fn mdoc_alloc
+Allocates a parsing structure.  The
+.Fa data
+pointer is passed to callbacks in
+.Fa cb , 
+which are documented further in the header file.  Returns NULL on
+failure.  If non-NULL, the pointer must be freed with
+.Fn mdoc_free .
+.It Fn mdoc_free
+Free all resources of a parser.  The pointer is no longer valid after
+invocation.
+.It Fn mdoc_parseln
+Parse a nil-terminated line of input.  This line should not contain the
+trailing newline.  Returns 0 on failure, 1 on success.  The input buffer 
+.Fa buf
+is modified by this function.
+.It Fn mdoc_endparse
+Signals that the parse is complete.  Note that if 
+.Fn mdoc_endparse
+is called subsequent to
+.Fn mdoc_node ,
+the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
+.It Fn mdoc_node
+Returns the first node of the parse.  Note that if 
+.Fn mdoc_parseln
+or
+.Fn mdoc_endparse
+return 0, the tree will be incomplete.
+.It Fn mdoc_meta
+Returns the document's parsed meta-data.  If this information has not
+yet been supplied or 
+.Fn mdoc_parseln
+or
+.Fn mdoc_endparse
+return 0, the data will be incomplete.
+.El
+.Pp
+.\" Variable descriptions.
+The following variables are also defined:
+.Bl -ohang -offset indent
+.It Va mdoc_macronames
+An array of string-ified token names.
+.It Va mdoc_argnames
+An array of string-ified token argument names.
+.El
+.Pp
+.Nm
+is
+.Ud
+.\" 
+.Sh EXAMPLES
+The following example reads lines from stdin and parses them, operating
+on the finished parse tree with 
+.Fn parsed .
+Note that, if the last line of the file isn't newline-terminated, this
+will truncate the file's last character (see 
+.Xr fgetln 3 ) .
+Further, this example does not error-check nor free memory upon failure.
+.Bd -literal
+struct mdoc *mdoc;
+struct mdoc_node *node;
+char *buf;
+size_t len;
+int line;
+
+line = 1;
+mdoc = mdoc_alloc(NULL, NULL);
+
+while ((buf = fgetln(fp, &len))) {
+	buf[len - 1] = '\\0';
+	if ( ! mdoc_parseln(mdoc, line, buf))
+		errx(1, "mdoc_parseln");
+	line++;
+}
+
+if ( ! mdoc_endparse(mdoc))
+	errx(1, "mdoc_endparse");
+if (NULL == (node = mdoc_node(mdoc)))
+	errx(1, "mdoc_node");
+
+parsed(mdoc, node);
+mdoc_free(mdoc);
+.Ed
+.\"
+.Sh SEE ALSO
+.Xr mdoc 7 ,
+.Xr mdoc.samples 7 ,
+.Xr groff 1 ,
+.Xr mdocml 1
+.\"
+.\"
+.Sh AUTHORS
+The
+.Nm
+utility was written by 
+.An Kristaps Dzonsons Aq kristaps@kth.se .
+.\"
+.\"
+.Sh BUGS
+Bugs, un-implemented macros and incompabilities are documented in this
+section.  The baseline for determining whether macro parsing is 
+.Qq incompatible
+is the default
+.Xr groff 1
+system bundled with 
+.Ox .
+.Pp
+Un-implemented: the 
+.Sq \&Xc
+and
+.Sq \&Xo
+macros aren't handled when used to span lines for the
+.Sq \&It
+macro.  Such usage is specifically discouraged in
+.Xr mdoc.samples 7 .
+.Pp
+Bugs: when 
+.Sq \&It \-column
+is invoked, whitespace is not stripped around
+.Sq \&Ta
+or tab-character separators.
+.Pp
+Incompatible: the 
+.Sq \&At
+macro only accepts a single parameter.  Furthermore, several macros 
+.Pf ( Sq \&Pp ,
+.Sq \&It ,
+and possibly others) accept multiple arguments with a warning.