summaryrefslogtreecommitdiffstats
path: root/mdoc.3
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2009-01-19 17:51:32 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2009-01-19 17:51:32 +0000
commit2e32d8081f19a0adc0f1c4091cc0e6720b1a24fe (patch)
tree308da3c4fc54485ffb916bd71b5a04b848513d70 /mdoc.3
parentd427476d5c4b9bd0804fa51647671e6b18e07afa (diff)
downloadmandoc-2e32d8081f19a0adc0f1c4091cc0e6720b1a24fe.tar.gz
More correct validation.
Elision of prologue macros from main tree.
Diffstat (limited to 'mdoc.3')
-rw-r--r--mdoc.359
1 files changed, 44 insertions, 15 deletions
diff --git a/mdoc.3 b/mdoc.3
index 75ac1eea..560f84cb 100644
--- a/mdoc.3
+++ b/mdoc.3
@@ -7,12 +7,15 @@
.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 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
@@ -20,7 +23,9 @@
.Ft int
.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
.Ft "const struct mdoc_node *"
-.Fn mdoc_result "struct mdoc *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 *mdoc"
.\"
@@ -35,13 +40,16 @@ 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.
.Pp
+.\" Function descriptions.
Function descriptions follow:
.Bl -ohang -offset indent
.It Fn mdoc_alloc
@@ -64,14 +72,30 @@ is modified by this function.
Signals that the parse is complete. Note that if
.Fn mdoc_endparse
is called subsequent to
-.Fn mdoc_result ,
+.Fn mdoc_node ,
the resulting tree is incomplete. Returns 0 on failure, 1 on success.
-.It Fn mdoc_result
-Returns the result of the parse or NULL on failure. Note that if
+.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
@@ -105,8 +129,8 @@ while ((buf = fgetln(fp, &len))) {
if ( ! mdoc_endparse(mdoc))
errx(1, "mdoc_endparse");
-if (NULL == (node = mdoc_result(mdoc)))
- errx(1, "mdoc_result");
+if (NULL == (node = mdoc_node(mdoc)))
+ errx(1, "mdoc_node");
parsed(mdoc, node);
mdoc_free(mdoc);
@@ -127,13 +151,15 @@ utility was written by
.\"
.\"
.Sh BUGS
-Both bugs and incompabilities are documented in this section. An
-incompatible macro or behaviour is relative to the default
+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
-The
+Un-implemented: the
.Sq \&Xc
and
.Sq \&Xo
@@ -142,12 +168,15 @@ macros aren't handled when used to span lines for the
macro. Such usage is specifically discouraged in
.Xr mdoc.samples 7 .
.Pp
-When
+Bugs: when
.Sq \&It \-column
is invoked, whitespace is not stripped around
.Sq \&Ta
or tab-character separators.
.Pp
-The
+Incompatible: the
.Sq \&At
-macro only accepts a single parameter.
+macro only accepts a single parameter. Furthermore, several macros
+.Pf ( Sq \&Pp ,
+.Sq \&It ,
+and possibly others) accept multiple arguments with a warning.