version 1.4, 2011/04/19 16:30:00 |
version 1.17, 2012/01/13 15:27:14 |
|
|
.Nm mandoc , |
.Nm mandoc , |
.Nm mandoc_escape , |
.Nm mandoc_escape , |
.Nm man_meta , |
.Nm man_meta , |
|
.Nm man_mparse , |
.Nm man_node , |
.Nm man_node , |
|
.Nm mchars_alloc , |
|
.Nm mchars_free , |
|
.Nm mchars_num2char , |
|
.Nm mchars_num2uc , |
|
.Nm mchars_spec2cp , |
|
.Nm mchars_spec2str , |
.Nm mdoc_meta , |
.Nm mdoc_meta , |
.Nm mdoc_node , |
.Nm mdoc_node , |
.Nm mparse_alloc , |
.Nm mparse_alloc , |
.Nm mparse_free , |
.Nm mparse_free , |
|
.Nm mparse_getkeep , |
|
.Nm mparse_keep , |
.Nm mparse_readfd , |
.Nm mparse_readfd , |
.Nm mparse_reset , |
.Nm mparse_reset , |
.Nm mparse_result , |
.Nm mparse_result , |
.Nm mparse_strerror , |
.Nm mparse_strerror , |
.Nm mparse_strlevel |
.Nm mparse_strlevel |
.Nd mandoc macro compiler library |
.Nd mandoc macro compiler library |
|
.Sh LIBRARY |
|
.Lb mandoc |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In man.h |
.In man.h |
.In mdoc.h |
.In mdoc.h |
.In mandoc.h |
.In mandoc.h |
.Ft "enum mandoc_esc" |
.Ft "enum mandoc_esc" |
.Fo mandoc_escape |
.Fo mandoc_escape |
.Fa "const char **in" |
.Fa "const char **end" |
.Fa "const char **seq" |
.Fa "const char **start" |
.Fa "int *len" |
.Fa "int *sz" |
.Fc |
.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" |
.Fc |
.Fc |
|
.Ft "const struct mparse *" |
|
.Fo man_mparse |
|
.Fa "const struct man *man" |
|
.Fc |
.Ft "const struct man_node *" |
.Ft "const struct man_node *" |
.Fo man_node |
.Fo man_node |
.Fa "const struct man *man" |
.Fa "const struct man *man" |
.Fc |
.Fc |
|
.Ft "struct mchars *" |
|
.Fn mchars_alloc |
|
.Ft void |
|
.Fn mchars_free "struct mchars *p" |
|
.Ft char |
|
.Fn mchars_num2char "const char *cp" "size_t sz" |
|
.Ft int |
|
.Fn mchars_num2uc "const char *cp" "size_t sz" |
|
.Ft "const char *" |
|
.Fo mchars_spec2str |
|
.Fa "const struct mchars *p" |
|
.Fa "const char *cp" |
|
.Fa "size_t sz" |
|
.Fa "size_t *rsz" |
|
.Fc |
|
.Ft int |
|
.Fo mchars_spec2cp |
|
.Fa "const struct mchars *p" |
|
.Fa "const char *cp" |
|
.Fa "size_t sz" |
|
.Ft "const char *" |
|
.Fc |
.Ft "const struct mdoc_meta *" |
.Ft "const struct mdoc_meta *" |
.Fo mdoc_meta |
.Fo mdoc_meta |
.Fa "const struct mdoc *mdoc" |
.Fa "const struct mdoc *mdoc" |
|
|
.Fo mparse_free |
.Fo mparse_free |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fc |
.Fc |
|
.Ft void |
|
.Fo mparse_getkeep |
|
.Fa "const struct mparse *parse" |
|
.Fc |
|
.Ft void |
|
.Fo mparse_keep |
|
.Fa "struct mparse *parse" |
|
.Fc |
.Ft "enum mandoclevel" |
.Ft "enum mandoclevel" |
.Fo mparse_readfd |
.Fo mparse_readfd |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
|
|
.Fn mparse_reset |
.Fn mparse_reset |
and parse new files. |
and parse new files. |
.El |
.El |
|
.Pp |
|
The |
|
.Nm |
|
library also contains routines for translating character strings into glyphs |
|
.Pq see Fn mchars_alloc |
|
and parsing escape sequences from strings |
|
.Pq see Fn mandoc_escape . |
.Sh REFERENCE |
.Sh REFERENCE |
This section documents the functions, types, and variables available |
This section documents the functions, types, and variables available |
via |
via |
|
|
.Ss Types |
.Ss Types |
.Bl -ohang |
.Bl -ohang |
.It Vt "enum mandoc_esc" |
.It Vt "enum mandoc_esc" |
|
An escape sequence classification. |
.It Vt "enum mandocerr" |
.It Vt "enum mandocerr" |
|
A fatal error, error, or warning message during parsing. |
.It Vt "enum mandoclevel" |
.It Vt "enum mandoclevel" |
|
A classification of an |
|
.Vt "enum mandoclevel" |
|
as regards system operation. |
|
.It Vt "struct mchars" |
|
An opaque pointer to an object allowing for translation between |
|
character strings and glyphs. |
|
See |
|
.Fn mchars_alloc . |
.It Vt "enum mparset" |
.It Vt "enum mparset" |
|
The type of parser when reading input. |
|
This should usually be |
|
.Dv MPARSE_AUTO |
|
for auto-detection. |
.It Vt "struct mparse" |
.It Vt "struct mparse" |
|
An opaque pointer to a running parse sequence. |
|
Created with |
|
.Fn mparse_alloc |
|
and freed with |
|
.Fn mparse_free . |
|
This may be used across parsed input if |
|
.Fn mparse_reset |
|
is called between parses. |
.It Vt "mandocmsg" |
.It Vt "mandocmsg" |
|
A prototype for a function to handle fatal error, error, and warning |
|
messages emitted by the parser. |
.El |
.El |
.Ss Functions |
.Ss Functions |
.Bl -ohang |
.Bl -ohang |
.It Fn mandoc_escape |
.It Fn mandoc_escape |
Scan an escape sequence, i.e., a character string beginning with |
Scan an escape sequence, i.e., a character string beginning with |
.Sq \e . |
.Sq \e . |
Pass a pointer to this string as |
Pass a pointer to the character after the |
|
.Sq \e |
|
as |
.Va end ; |
.Va end ; |
it will be set to the supremum of the parsed escape sequence unless |
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 |
returning |
|
.Dv ESCAPE_ERROR , |
|
in which case the string is bogus and should be |
thrown away. |
thrown away. |
If not ESCAPE_ERROR or ESCAPE_IGNORE, |
If not |
|
.Dv ESCAPE_ERROR |
|
or |
|
.Dv ESCAPE_IGNORE , |
.Va start |
.Va start |
is set to the first relevant character of the substring (font, glyph, |
is set to the first relevant character of the substring (font, glyph, |
whatever) of length |
whatever) of length |
|
|
.Va start |
.Va start |
and |
and |
.Va sz |
.Va sz |
may be NULL. |
may be |
|
.Dv NULL . |
.It Fn man_meta |
.It Fn man_meta |
Obtain the meta-data of a successful parse. |
Obtain the meta-data of a successful parse. |
This may only be used on a pointer returned by |
This may only be used on a pointer returned by |
.Fn mparse_result . |
.Fn mparse_result . |
|
.It Fn man_mparse |
|
Get the parser used for the current output. |
.It Fn man_node |
.It Fn man_node |
Obtain the root node of a successful parse. |
Obtain the root node of a successful parse. |
This may only be used on a pointer returned by |
This may only be used on a pointer returned by |
.Fn mparse_result . |
.Fn mparse_result . |
|
.It Fn mchars_alloc |
|
Allocate an |
|
.Vt "struct mchars *" |
|
object for translating special characters into glyphs. |
|
See |
|
.Xr mandoc_char 7 |
|
for an overview of special characters. |
|
The object must be freed with |
|
.Fn mchars_free . |
|
.It Fn mchars_free |
|
Free an object created with |
|
.Fn mchars_alloc . |
|
.It Fn mchars_num2char |
|
Convert a character index (e.g., the \eN\(aq\(aq escape) into a |
|
printable ASCII character. |
|
Returns \e0 (the nil character) if the input sequence is malformed. |
|
.It Fn mchars_num2uc |
|
Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into |
|
a Unicode codepoint. |
|
Returns \e0 (the nil character) if the input sequence is malformed. |
|
.It Fn mchars_spec2cp |
|
Convert a special character into a valid Unicode codepoint. |
|
Returns \-1 on failure or a non-zero Unicode codepoint on success. |
|
.It Fn mchars_spec2str |
|
Convert a special character into an ASCII string. |
|
Returns |
|
.Dv NULL |
|
on failure. |
.It Fn mdoc_meta |
.It Fn mdoc_meta |
Obtain the meta-data of a successful parse. |
Obtain the meta-data of a successful parse. |
This may only be used on a pointer returned by |
This may only be used on a pointer returned by |
Line 199 must be called to free the memory allocated by this fu |
|
Line 313 must be called to free the memory allocated by this fu |
|
.It Fn mparse_free |
.It Fn mparse_free |
Free all memory allocated by |
Free all memory allocated by |
.Fn mparse_alloc . |
.Fn mparse_alloc . |
|
.It Fn mparse_getkeep |
|
Acquire the keep buffer. |
|
Must follow a call of |
|
.Fn mparse_keep . |
|
.It Fn mparse_keep |
|
Instruct the parser to retain a copy of its parsed input. |
|
This can be acquired with subsequent |
|
.Fn mparse_getkeep |
|
calls. |
.It Fn mparse_readfd |
.It Fn mparse_readfd |
Parse a file or file descriptor. |
Parse a file or file descriptor. |
If |
If |
Line 249 This section consists of structural documentation for |
|
Line 372 This section consists of structural documentation for |
|
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr man 7 |
.Xr man 7 |
syntax trees. |
syntax trees and strings. |
|
.Ss Man and Mdoc Strings |
|
Strings may be extracted from mdoc and man meta-data, or from text |
|
nodes (MDOC_TEXT and MAN_TEXT, respectively). |
|
These strings have special non-printing formatting cues embedded in the |
|
text itself, as well as |
|
.Xr roff 7 |
|
escapes preserved from input. |
|
Implementing systems will need to handle both situations to produce |
|
human-readable text. |
|
In general, strings may be assumed to consist of 7-bit ASCII characters. |
|
.Pp |
|
The following non-printing characters may be embedded in text strings: |
|
.Bl -tag -width Ds |
|
.It Dv ASCII_NBRSP |
|
A non-breaking space character. |
|
.It Dv ASCII_HYPH |
|
A soft hyphen. |
|
.El |
|
.Pp |
|
Escape characters are also passed verbatim into text strings. |
|
An escape character is a sequence of characters beginning with the |
|
backslash |
|
.Pq Sq \e . |
|
To construct human-readable text, these should be intercepted with |
|
.Fn mandoc_escape |
|
and converted with one of |
|
.Fn mchars_num2char , |
|
.Fn mchars_spec2str , |
|
and so on. |
.Ss Man Abstract Syntax Tree |
.Ss Man Abstract Syntax Tree |
This AST is governed by the ontological rules dictated in |
This AST is governed by the ontological rules dictated in |
.Xr man 7 |
.Xr man 7 |
Line 290 where capitalised non-terminals represent nodes. |
|
Line 442 where capitalised non-terminals represent nodes. |
|
.It ELEMENT |
.It ELEMENT |
\(<- ELEMENT | TEXT* |
\(<- ELEMENT | TEXT* |
.It TEXT |
.It TEXT |
\(<- [[:alpha:]]* |
\(<- [[:ascii:]]* |
.El |
.El |
.Pp |
.Pp |
The only elements capable of nesting other elements are those with |
The only elements capable of nesting other elements are those with |
Line 349 where capitalised non-terminals represent nodes. |
|
Line 501 where capitalised non-terminals represent nodes. |
|
.It TAIL |
.It TAIL |
\(<- mnode* |
\(<- mnode* |
.It TEXT |
.It TEXT |
\(<- [[:printable:],0x1e]* |
\(<- [[:ascii:]]* |
.El |
.El |
.Pp |
.Pp |
Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of |
Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of |
Line 364 where a new body introduces a new phrase. |
|
Line 516 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 |
Line 436 levels of badly-nested blocks. |
|
Line 588 levels of badly-nested blocks. |
|
.Xr mandoc 1 , |
.Xr mandoc 1 , |
.Xr eqn 7 , |
.Xr eqn 7 , |
.Xr man 7 , |
.Xr man 7 , |
|
.Xr mandoc_char 7 , |
.Xr mdoc 7 , |
.Xr mdoc 7 , |
.Xr roff 7 , |
.Xr roff 7 , |
.Xr tbl 7 |
.Xr tbl 7 |
Line 443 levels of badly-nested blocks. |
|
Line 596 levels of badly-nested blocks. |
|
The |
The |
.Nm |
.Nm |
library was written by |
library was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons , |
|
.Mt kristaps@bsd.lv . |