-.\" $Id: man.3,v 1.12 2010/02/17 19:22:01 kristaps Exp $
+.\" $Id: man.3,v 1.16 2010/04/13 05:26:49 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: February 17 2010 $
+.Dd $Mdocdate: April 13 2010 $
.Dt MAN 3
.Os
-.\" SECTION
.Sh NAME
+.Nm man ,
.Nm man_alloc ,
.Nm man_parseln ,
.Nm man_endparse ,
.Nm man_free ,
.Nm man_reset
.Nd man macro compiler library
-.\" SECTION
.Sh SYNOPSIS
.In man.h
.Vt extern const char * const * man_macronames;
.Fn man_meta "const struct man *man"
.Ft int
.Fn man_endparse "struct man *man"
-.\" SECTION
.Sh DESCRIPTION
The
-.Nm man
+.Nm
library parses lines of
.Xr man 7
input (and
.Em only
man) into an abstract syntax tree (AST).
-.\" PARAGRAPH
.Pp
In general, applications initiate a parsing sequence with
.Fn man_alloc ,
sequence. See the
.Sx EXAMPLES
section for a full example.
-.\" PARAGRAPH
.Pp
+Beyond the full set of macros defined in
+.Xr man 7 ,
+the
+.Nm
+library also accepts the following macros:
+.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 .
+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
available to programmers. Following that, the
.Sx Abstract Syntax Tree
section documents the output tree.
-.\" SUBSECTION
.Ss Types
Both functions (see
.Sx Functions )
.Sx Variables )
may use the following types:
.Bl -ohang
-.\" LIST-ITEM
.It Vt struct man
An opaque type defined in
.Pa man.c .
Its values are only used privately within the library.
-.\" LIST-ITEM
.It Vt struct man_cb
A set of message callbacks defined in
.Pa man.h .
-.\" LIST-ITEM
.It Vt struct man_node
A parsed node. Defined in
.Pa man.h .
.Sx Abstract Syntax Tree
for details.
.El
-.\" SUBSECTION
.Ss Functions
Function descriptions follow:
.Bl -ohang
-.\" LIST-ITEM
.It Fn man_alloc
Allocates a parsing structure. The
.Fa data
.Pa man.h .
Returns NULL on failure. If non-NULL, the pointer must be freed with
.Fn man_free .
-.\" LIST-ITEM
.It Fn man_reset
Reset the parser for another parse routine. After its use,
.Fn man_parseln
behaves as if invoked for the first time.
-.\" LIST-ITEM
.It Fn man_free
Free all resources of a parser. The pointer is no longer valid after
invocation.
-.\" LIST-ITEM
.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
.Fa buf
is modified by this function.
-.\" LIST-ITEM
.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.
-.\" LIST-ITEM
.It Fn man_node
Returns the first node of the parse. Note that if
.Fn man_parseln
.Fn man_endparse
return 0, the data will be incomplete.
.El
-.\" SUBSECTION
.Ss Variables
The following variables are also defined:
.Bl -ohang
-.\" LIST-ITEM
.It Va man_macronames
An array of string-ified token names.
.El
-.\" SUBSECTION
.Ss Abstract Syntax Tree
The
.Nm
or
.Fn man_parseln
fail, it may be incomplete.
-.\" PARAGRAPH
.Pp
This AST is governed by the ontological
rules dictated in
.Xr man 7
and derives its terminology accordingly.
-.\" PARAGRAPH
.Pp
The AST is composed of
.Vt struct man_node
and
.Va prev
fields) and some type-specific data.
-.\" PARAGRAPH
.Pp
The tree itself is arranged according to the following normal form,
where capitalised non-terminals represent nodes.
.Pp
.Bl -tag -width "ELEMENTXX" -compact
-.\" LIST-ITEM
.It ROOT
\(<- mnode+
.It mnode
.It TEXT
\(<- [[:alpha:]]*
.El
-.\" PARAGRAPH
.Pp
The only elements capable of nesting other elements are those with
next-lint scope as documented in
.Xr man 7 .
-.\" SECTION
.Sh EXAMPLES
The following example reads lines from stdin and parses them, operating
on the finished parse tree with
parsed(man, node);
man_free(man);
.Ed
-.\" SECTION
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr man 7
-.\" SECTION
.Sh AUTHORS
The
.Nm
git.ckatri.com / mandoc.git / blobdiff