325 lines
7.1 KiB
Groff
325 lines
7.1 KiB
Groff
.\" $Id: man.3,v 1.18 2010/05/25 22:16:59 kristaps Exp $
|
|
.\"
|
|
.\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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: May 25 2010 $
|
|
.Dt MAN 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm man ,
|
|
.Nm man_alloc ,
|
|
.Nm man_endparse ,
|
|
.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 "struct man *"
|
|
.Fn man_alloc "void *data" "int pflags" "mandocmsg msgs"
|
|
.Ft int
|
|
.Fn man_endparse "struct man *man"
|
|
.Ft void
|
|
.Fn man_free "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_parseln "struct man *man" "int line" "char *buf"
|
|
.Ft void
|
|
.Fn man_reset "struct man *man"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library parses lines of
|
|
.Xr man 7
|
|
input into an abstract syntax tree (AST).
|
|
.Pp
|
|
In general, applications initiate a parsing sequence with
|
|
.Fn man_alloc ,
|
|
parse each line in a document with
|
|
.Fn man_parseln ,
|
|
close the parsing session with
|
|
.Fn man_endparse ,
|
|
operate over the syntax tree returned by
|
|
.Fn man_node
|
|
and
|
|
.Fn man_meta ,
|
|
then free all allocated memory with
|
|
.Fn man_free .
|
|
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.
|
|
.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 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 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
|
|
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 .
|
|
Its values are only used privately within the library.
|
|
.It Vt mandocmsg
|
|
A function callback type defined in
|
|
.Pa mandoc.h .
|
|
.It Vt struct man_node
|
|
A parsed node.
|
|
Defined in
|
|
.Pa man.h .
|
|
See
|
|
.Sx Abstract Syntax Tree
|
|
for details.
|
|
.El
|
|
.Ss Functions
|
|
Function descriptions follow:
|
|
.Bl -ohang
|
|
.It Fn man_alloc
|
|
Allocates a parsing structure.
|
|
The
|
|
.Fa data
|
|
pointer is passed to
|
|
.Fa msgs .
|
|
The
|
|
.Fa pflags
|
|
arguments are defined in
|
|
.Pa man.h .
|
|
Returns NULL on failure.
|
|
If non-NULL, the pointer must be freed with
|
|
.Fn man_free .
|
|
.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.
|
|
.It Fn man_free
|
|
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
|
|
.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.
|
|
.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.
|
|
.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.
|
|
.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
|
|
.Fn man_nodes ;
|
|
however, if called before
|
|
.Fn man_endparse ,
|
|
or after
|
|
.Fn man_endparse
|
|
or
|
|
.Fn man_parseln
|
|
fail, it may be incomplete.
|
|
.Pp
|
|
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
|
|
.Va type
|
|
field.
|
|
Each node also provides its parse point (the
|
|
.Va line ,
|
|
.Va sec ,
|
|
and
|
|
.Va pos
|
|
fields), its position in the tree (the
|
|
.Va parent ,
|
|
.Va child ,
|
|
.Va next
|
|
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.
|
|
.Pp
|
|
.Bl -tag -width "ELEMENTXX" -compact
|
|
.It ROOT
|
|
\(<- mnode+
|
|
.It mnode
|
|
\(<- ELEMENT | TEXT | BLOCK
|
|
.It BLOCK
|
|
\(<- HEAD BODY
|
|
.It HEAD
|
|
\(<- mnode*
|
|
.It BODY
|
|
\(<- mnode*
|
|
.It ELEMENT
|
|
\(<- ELEMENT | TEXT*
|
|
.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 man *man;
|
|
struct man_node *node;
|
|
char *buf;
|
|
size_t len;
|
|
int line;
|
|
|
|
line = 1;
|
|
man = man_alloc(NULL, 0, NULL);
|
|
buf = NULL;
|
|
alloc_len = 0;
|
|
|
|
while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
|
|
if (len && buflen[len - 1] = '\en')
|
|
buf[len - 1] = '\e0';
|
|
if ( ! man_parseln(man, line, buf))
|
|
errx(1, "man_parseln");
|
|
line++;
|
|
}
|
|
|
|
free(buf);
|
|
|
|
if ( ! man_endparse(man))
|
|
errx(1, "man_endparse");
|
|
if (NULL == (node = man_node(man)))
|
|
errx(1, "man_node");
|
|
|
|
parsed(man, node);
|
|
man_free(man);
|
|
.Ed
|
|
.Pp
|
|
Please see
|
|
.Pa main.c
|
|
in the source archive for a rigorous reference.
|
|
.Sh SEE ALSO
|
|
.Xr mandoc 1 ,
|
|
.Xr man 7
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
library was written by
|
|
.An Kristaps Dzonsons Aq kristaps@bsd.lv .
|