version 1.2, 2011/03/28 21:49:42 |
version 1.5, 2011/04/30 10:18:24 |
|
|
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm mandoc , |
.Nm mandoc , |
|
.Nm mandoc_escape , |
.Nm man_meta , |
.Nm man_meta , |
.Nm man_node , |
.Nm man_node , |
.Nm mdoc_meta , |
.Nm mdoc_meta , |
|
|
.In man.h |
.In man.h |
.In mdoc.h |
.In mdoc.h |
.In mandoc.h |
.In mandoc.h |
|
.Ft "enum mandoc_esc" |
|
.Fo mandoc_escape |
|
.Fa "const char **in" |
|
.Fa "const char **seq" |
|
.Fa "int *len" |
|
.Fc |
.Ft "const struct man_meta *" |
.Ft "const struct man_meta *" |
.Fo man_meta |
.Fo man_meta |
.Fa "const struct man *man" |
.Fa "const struct man *man" |
|
|
.Vt extern const char * const * man_macronames; |
.Vt extern const char * const * man_macronames; |
.Vt extern const char * const * mdoc_argnames; |
.Vt extern const char * const * mdoc_argnames; |
.Vt extern const char * const * mdoc_macronames; |
.Vt extern const char * const * mdoc_macronames; |
|
.Fd "#define ASCII_NBRSP" |
|
.Fd "#define ASCII_HYPH" |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm mandoc |
.Nm mandoc |
|
|
.Fn mparse_reset |
.Fn mparse_reset |
and parse new files. |
and parse new files. |
.El |
.El |
|
.Sh REFERENCE |
|
This section documents the functions, types, and variables available |
|
via |
|
.In mandoc.h . |
|
.Ss Types |
|
.Bl -ohang |
|
.It Vt "enum mandoc_esc" |
|
.It Vt "enum mandocerr" |
|
.It Vt "enum mandoclevel" |
|
.It Vt "enum mparset" |
|
.It Vt "struct mparse" |
|
.It Vt "mandocmsg" |
|
.El |
|
.Ss Functions |
|
.Bl -ohang |
|
.It Fn mandoc_escape |
|
Scan an escape sequence, i.e., a character string beginning with |
|
.Sq \e . |
|
Pass a pointer to this string as |
|
.Va end ; |
|
it will be set to the supremum of the parsed escape sequence unless |
|
returning ESCAPE_ERROR, in which case the string is bogus and should be |
|
thrown away. |
|
If not ESCAPE_ERROR or ESCAPE_IGNORE, |
|
.Va start |
|
is set to the first relevant character of the substring (font, glyph, |
|
whatever) of length |
|
.Va sz . |
|
Both |
|
.Va start |
|
and |
|
.Va sz |
|
may be NULL. |
|
.It Fn man_meta |
|
Obtain the meta-data of a successful parse. |
|
This may only be used on a pointer returned by |
|
.Fn mparse_result . |
|
.It Fn man_node |
|
Obtain the root node of a successful parse. |
|
This may only be used on a pointer returned by |
|
.Fn mparse_result . |
|
.It Fn mdoc_meta |
|
Obtain the meta-data of a successful parse. |
|
This may only be used on a pointer returned by |
|
.Fn mparse_result . |
|
.It Fn mdoc_node |
|
Obtain the root node of a successful parse. |
|
This may only be used on a pointer returned by |
|
.Fn mparse_result . |
|
.It Fn mparse_alloc |
|
Allocate a parser. |
|
The same parser may be used for multiple files so long as |
|
.Fn mparse_reset |
|
is called between parses. |
|
.Fn mparse_free |
|
must be called to free the memory allocated by this function. |
|
.It Fn mparse_free |
|
Free all memory allocated by |
|
.Fn mparse_alloc . |
|
.It Fn mparse_readfd |
|
Parse a file or file descriptor. |
|
If |
|
.Va fd |
|
is -1, |
|
.Va fname |
|
is opened for reading. |
|
Otherwise, |
|
.Va fname |
|
is assumed to be the name associated with |
|
.Va fd . |
|
This may be called multiple times with different parameters; however, |
|
.Fn mparse_reset |
|
should be invoked between parses. |
|
.It Fn mparse_reset |
|
Reset a parser so that |
|
.Fn mparse_readfd |
|
may be used again. |
|
.It Fn mparse_result |
|
Obtain the result of a parse. |
|
Only successful parses |
|
.Po |
|
i.e., those where |
|
.Fn mparse_readfd |
|
returned less than MANDOCLEVEL_FATAL |
|
.Pc |
|
should invoke this function, in which case one of the two pointers will |
|
be filled in. |
|
.It Fn mparse_strerror |
|
Return a statically-allocated string representation of an error code. |
|
.It Fn mparse_strlevel |
|
Return a statically-allocated string representation of a level code. |
|
.El |
|
.Ss Variables |
|
.Bl -ohang |
|
.It Va man_macronames |
|
The string representation of a man macro as indexed by |
|
.Vt "enum mant" . |
|
.It Va mdoc_argnames |
|
The string representation of a mdoc macro argument as indexed by |
|
.Vt "enum mdocargt" . |
|
.It Va mdoc_macronames |
|
The string representation of a mdoc macro as indexed by |
|
.Vt "enum mdoct" . |
|
.El |
.Sh IMPLEMENTATION NOTES |
.Sh IMPLEMENTATION NOTES |
This section consists of structural documentation for |
This section consists of structural documentation for |
.Xr mdoc 7 |
.Xr mdoc 7 |
Line 251 where a new body introduces a new phrase. |
|
Line 364 where a new body introduces a new phrase. |
|
.Pp |
.Pp |
The |
The |
.Xr mdoc 7 |
.Xr mdoc 7 |
syntax tree accomodates for broken block structures as well. |
syntax tree accommodates for broken block structures as well. |
The ENDBODY node is available to end the formatting associated |
The ENDBODY node is available to end the formatting associated |
with a given block before the physical end of that block. |
with a given block before the physical end of that block. |
It has a non-null |
It has a non-null |