]> git.cameronkatri.com Git - mandoc.git/blobdiff - mdoc.3
Beginning of mdoc.7 full-reference in place.
[mandoc.git] / mdoc.3
diff --git a/mdoc.3 b/mdoc.3
index a7ab956ae6e88591e7a33cb2c9852d964f388815..5c6ac4ac21b8c3cea5107b8fbe0253841689dfad 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,23 +1,21 @@
-.\" $Id: mdoc.3,v 1.25 2009/03/27 14:56:15 kristaps Exp $
+.\"    $Id: mdoc.3,v 1.35 2009/10/03 16:36:06 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" 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.
-.\" 
-.Dd $Mdocdate: March 27 2009 $
-.Dt mdoc 3
+.\" 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: October 3 2009 $
+.Dt MDOC 3
 .Os
 .\" SECTION
 .Sh NAME
 .Nd mdoc macro compiler library
 .\" SECTION
 .Sh SYNOPSIS
-.Fd #include <mdoc.h>
+.In mdoc.h
 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"
 .Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
-.Ft void
+.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
 .Sh DESCRIPTION
 The
 .Nm mdoc
-library parses lines of 
+library parses lines of
 .Xr mdoc 7
 input (and
 .Em only
@@ -61,12 +59,12 @@ mdoc) into an abstract syntax tree (AST).
 .Pp
 In general, applications initiate a parsing sequence with
 .Fn mdoc_alloc ,
-parse each line in a document with 
+parse each line in a document with
 .Fn mdoc_parseln ,
 close the parsing session with
 .Fn mdoc_endparse ,
 operate over the syntax tree returned by
-.Fn mdoc_node 
+.Fn mdoc_node
 and
 .Fn mdoc_meta ,
 then free all allocated memory with
@@ -79,13 +77,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
@@ -108,7 +106,7 @@ A set of message callbacks defined in
 .It Vt struct mdoc_node
 A parsed node.  Defined in
 .Pa mdoc.h .
-See 
+See
 .Sx Abstract Syntax Tree
 for details.
 .El
@@ -121,8 +119,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
@@ -131,9 +129,10 @@ 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, 
+Reset the parser for another parse routine.  After its use,
 .Fn mdoc_parseln
-behaves as if invoked for the first time.
+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
@@ -141,26 +140,26 @@ invocation.
 .\" LIST-ITEM
 .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 
+trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 .Fa buf
 is modified by this function.
 .\" LIST-ITEM
 .It Fn mdoc_endparse
-Signals that the parse is complete.  Note that if 
+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.
 .\" LIST-ITEM
 .It Fn mdoc_node
-Returns the first node of the parse.  Note that if 
+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 
+yet been supplied or
 .Fn mdoc_parseln
 or
 .Fn mdoc_endparse
@@ -179,7 +178,7 @@ An array of string-ified token argument 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
@@ -187,24 +186,24 @@ regular form.  It may be reviewed at any time with
 however, if called before
 .Fn mdoc_endparse ,
 or after
-.Fn mdoc_endparse 
+.Fn mdoc_endparse
 or
 .Fn mdoc_parseln
-fail, it may be incomplete.  
+fail, it may be incomplete.
 .\" PARAGRAPH
 .Pp
 This AST is governed by the ontological
 rules dictated in
 .Xr mdoc 7
-and derives its terminology accordingly.  
+and derives its terminology accordingly.
 .Qq In-line
 elements described in
 .Xr mdoc 7
-are described simply as 
+are described simply as
 .Qq elements .
 .\" PARAGRAPH
 .Pp
-The AST is composed of 
+The AST is composed of
 .Vt struct mdoc_node
 nodes with block, head, body, element, root and text types as declared
 by the
@@ -217,9 +216,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
@@ -252,21 +251,21 @@ where capitalised non-terminals represent nodes.
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 although a TEXT node will generally have a non-zero-length string, in
-the specific case of 
+the specific case of
 .Sq \&.Bd \-literal ,
 an empty line will produce a zero-length string.
 .\" 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"
 struct mdoc *mdoc;
-struct mdoc_node *node;
+const struct mdoc_node *node;
 char *buf;
 size_t len;
 int line;
@@ -297,23 +296,23 @@ mdoc_free(mdoc);
 .Sh AUTHORS
 The
 .Nm
-utility was written by 
-.An Kristaps Dzonsons Aq kristaps@openbsd.org .
+utility was written by
+.An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
-The 
+The
 .Sq \&.Xc
 and
 .Sq \&.Xo
 macros aren't handled when used to span lines for the
 .Sq \&.It
-macro. 
+macro.
 .\" LIST-ITEM
 .It
-The 
+The
 .Sq \&.Bsx
 macro family doesn't yet understand version arguments.
 .\" LIST-ITEM
@@ -322,9 +321,9 @@ If not given a value, the \-offset argument to
 .Sq \&.Bd
 and
 .Sq \&.Bl
-should be the width of 
+should be the width of
 .Qq <string> ;
-instead, a value of 
+instead, a value of
 .Li 10n
 is provided.
 .\" LIST-ITEM
@@ -334,12 +333,4 @@ Columns widths in
 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