-.\" $Id: man.3,v 1.15 2010/03/31 06:37:57 kristaps Exp $
+.\" $Id: man.3,v 1.29 2011/01/03 11:31:26 kristaps Exp $
.\"
.\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" 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 31 2010 $
+.Dd $Mdocdate: January 3 2011 $
.Dt MAN 3
.Os
-.
-.
.Sh NAME
.Nm man ,
.Nm man_alloc ,
-.Nm man_parseln ,
.Nm man_endparse ,
-.Nm man_node ,
-.Nm man_meta ,
.Nm man_free ,
+.Nm man_meta ,
+.Nm man_node ,
+.Nm man_parseln ,
.Nm man_reset
.Nd man macro compiler library
-.
-.
.Sh SYNOPSIS
+.In mandoc.h
.In man.h
.Vt extern const char * const * man_macronames;
+.Ft int
+.Fo man_addspan
+.Fa "struct man *man"
+.Fa "const struct tbl_span *span"
+.Fc
.Ft "struct man *"
-.Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
-.Ft void
-.Fn man_reset "struct man *man"
+.Fo man_alloc
+.Fa "struct regset *regs"
+.Fa "void *data"
+.Fa "mandocmsg msgs"
+.Fc
+.Ft int
+.Fn man_endparse "struct man *man"
.Ft void
.Fn man_free "struct man *man"
-.Ft int
-.Fn man_parseln "struct man *man" "int line" "char *buf"
-.Ft "const struct man_node *"
-.Fn man_node "const struct man *man"
.Ft "const struct man_meta *"
.Fn man_meta "const struct man *man"
+.Ft "const struct man_node *"
+.Fn man_node "const struct man *man"
.Ft int
-.Fn man_endparse "struct man *man"
-.
-.
+.Fo man_parseln
+.Fa "struct man *man"
+.Fa "int line"
+.Fa "char *buf"
+.Fc
+.Ft void
+.Fn man_reset "struct man *man"
.Sh DESCRIPTION
The
.Nm
library parses lines of
.Xr man 7
-input (and
-.Em only
-man) into an abstract syntax tree (AST).
-.
+input into an abstract syntax tree (AST).
.Pp
In general, applications initiate a parsing sequence with
.Fn man_alloc ,
The
.Fn man_reset
function may be used in order to reset the parser for another input
-sequence. See the
-.Sx EXAMPLES
-section for a full example.
-.
+sequence.
.Pp
Beyond the full set of macros defined in
.Xr man 7 ,
the
.Nm
-library also accepts the following macros:
-.
+library also accepts the following macro:
.Pp
.Bl -tag -width Ds -compact
-.It am
-.It ami
-.It de
-.It dei
-.It ig
-Instructional macros in the original roff language. Blocks begun by
-these macros end with
-.Sq ..
-and may begin anywhere, although they may not break the next-line
-scoping rules specified in
-.Xr man 7 .
-These blocks are discarded.
-.
.It PD
-Has no effect. Handled as a current-scope line macro.
-.
-.It Sp
-A synonym for
-.Sq sp 0.5v
-.Pq part of the standard preamble for Perl documentation .
-Handled as a line macro.
-.
-.It UC
-Has no effect. Handled as a current-scope line macro.
-.
-.It Vb
-A synonym for
-.Sq nf
-.Pq part of the standard preamble for Perl documentation .
-Handled as a current-scope line macro.
-.
-.It Ve
-A synonym for
-.Sq fi ,
-closing
-.Sq Vb
-.Pq part of the standard preamble for Perl documentation .
+Has no effect.
Handled as a current-scope line macro.
.El
-.Pp
-Furthermore, the following escapes are accepted to allow
-.Xr pod2man 1
-documents to be correctly formatted:
-\e*(-- (dash),
-\e*(PI (pi),
-\e*(L" (left double-quote),
-\e*(R" (right double-quote),
-\e*(C+ (C++),
-\e*(C` (left single-quote),
-\e*(C' (right single-quote),
-\e*(Aq (apostrophe),
-\e*^ (hat),
-\e*, (comma),
-\e*~ (tilde),
-\e*/ (forward slash),
-\e*: (umlaut),
-\e*8 (beta),
-\e*o (degree),
-\e*(D- (Eth),
-\e*(d- (eth),
-\e*(Th (Thorn),
-and
-\e*(th (thorn).
-.
-.
-.Sh REFERENCE
-This section further defines the
-.Sx Types ,
-.Sx Functions
-and
-.Sx Variables
-available to programmers. Following that, the
-.Sx Abstract Syntax Tree
-section documents the output tree.
-.
-.
.Ss Types
-Both functions (see
-.Sx Functions )
-and variables (see
-.Sx Variables )
-may use the following types:
.Bl -ohang
-.
.It Vt struct man
-An opaque type defined in
-.Pa man.c .
+An opaque type.
Its values are only used privately within the library.
-.
-.It Vt struct man_cb
-A set of message callbacks defined in
-.Pa man.h .
-.
.It Vt struct man_node
-A parsed node. Defined in
-.Pa man.h .
+A parsed node.
See
.Sx Abstract Syntax Tree
for details.
.El
-.
-.
.Ss Functions
-Function descriptions follow:
+If
+.Fn man_addspan ,
+.Fn man_parseln ,
+or
+.Fn man_endparse
+return 0, calls to any function but
+.Fn man_reset
+or
+.Fn man_free
+will raise an assertion.
.Bl -ohang
-.
+.It Fn man_addspan
+Add a table span to the parsing stream.
+Returns 0 on failure, 1 on success.
.It Fn man_alloc
-Allocates a parsing structure. The
-.Fa data
-pointer is passed to callbacks in
-.Fa cb ,
-which are documented further in the header file.
+Allocates a parsing structure.
The
-.Fa pflags
-arguments are defined in
-.Pa man.h .
-Returns NULL on failure. If non-NULL, the pointer must be freed with
+.Fa data
+pointer is passed to
+.Fa msgs .
+Always returns a valid pointer.
+The pointer must be freed with
.Fn man_free .
-.
.It Fn man_reset
-Reset the parser for another parse routine. After its use,
+Reset the parser for another parse routine.
+After its use,
.Fn man_parseln
behaves as if invoked for the first time.
-.
.It Fn man_free
-Free all resources of a parser. The pointer is no longer valid after
-invocation.
-.
+Free all resources of a parser.
+The pointer is no longer valid after invocation.
.It Fn man_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
+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
.Fa buf
is modified by this function.
-.
.It Fn man_endparse
-Signals that the parse is complete. Note that if
-.Fn man_endparse
-is called subsequent to
-.Fn man_node ,
-the resulting tree is incomplete. Returns 0 on failure, 1 on success.
-.
+Signals that the parse is complete.
+Returns 0 on failure, 1 on success.
.It Fn man_node
-Returns the first node of the parse. Note that if
-.Fn man_parseln
-or
-.Fn man_endparse
-return 0, the tree will be incomplete.
+Returns the first node of the parse.
.It Fn man_meta
-Returns the document's parsed meta-data. If this information has not
-yet been supplied or
-.Fn man_parseln
-or
-.Fn man_endparse
-return 0, the data will be incomplete.
+Returns the document's parsed meta-data.
.El
-.
-.
.Ss Variables
The following variables are also defined:
.Bl -ohang
-.
.It Va man_macronames
An array of string-ified token names.
.El
-.
-.
.Ss Abstract Syntax Tree
The
.Nm
functions produce an abstract syntax tree (AST) describing input in a
-regular form. It may be reviewed at any time with
+regular form.
+It may be reviewed at any time with
.Fn man_nodes ;
however, if called before
.Fn man_endparse ,
or
.Fn man_parseln
fail, it may be incomplete.
-.
.Pp
-This AST is governed by the ontological
-rules dictated in
+This AST is governed by the ontological rules dictated in
.Xr man 7
and derives its terminology accordingly.
-.
.Pp
The AST is composed of
.Vt struct man_node
-nodes with element, root and text types as declared
-by the
+nodes with element, root and text types as declared by the
.Va type
-field. Each node also provides its parse point (the
+field.
+Each node also provides its parse point (the
.Va line ,
.Va sec ,
and
and
.Va prev
fields) and some type-specific data.
-.
.Pp
The tree itself is arranged according to the following normal form,
where capitalised non-terminals represent nodes.
.It TEXT
\(<- [[:alpha:]]*
.El
-.
.Pp
The only elements capable of nesting other elements are those with
next-lint scope as documented in
.Xr man 7 .
-.
-.
.Sh EXAMPLES
The following example reads lines from stdin and parses them, operating
on the finished parse tree with
.Fn parsed .
This example does not error-check nor free memory upon failure.
.Bd -literal -offset indent
+struct regset regs;
struct man *man;
struct man_node *node;
char *buf;
size_t len;
int line;
+bzero(®s, sizeof(struct regset));
line = 1;
-man = man_alloc(NULL, 0, NULL);
+man = man_alloc(®s, NULL, NULL);
buf = NULL;
alloc_len = 0;
parsed(man, node);
man_free(man);
.Ed
-.
-.
+.Pp
+To compile this, execute
+.Pp
+.Dl % cc main.c libman.a libmandoc.a
+.Pp
+where
+.Pa main.c
+is the example file.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr man 7
-.
-.
.Sh AUTHORS
The
.Nm
-utility was written by
+library was written by
.An Kristaps Dzonsons Aq kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blobdiff