libmdoc accepts whitespace following control character.

[mandoc.git] / man.3

diff --git a/man.3 b/man.3
index bf46131ce815edee9d8f8a1210e2ea37594f5646..7e666d92d84792a28c767a5e62e432711decc43f 100644 (file)
--- a/man.3
+++ b/man.3
@@ -1,4 +1,4 @@
-.\"    $Id: man.3,v 1.6 2009/07/05 19:30:49 kristaps Exp $
+.\"    $Id: man.3,v 1.8 2009/08/17 11:10:02 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -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.
 .\"
-.Dd $Mdocdate: July 5 2009 $
+.Dd $Mdocdate: August 17 2009 $
 .Dt MAN 3
 .Os
 .\" SECTION
@@ -49,7 +49,7 @@
 .Sh DESCRIPTION
 The
 .Nm man
-library parses lines of 
+library parses lines of
 .Xr man 7
 input (and
 .Em only
@@ -58,12 +58,12 @@ man) into an abstract syntax tree (AST).
 .Pp
 In general, applications initiate a parsing sequence with
 .Fn man_alloc ,
-parse each line in a document with 
+parse each line in a document with
 .Fn man_parseln ,
 close the parsing session with
 .Fn man_endparse ,
 operate over the syntax tree returned by
-.Fn man_node 
+.Fn man_node
 and
 .Fn man_meta ,
 then free all allocated memory with
@@ -76,13 +76,13 @@ sequence.  See the
 section for a full example.
 .\" PARAGRAPH
 .Pp
-This section further defines the 
+This section further defines the
 .Sx Types ,
-.Sx Functions 
+.Sx Functions
 and
 .Sx Variables
 available to programmers.  Following that, the
-.Sx Abstract Syntax Tree 
+.Sx Abstract Syntax Tree
 section documents the output tree.
 .\" SUBSECTION
 .Ss Types
@@ -105,7 +105,7 @@ A set of message callbacks defined in
 .It Vt struct man_node
 A parsed node.  Defined in
 .Pa man.h .
-See 
+See
 .Sx Abstract Syntax Tree
 for details.
 .El
@@ -118,8 +118,8 @@ Function descriptions follow:
 Allocates a parsing structure.  The
 .Fa data
 pointer is passed to callbacks in
-.Fa cb , 
-which are documented further in the header file.  
+.Fa cb ,
+which are documented further in the header file.
 The
 .Fa pflags
 arguments are defined in
@@ -128,7 +128,7 @@ Returns NULL on failure.  If non-NULL, the pointer must be freed with
 .Fn man_free .
 .\" LIST-ITEM
 .It Fn man_reset
-Reset the parser for another parse routine.  After its use, 
+Reset the parser for another parse routine.  After its use,
 .Fn man_parseln
 behaves as if invoked for the first time.
 .\" LIST-ITEM
@@ -138,26 +138,26 @@ invocation.
 .\" LIST-ITEM
 .It Fn man_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 
+trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 .Fa buf
 is modified by this function.
 .\" LIST-ITEM
 .It Fn man_endparse
-Signals that the parse is complete.  Note that if 
+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.
 .\" LIST-ITEM
 .It Fn man_node
-Returns the first node of the parse.  Note that if 
+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.  If this information has not
-yet been supplied or 
+yet been supplied or
 .Fn man_parseln
 or
 .Fn man_endparse
@@ -173,7 +173,7 @@ An array of string-ified token names.
 .El
 .\" SUBSECTION
 .Ss Abstract Syntax Tree
-The 
+The
 .Nm
 functions produce an abstract syntax tree (AST) describing input in a
 regular form.  It may be reviewed at any time with
@@ -181,19 +181,19 @@ regular form.  It may be reviewed at any time with
 however, if called before
 .Fn man_endparse ,
 or after
-.Fn man_endparse 
+.Fn man_endparse
 or
 .Fn man_parseln
-fail, it may be incomplete.  
+fail, it may be incomplete.
 .\" PARAGRAPH
 .Pp
 This AST is governed by the ontological
 rules dictated in
 .Xr man 7
-and derives its terminology accordingly.  
+and derives its terminology accordingly.
 .\" PARAGRAPH
 .Pp
-The AST is composed of 
+The AST is composed of
 .Vt struct man_node
 nodes with element, root and text types as declared
 by the
@@ -206,9 +206,9 @@ and
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,
-.Va next 
+.Va next
 and
-.Va prev 
+.Va prev
 fields) and some type-specific data.
 .\" PARAGRAPH
 .Pp
@@ -220,7 +220,13 @@ where capitalised non-terminals represent nodes.
 .It ROOT
 \(<- mnode+
 .It mnode
-\(<- ELEMENT | TEXT
+\(<- ELEMENT | TEXT | BLOCK
+.It BLOCK
+\(<- HEAD BODY
+.It HEAD
+\(<- mnode*
+.It BODY
+\(<- mnode*
 .It ELEMENT
 \(<- ELEMENT | TEXT*
 .It TEXT
@@ -234,10 +240,10 @@ next-lint scope as documented in
 .\" SECTION
 .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating
-on the finished parse tree with 
+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 
+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 -offset "XXXX"
@@ -273,5 +279,5 @@ man_free(man);
 .Sh AUTHORS
 The
 .Nm
-utility was written by 
+utility was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .