-.\" $Id: mdoc.3,v 1.10 2009/02/24 13:46:54 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: February 24 2009 $
-.Dt mdoc 3
+.Dd $Mdocdate: July 5 2009 $
+.Dt MDOC 3
.Os
.\" SECTION
.Sh NAME
.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
.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
.Sh DESCRIPTION
The
.Nm mdoc
-library parses lines of mdoc input into an abstract syntax tree.
-.Dq mdoc ,
-which is used to format BSD manual pages, is a macro package of the
-.Dq roff
-language. The
-.Nm
-library implements only those macros documented in the
+library parses lines of
.Xr mdoc 7
-and
-.Xr mdoc.samples 7
-manuals.
-.\" PARAGRAPH
-.Pp
-.Nm
-is
-.Ud
+input (and
+.Em only
+mdoc) into an abstract syntax tree (AST).
.\" PARAGRAPH
.Pp
In general, applications initiate a parsing sequence with
.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
.Sx Functions
and
.Sx Variables
-available to programmers. Following that,
-.Sx Character Encoding
-describes input format. Lastly,
-.Sx Abstract Syntax Tree ,
-documents the output tree.
+available to programmers. Following that, the
+.Sx Abstract Syntax Tree
+section documents the output tree.
.\" SUBSECTION
.Ss Types
Both functions (see
.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.
An array of string-ified token argument names.
.El
.\" SUBSECTION
-.Ss Character Encoding
-The
-.Xr mdoc 3
-library accepts only printable ASCII characters as defined by
-.Xr isprint 3 .
-Non-ASCII character sequences are escaped with an escape character
-.Sq \\
-and followed by either an open-parenthesis
-.Sq \&(
-for two-character sequences; an open-bracket
-.Sq \&[
-for n-character sequences (terminated at a close-bracket
-.Sq \&] ) ;
-or one of a small set of single characters for other escapes.
-.\" SUBSECTION
.Ss Abstract Syntax Tree
The
.Nm
-functions produce an abstract syntax tree (AST) describing the input
-lines in a regular form. It may be reviewed at any time with
+functions produce an abstract syntax tree (AST) describing input in a
+regular form. It may be reviewed at any time with
.Fn mdoc_nodes ;
however, if called before
.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.
+.Qq In-line
+elements described in
+.Xr mdoc 7
+are described simply as
+.Qq elements .
.\" PARAGRAPH
.Pp
The AST is composed of
.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,
the specific case of
.Sq \&.Bd \-literal ,
an empty line will produce a zero-length string.
-.\" PARAGRAPH
-.Pp
-The rule-of-thumb for mapping node types to macros follows. In-line
-elements, such as
-.Sq \&.Em foo ,
-are classified as ELEMENT nodes, which can only contain text.
-Multi-line elements, such as
-.Sq \&.Sh ,
-are BLOCK elements, where the HEAD constitutes line contents and the
-BODY constitutes subsequent lines. In-line elements with matching
-pairs, such as
-.Sq \&.So
-and
-.Sq \&.Sc ,
-are BLOCK elements with no HEAD tag. The only exception to this is
-.Sq \&.Eo
-and
-.Sq \&.Ec ,
-which has a HEAD and TAIL node corresponding to the enclosure string.
-TEXT nodes, obviously, constitute text, and the ROOT node is the
-document's root.
.\" SECTION
.Sh EXAMPLES
The following example reads lines from stdin and parses them, operating
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';
.Ed
.\" SECTION
.Sh SEE ALSO
-.Xr mdoc 7 ,
-.Xr mdoc.samples 7 ,
-.Xr groff 1 ,
-.Xr mdocml 1
+.Xr mandoc 1 ,
+.Xr mdoc 7
.\" SECTION
.Sh AUTHORS
The
utility was written by
.An Kristaps Dzonsons Aq kristaps@kth.se .
.\" SECTION
-.Sh BUGS
-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 .
-.\" PARAGRAPH
-.Pp
-Un-implemented: the
-.Sq \&Xc
+.Sh CAVEATS
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+The
+.Sq \&.Xc
and
-.Sq \&Xo
+.Sq \&.Xo
macros aren't handled when used to span lines for the
-.Sq \&It
-macro. Such usage is specifically discouraged in
-.Xr mdoc.samples 7 .
-.\" PARAGRAPH
-.Pp
-Bugs: when
-.Sq \&It \-column
-is invoked, whitespace is not stripped around
-.Sq \&Ta
-or tab-character separators.
-.\" PARAGRAPH
-.Pp
-Bugs: elements within columns for
-.Sq \&It \-column
-are not yet supported.
-.\" PARAGRAPH
-.Pp
-Incompatible: the
-.Sq \&At
-macro only accepts a single parameter. Furthermore, several macros
-.Pf ( Sq \&Pp ,
-.Sq \&It ,
-and possibly others) accept multiple arguments with a warning.
-.\" PARAGRAPH
-.Pp
-Incompatible: only those macros specified by
-.Xr mdoc.samples 7
+.Sq \&.It
+macro.
+.\" LIST-ITEM
+.It
+The
+.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
-.Xr mdoc 7
-for
-.Ox
-are supported; support for
-.Nx
-and other
-.Bx
-systems is in progress.
+.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
git.ckatri.com / mandoc.git / blobdiff