-.\" $Id: mdoc.3,v 1.6 2009/02/23 09:33:34 kristaps Exp $
+.\" $Id: mdoc.3,v 1.17 2009/03/14 05:21:58 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: February 23 2009 $
+.Dd $Mdocdate: March 14 2009 $
.Dt mdoc 3
.Os
.\" SECTION
.Sh DESCRIPTION
The
.Nm mdoc
-library parses lines of mdoc input into an abstract syntax tree.
-.Dq mdoc
-is a macro package of the
-.Dq roff
-language, which is used to format BSD manual pages. 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
+input (and
+.Em only
+mdoc) into an abstract syntax tree that generalises the semantic
+annotation of its input. Common front-ends for
.Nm
-is
-.Ud
+are
+.Xr mdocterm 1 ,
+.Xr mdoclint 1
+and
+.Xr mdoctree 1 .
.\" PARAGRAPH
.Pp
In general, applications initiate a parsing sequence with
.Sx Functions
and
.Sx Variables
-available to programmers. The last sub-section,
-.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
and variables (see
.Sx Variables )
may use the following types:
-.Bl -ohang
+.Bl -ohang -offset "XXXX"
.\" LIST-ITEM
.It Vt struct mdoc
An opaque type defined in
.\" SUBSECTION
.Ss Functions
Function descriptions follow:
-.Bl -ohang
+.Bl -ohang -offset "XXXX"
.\" LIST-ITEM
.It Fn mdoc_alloc
Allocates a parsing structure. The
.\" SUBSECTION
.Ss Variables
The following variables are also defined:
-.Bl -ohang
+.Bl -ohang -offset "XXXX"
.\" LIST-ITEM
.It Va mdoc_macronames
An array of string-ified token names.
.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. 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
The tree itself is arranged according to the following normal form,
where capitalised non-terminals represent nodes.
.Pp
-.Bl -tag -width "ELEMENTXX" -compact
+.Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
.\" LIST-ITEM
.It ROOT
\(<- mnode+
.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, it
-certain cases, such as
-.Dq \&.Bd \-literal ,
+although a TEXT node will generally have a non-zero-length string, in
+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
-.Dq \&.Em foo ,
-are classified as ELEMENT nodes, which can only contain text.
-Multi-line elements such as
-.Dq \&.Sh
-are BLOCK elements, where the HEAD constitutes line contents and the
-BODY constitutes subsequent lines. In-line elements with matching
-pairs, such as
-.Dq \&.So
-and
-.Dq \&.Sc ,
-are BLOCK elements with no HEAD tag. The only exception to this is
-.Dq \&.Eo
-and
-.Dq \&.Ec ,
-which has a HEAD and TAIL node corresponding to the enclosure string.
-TEXT nodes, obviously, constitute text; the ROOT node is the document's
-root.
.\" SECTION
.Sh EXAMPLES
The following example reads lines from stdin and parses them, operating
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
+.Bd -literal -offset "XXXX"
struct mdoc *mdoc;
struct mdoc_node *node;
char *buf;
.Ed
.\" SECTION
.Sh SEE ALSO
-.Xr mdoc 7 ,
-.Xr mdoc.samples 7 ,
-.Xr groff 1 ,
-.Xr mdocml 1
+.Xr mdocterm 1 ,
+.Xr mdoclint 1 ,
+.Xr mdoctree 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 .
-.Pp
-Un-implemented: the
+.Sh CAVEATS
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+The
.Sq \&Xc
and
.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 .
-.Pp
-Bugs: when
-.Sq \&It \-column
-is invoked, whitespace is not stripped around
-.Sq \&Ta
-or tab-character separators.
-.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.
-.Pp
-Incompatible: only those macros specified by
-.Xr mdoc.samples 7
-and
-.Xr mdoc 7
-for
-.Ox
-are supported; support for
-.Nx
-and other
-.Bx
-systems is in progress.
+macro.
+.\" LIST-ITEM
+.It
+The
+.Sq \&Bsx
+macro doesn't yet understand version arguments.
+.El
git.ckatri.com / mandoc.git / blobdiff