Renamed TERMP_NONOSPACE -> TERMP_DANGLE.

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index 37b68091f21cd8bb587edbb55f90eb3c5979a97f..8f667235fd06b8e9511a6d2282c47d3c1ba82fb3 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,23 +1,21 @@
-.\" $Id: mdoc.3,v 1.18 2009/03/16 22:19:19 kristaps Exp $
+.\"    $Id: mdoc.3,v 1.31 2009/07/05 19:30:49 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
-.\" purpose with or without fee is hereby granted, provided that the
-.\" above copyright notice and this permission notice appear in all
-.\" copies.
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
-.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
-.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
-.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
-.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
-.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-.\" PERFORMANCE OF THIS SOFTWARE.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 16 2009 $
-.Dt mdoc 3
+.Dd $Mdocdate: July 5 2009 $
+.Dt MDOC 3
 .Os
 .\" SECTION
 .Sh NAME
@@ -26,7 +24,8 @@
 .Nm mdoc_endparse ,
 .Nm mdoc_node ,
 .Nm mdoc_meta ,
-.Nm mdoc_free
+.Nm mdoc_free ,
+.Nm mdoc_reset
 .Nd mdoc macro compiler library
 .\" SECTION
 .Sh SYNOPSIS
@@ -34,15 +33,17 @@
 .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"
+.Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
+.Ft int
+.Fn mdoc_reset "struct mdoc *mdoc"
 .Ft void
 .Fn mdoc_free "struct mdoc *mdoc"
 .Ft int
 .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
 .Ft "const struct mdoc_node *"
-.Fn mdoc_node "struct mdoc *mdoc"
+.Fn mdoc_node "const struct mdoc *mdoc"
 .Ft "const struct mdoc_meta *"
-.Fn mdoc_meta "struct mdoc *mdoc"
+.Fn mdoc_meta "const struct mdoc *mdoc"
 .Ft int
 .Fn mdoc_endparse "struct mdoc *mdoc"
 .\" SECTION
@@ -53,14 +54,7 @@ library parses lines of
 .Xr mdoc 7
 input (and
 .Em only
-mdoc) into an abstract syntax tree that generalises the semantic
-annotation of its input.  Common front-ends for 
-.Nm
-are
-.Xr mdocterm 1 ,
-.Xr mdoclint 1 
-and
-.Xr mdoctree 1 .
+mdoc) into an abstract syntax tree (AST).
 .\" PARAGRAPH
 .Pp
 In general, applications initiate a parsing sequence with
@@ -75,7 +69,10 @@ and
 .Fn mdoc_meta ,
 then free all allocated memory with
 .Fn mdoc_free .
-See the
+The
+.Fn mdoc_reset
+function may be used in order to reset the parser for another input
+sequence.  See the
 .Sx EXAMPLES
 section for a full example.
 .\" PARAGRAPH
@@ -123,10 +120,20 @@ 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
+which are documented further in the header file.  
+The
+.Fa pflags
+arguments are defined in
+.Pa mdoc.h .
+Returns NULL on failure.  If non-NULL, the pointer must be freed with
 .Fn mdoc_free .
 .\" LIST-ITEM
+.It Fn mdoc_reset
+Reset the parser for another parse routine.  After its use, 
+.Fn mdoc_parseln
+behaves as if invoked for the first time.  If it returns 0, memory could
+not be allocated.
+.\" LIST-ITEM
 .It Fn mdoc_free
 Free all resources of a parser.  The pointer is no longer valid after
 invocation.
@@ -212,9 +219,7 @@ fields), its position in the tree (the
 .Va next 
 and
 .Va prev 
-fields) and type-specific data (the
-.Va data
-field).
+fields) and some type-specific data.
 .\" PARAGRAPH
 .Pp
 The tree itself is arranged according to the following normal form,
@@ -260,13 +265,13 @@ will truncate the file's last character (see
 Further, this example does not error-check nor free memory upon failure.
 .Bd -literal -offset "XXXX"
 struct mdoc *mdoc;
-struct mdoc_node *node;
+const struct mdoc_node *node;
 char *buf;
 size_t len;
 int line;
 
 line = 1;
-mdoc = mdoc_alloc(NULL, NULL);
+mdoc = mdoc_alloc(NULL, 0, NULL);
 
 while ((buf = fgetln(fp, &len))) {
        buf[len - 1] = '\\0';
@@ -285,9 +290,7 @@ mdoc_free(mdoc);
 .Ed
 .\" SECTION
 .Sh SEE ALSO
-.Xr mdocterm 1 ,
-.Xr mdoclint 1 ,
-.Xr mdoctree 1 ,
+.Xr mandoc 1 ,
 .Xr mdoc 7
 .\" SECTION
 .Sh AUTHORS
@@ -301,15 +304,41 @@ utility was written by
 .\" LIST-ITEM
 .It
 The 
-.Sq \&Xc
+.Sq \&.Xc
 and
-.Sq \&Xo
+.Sq \&.Xo
 macros aren't handled when used to span lines for the
-.Sq \&It
+.Sq \&.It
 macro. 
 .\" LIST-ITEM
 .It
 The 
-.Sq \&Bsx
-macro doesn't yet understand version arguments.
+.Sq \&.Bsx
+macro family doesn't yet understand version arguments.
+.\" LIST-ITEM
+.It
+If not given a value, the \-offset argument to
+.Sq \&.Bd
+and
+.Sq \&.Bl
+should be the width of 
+.Qq <string> ;
+instead, a value of 
+.Li 10n
+is provided.
+.\" LIST-ITEM
+.It
+Columns widths in
+.Sq \&.Bl \-column
+should default to width
+.Qq <stringx>
+if not included.
+.\" LIST-ITEM
+.It
+List-width suffix
+.Qq m
+isn't handled.
+.\" LIST-ITEM
+.It
+Contents of the SYNOPSIS section aren't checked.
 .El