Return to man.3 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.16, 2010/04/13 05:26:49 | version 1.17, 2010/05/25 21:46:48 | ||
---|---|---|---|
|
|
||
.Sh NAME | .Sh NAME | ||
.Nm man , | .Nm man , | ||
.Nm man_alloc , | .Nm man_alloc , | ||
.Nm man_parseln , | |||
.Nm man_endparse , | .Nm man_endparse , | ||
.Nm man_node , | |||
.Nm man_meta , | |||
.Nm man_free , | .Nm man_free , | ||
.Nm man_meta , | |||
.Nm man_node , | |||
.Nm man_parseln , | |||
.Nm man_reset | .Nm man_reset | ||
.Nd man macro compiler library | .Nd man macro compiler library | ||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||
.In mandoc.h | |||
.In man.h | .In man.h | ||
.Vt extern const char * const * man_macronames; | .Vt extern const char * const * man_macronames; | ||
.Ft "struct man *" | .Ft "struct man *" | ||
.Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb" | .Fn man_alloc "void *data" "int pflags" "mandocmsg msgs" | ||
.Ft int | |||
.Fn man_endparse "struct man *man" | |||
.Ft void | .Ft void | ||
.Fn man_reset "struct man *man" | |||
.Ft void | |||
.Fn man_free "struct man *man" | .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 *" | .Ft "const struct man_meta *" | ||
.Fn man_meta "const struct man *man" | .Fn man_meta "const struct man *man" | ||
.Ft "const struct man_node *" | |||
.Fn man_node "const struct man *man" | |||
.Ft int | .Ft int | ||
.Fn man_endparse "struct man *man" | .Fn man_parseln "struct man *man" "int line" "char *buf" | ||
.Ft void | |||
.Fn man_reset "struct man *man" | |||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | The | ||
.Nm | .Nm | ||
library parses lines of | library parses lines of | ||
.Xr man 7 | .Xr man 7 | ||
input (and | input into an abstract syntax tree (AST). | ||
.Em only | |||
man) into an abstract syntax tree (AST). | |||
.Pp | .Pp | ||
In general, applications initiate a parsing sequence with | In general, applications initiate a parsing sequence with | ||
.Fn man_alloc , | .Fn man_alloc , | ||
|
|
||
The | The | ||
.Fn man_reset | .Fn man_reset | ||
function may be used in order to reset the parser for another input | function may be used in order to reset the parser for another input | ||
sequence. See the | sequence. | ||
See the | |||
.Sx EXAMPLES | .Sx EXAMPLES | ||
section for a full example. | section for a full example. | ||
.Pp | .Pp | ||
|
|
||
library also accepts the following macros: | library also accepts the following macros: | ||
.Pp | .Pp | ||
.Bl -tag -width Ds -compact | .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 | .It PD | ||
Has no effect. Handled as a current-scope line macro. | Has no effect. Handled as a current-scope line macro. | ||
.It Sp | .It Sp | ||
|
|
||
.Sq sp 0.5v | .Sq sp 0.5v | ||
.Pq part of the standard preamble for Perl documentation . | .Pq part of the standard preamble for Perl documentation . | ||
Handled as a line macro. | Handled as a line macro. | ||
.It UC | |||
Has no effect. Handled as a current-scope line macro. | |||
.It Vb | .It Vb | ||
A synonym for | A synonym for | ||
.Sq nf | .Sq nf | ||
|
|
||
.Sx Functions | .Sx Functions | ||
and | and | ||
.Sx Variables | .Sx Variables | ||
available to programmers. Following that, the | available to programmers. | ||
Following that, the | |||
.Sx Abstract Syntax Tree | .Sx Abstract Syntax Tree | ||
section documents the output tree. | section documents the output tree. | ||
.Ss Types | .Ss Types | ||
|
|
||
An opaque type defined in | An opaque type defined in | ||
.Pa man.c . | .Pa man.c . | ||
Its values are only used privately within the library. | Its values are only used privately within the library. | ||
.It Vt struct man_cb | .It Vt mandocmsg | ||
A set of message callbacks defined in | A function callback type defined in | ||
.Pa man.h . | .Pa mandoc.h . | ||
.It Vt struct man_node | .It Vt struct man_node | ||
A parsed node. Defined in | A parsed node. | ||
Defined in | |||
.Pa man.h . | .Pa man.h . | ||
See | See | ||
.Sx Abstract Syntax Tree | .Sx Abstract Syntax Tree | ||
|
|
||
Function descriptions follow: | Function descriptions follow: | ||
.Bl -ohang | .Bl -ohang | ||
.It Fn man_alloc | .It Fn man_alloc | ||
Allocates a parsing structure. The | Allocates a parsing structure. | ||
The | |||
.Fa data | .Fa data | ||
pointer is passed to callbacks in | pointer is passed to callbacks in | ||
.Fa cb , | .Fa cb , | ||
|
|
||
.Fa pflags | .Fa pflags | ||
arguments are defined in | arguments are defined in | ||
.Pa man.h . | .Pa man.h . | ||
Returns NULL on failure. If non-NULL, the pointer must be freed with | Returns NULL on failure. | ||
If non-NULL, the pointer must be freed with | |||
.Fn man_free . | .Fn man_free . | ||
.It Fn man_reset | .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 | .Fn man_parseln | ||
behaves as if invoked for the first time. | behaves as if invoked for the first time. | ||
.It Fn man_free | .It Fn man_free | ||
Free all resources of a parser. The pointer is no longer valid after | Free all resources of a parser. | ||
invocation. | The pointer is no longer valid after invocation. | ||
.It Fn man_parseln | .It Fn man_parseln | ||
Parse a nil-terminated line of input. This line should not contain the | Parse a nil-terminated line of input. | ||
trailing newline. Returns 0 on failure, 1 on success. The input buffer | This line should not contain the trailing newline. | ||
Returns 0 on failure, 1 on success. | |||
The input buffer | |||
.Fa buf | .Fa buf | ||
is modified by this function. | is modified by this function. | ||
.It Fn man_endparse | .It Fn man_endparse | ||
Signals that the parse is complete. Note that if | Signals that the parse is complete. | ||
Note that if | |||
.Fn man_endparse | .Fn man_endparse | ||
is called subsequent to | is called subsequent to | ||
.Fn man_node , | .Fn man_node , | ||
the resulting tree is incomplete. Returns 0 on failure, 1 on success. | the resulting tree is incomplete. | ||
Returns 0 on failure, 1 on success. | |||
.It Fn man_node | .It Fn man_node | ||
Returns the first node of the parse. Note that if | Returns the first node of the parse. | ||
Note that if | |||
.Fn man_parseln | .Fn man_parseln | ||
or | or | ||
.Fn man_endparse | .Fn man_endparse | ||
return 0, the tree will be incomplete. | return 0, the tree will be incomplete. | ||
.It Fn man_meta | .It Fn man_meta | ||
Returns the document's parsed meta-data. If this information has not | Returns the document's parsed meta-data. | ||
yet been supplied or | If this information has not yet been supplied or | ||
.Fn man_parseln | .Fn man_parseln | ||
or | or | ||
.Fn man_endparse | .Fn man_endparse | ||
|
|
||
The | The | ||
.Nm | .Nm | ||
functions produce an abstract syntax tree (AST) describing input in a | 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 ; | .Fn man_nodes ; | ||
however, if called before | however, if called before | ||
.Fn man_endparse , | .Fn man_endparse , | ||
|
|
||
.Fn man_parseln | .Fn man_parseln | ||
fail, it may be incomplete. | fail, it may be incomplete. | ||
.Pp | .Pp | ||
This AST is governed by the ontological | This AST is governed by the ontological rules dictated in | ||
rules dictated in | |||
.Xr man 7 | .Xr man 7 | ||
and derives its terminology accordingly. | and derives its terminology accordingly. | ||
.Pp | .Pp | ||
The AST is composed of | The AST is composed of | ||
.Vt struct man_node | .Vt struct man_node | ||
nodes with element, root and text types as declared | nodes with element, root and text types as declared by the | ||
by the | |||
.Va type | .Va type | ||
field. Each node also provides its parse point (the | field. | ||
Each node also provides its parse point (the | |||
.Va line , | .Va line , | ||
.Va sec , | .Va sec , | ||
and | and | ||
|
|
||
parsed(man, node); | parsed(man, node); | ||
man_free(man); | man_free(man); | ||
.Ed | .Ed | ||
.Pp | |||
Please see | |||
.Pa main.c | |||
in the source archive for a rigorous reference. | |||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr mandoc 1 , | .Xr mandoc 1 , | ||
.Xr man 7 | .Xr man 7 | ||
.Sh AUTHORS | .Sh AUTHORS | ||
The | The | ||
.Nm | .Nm | ||
utility was written by | library was written by | ||
.An Kristaps Dzonsons Aq kristaps@bsd.lv . | .An Kristaps Dzonsons Aq kristaps@bsd.lv . |