version 1.3, 2009/01/17 16:15:27 |
version 1.5, 2009/01/20 15:05:01 |
|
|
.Nm mdoc_alloc , |
.Nm mdoc_alloc , |
.Nm mdoc_parseln , |
.Nm mdoc_parseln , |
.Nm mdoc_endparse , |
.Nm mdoc_endparse , |
.Nm mdoc_result , |
.Nm mdoc_node , |
|
.Nm mdoc_meta , |
.Nm mdoc_free |
.Nm mdoc_free |
.Nd mdoc macro compiler library |
.Nd mdoc macro compiler library |
.\" |
.\" |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In mdoc.h |
.Fd #include <mdoc.h> |
|
.Vt extern const char * const * mdoc_macronames; |
|
.Vt extern const char * const * mdoc_argnames; |
.Ft "struct mdoc *" |
.Ft "struct mdoc *" |
.Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb" |
.Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb" |
.Ft void |
.Ft void |
|
|
.Ft int |
.Ft int |
.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf" |
.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf" |
.Ft "const struct mdoc_node *" |
.Ft "const struct mdoc_node *" |
.Fn mdoc_result "struct mdoc *mdoc" |
.Fn mdoc_node "struct mdoc *mdoc" |
|
.Ft "const struct mdoc_meta *" |
|
.Fn mdoc_meta "struct mdoc *mdoc" |
.Ft int |
.Ft int |
.Fn mdoc_endparse "struct mdoc *mdoc" |
.Fn mdoc_endparse "struct mdoc *mdoc" |
.\" |
.\" |
Line 35 parse each line in a document with |
|
Line 40 parse each line in a document with |
|
close the parsing session with |
close the parsing session with |
.Fn mdoc_endparse , |
.Fn mdoc_endparse , |
operate over the syntax tree returned by |
operate over the syntax tree returned by |
.Fn mdoc_result , |
.Fn mdoc_node |
|
and |
|
.Fn mdoc_meta , |
then free all allocated memory with |
then free all allocated memory with |
.Fn mdoc_free . |
.Fn mdoc_free . |
See the |
See the |
.Sx EXAMPLES |
.Sx EXAMPLES |
section for a full example. |
section for a full example. |
.Pp |
.Pp |
|
.\" Function descriptions. |
Function descriptions follow: |
Function descriptions follow: |
.Bl -ohang -offset indent |
.Bl -ohang -offset indent |
.It Fn mdoc_alloc |
.It Fn mdoc_alloc |
Line 64 is modified by this function. |
|
Line 72 is modified by this function. |
|
Signals that the parse is complete. Note that if |
Signals that the parse is complete. Note that if |
.Fn mdoc_endparse |
.Fn mdoc_endparse |
is called subsequent to |
is called subsequent to |
.Fn mdoc_result , |
.Fn mdoc_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 mdoc_result |
.It Fn mdoc_node |
Returns the result of the parse or NULL on failure. Note that if |
Returns the first node of the parse. Note that if |
.Fn mdoc_parseln |
.Fn mdoc_parseln |
or |
or |
.Fn mdoc_endparse |
.Fn mdoc_endparse |
return 0, the tree will be incomplete. |
return 0, the tree will be incomplete. |
|
.It Fn mdoc_meta |
|
Returns the document's parsed meta-data. If this information has not |
|
yet been supplied or |
|
.Fn mdoc_parseln |
|
or |
|
.Fn mdoc_endparse |
|
return 0, the data will be incomplete. |
.El |
.El |
.Pp |
.Pp |
|
.\" Variable descriptions. |
|
The following variables are also defined: |
|
.Bl -ohang -offset indent |
|
.It Va mdoc_macronames |
|
An array of string-ified token names. |
|
.It Va mdoc_argnames |
|
An array of string-ified token argument names. |
|
.El |
|
.Pp |
.Nm |
.Nm |
is |
is |
.Ud |
.Ud |
Line 105 while ((buf = fgetln(fp, &len))) { |
|
Line 129 while ((buf = fgetln(fp, &len))) { |
|
|
|
if ( ! mdoc_endparse(mdoc)) |
if ( ! mdoc_endparse(mdoc)) |
errx(1, "mdoc_endparse"); |
errx(1, "mdoc_endparse"); |
if (NULL == (node = mdoc_result(mdoc))) |
if (NULL == (node = mdoc_node(mdoc))) |
errx(1, "mdoc_result"); |
errx(1, "mdoc_node"); |
|
|
parsed(mdoc, node); |
parsed(mdoc, node); |
mdoc_free(mdoc); |
mdoc_free(mdoc); |
Line 127 utility was written by |
|
Line 151 utility was written by |
|
.\" |
.\" |
.\" |
.\" |
.Sh BUGS |
.Sh BUGS |
Both bugs and incompabilities are documented in this section. An |
Bugs, un-implemented macros and incompabilities are documented in this |
incompatible macro or behaviour is relative to the default |
section. The baseline for determining whether macro parsing is |
|
.Qq incompatible |
|
is the default |
.Xr groff 1 |
.Xr groff 1 |
system bundled with |
system bundled with |
.Ox . |
.Ox . |
.Pp |
.Pp |
The |
Un-implemented: the |
.Sq \&Xc |
.Sq \&Xc |
and |
and |
.Sq \&Xo |
.Sq \&Xo |
Line 142 macros aren't handled when used to span lines for the |
|
Line 168 macros aren't handled when used to span lines for the |
|
macro. Such usage is specifically discouraged in |
macro. Such usage is specifically discouraged in |
.Xr mdoc.samples 7 . |
.Xr mdoc.samples 7 . |
.Pp |
.Pp |
When |
Bugs: when |
.Sq \&It \-column |
.Sq \&It \-column |
is invoked, whitespace is not stripped around |
is invoked, whitespace is not stripped around |
.Sq \&Ta |
.Sq \&Ta |
or tab-character separators. |
or tab-character separators. |
.Pp |
.Pp |
The |
Incompatible: the |
.Sq \&At |
.Sq \&At |
macro only accepts a single parameter. |
macro only accepts a single parameter. Furthermore, several macros |
|
.Pf ( Sq \&Pp , |
|
.Sq \&It , |
|
and possibly others) accept multiple arguments with a warning. |
|
.Pp |
|
Incompatible: only those macros specified by |
|
.Xr mdoc.samples 7 |
|
and |
|
.Xr mdoc 7 |
|
for |
|
.Ox |
|
are supported; support for |
|
.Nx |
|
and other BSD systems is in progress. |