-.\" $Id: mdoc.3,v 1.27 2009/04/12 19:19:57 kristaps Exp $
+.\" $Id: mdoc.3,v 1.33 2009/07/20 13:45:11 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: April 12 2009 $
+.\" 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: July 20 2009 $
.Dt MDOC 3
.Os
.\" SECTION
.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
.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
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
.It Vt struct mdoc_node
A parsed node. Defined in
.Pa mdoc.h .
-See
+See
.Sx Abstract Syntax Tree
for details.
.El
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
.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. If it returns 0, memory could
not be allocated.
.\" 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
.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
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
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
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;
.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
.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
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
git.ckatri.com / mandoc.git / blobdiff