-.\" $Id: mdoc.3,v 1.12 2009/02/27 08:20:15 kristaps Exp $
+.\" $Id: mdoc.3,v 1.25 2009/03/27 14:56:15 kristaps Exp $
.\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: February 27 2009 $
+.Dd $Mdocdate: March 27 2009 $
.Dt mdoc 3
.Os
.\" SECTION
.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 void
+.Fn mdoc_reset "struct mdoc *mdoc"
.Ft void
.Fn mdoc_free "struct mdoc *mdoc"
.Ft int
.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. Documents with
-.Xr refer 1 ,
-.Xr eqn 1
-and other pre-processor sections aren't accomodated.
-.\" 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.
+.\" 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 delimited in various ways. All are
-preceeded by 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 \&] ) ;
-an asterisk and open-parenthesis
-.Sq \&*(
-for two-character sequences;
-an asterisk and non-open-parenthesis
-.Sq \&*
-for single-character sequences; or one of a small set of standalone
-single characters for other escapes.
-.Pp
-Examples:
-.Pp
-.Bl -tag -width "XXXXXXXX" -offset "XXXX" -compact
-.\" LIST-ITEM
-.It \\*(<=
-prints
-.Dq \*(<=
-.Pq greater-equal
-.\" LIST-ITEM
-.It \\(<-
-prints
-.Dq \(<-
-.Pq left-arrow
-.\" LIST-ITEM
-.It \\[<-]
-also prints
-.Dq \(<-
-.Pq left-arrow
-.\" LIST-ITEM
-.It \\*(Ba
-prints
-.Dq \*(Ba
-.Pq bar
-.\" LIST-ITEM
-.It \\*q
-prints
-.Dq \*q
-.Pq double-quote
-.El
-.\" 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
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
.Nm
utility was written by
-.An Kristaps Dzonsons Aq kristaps@kth.se .
+.An Kristaps Dzonsons Aq kristaps@openbsd.org .
.\" 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