version 1.6, 2011/05/01 10:40:52 |
version 1.11, 2011/06/22 22:10:02 |
|
|
.Nm mchars_alloc , |
.Nm mchars_alloc , |
.Nm mchars_free , |
.Nm mchars_free , |
.Nm mchars_num2char , |
.Nm mchars_num2char , |
.Nm mchars_res2cp , |
.Nm mchars_num2uc , |
.Nm mchars_res2str , |
|
.Nm mchars_spec2cp , |
.Nm mchars_spec2cp , |
.Nm mchars_spec2str , |
.Nm mchars_spec2str , |
.Nm mdoc_meta , |
.Nm mdoc_meta , |
|
|
.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 |
|
|
.Fn mchars_free "struct mchars *p" |
.Fn mchars_free "struct mchars *p" |
.Ft char |
.Ft char |
.Fn mchars_num2char "const char *cp" "size_t sz" |
.Fn mchars_num2char "const char *cp" "size_t sz" |
.Ft "const char *" |
|
.Fo mchars_res2str |
|
.Fa "struct mchars *p" |
|
.Fa "const char *cp" |
|
.Fa "size_t sz" |
|
.Fa "size_t *rsz" |
|
.Fc |
|
.Ft int |
.Ft int |
.Fo mchars_res2cp |
.Fn mchars_num2uc "const char *cp" "size_t sz" |
.Fa "struct mchars *p" |
|
.Fa "const char *cp" |
|
.Fa "size_t sz" |
|
.Ft "const char *" |
.Ft "const char *" |
.Fc |
|
.Ft "const char *" |
|
.Fo mchars_spec2str |
.Fo mchars_spec2str |
.Fa "struct mchars *p" |
.Fa "struct mchars *p" |
.Fa "const char *cp" |
.Fa "const char *cp" |
|
|
.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" |
.It Vt "struct mchars" |
An opaque pointer to an object allowing for translation between |
An opaque pointer to an object allowing for translation between |
character strings and glyphs. |
character strings and glyphs. |
See |
See |
.Fn mchars_alloc . |
.Fn mchars_alloc . |
.It Vt "enum mparset" |
.It Vt "enum mparset" |
|
The type of parser when reading input. |
|
This should usually be |
|
.Va 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 |
Line 247 The object must be freed with |
|
Line 255 The object must be freed with |
|
Free an object created with |
Free an object created with |
.Fn mchars_alloc . |
.Fn mchars_alloc . |
.It Fn mchars_num2char |
.It Fn mchars_num2char |
Convert a character index as found in \eN\(aq\(aq into a printable |
Convert a character index (e.g., the \eN\(aq\(aq escape) into a |
character. |
printable ASCII character. |
Returns \e0 (the nil character) if the input sequence is malformed. |
Returns \e0 (the nil character) if the input sequence is malformed. |
.It Fn mchars_res2cp |
.It Fn mchars_num2uc |
Convert a predefined character into a valid Unicode codepoint. |
Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into |
Returns \-1 on failure and 0 if no code-point exists (if this occurs, |
a Unicode codepoint. |
the caller should fall back to |
Returns \e0 (the nil character) if the input sequence is malformed. |
.Fn mchars_res2str ) . |
|
.It Fn mchars_res2str |
|
Convert a predefined character into an ASCII string. |
|
Returns NULL on failure. |
|
.It Fn mchars_spec2cp |
.It Fn mchars_spec2cp |
Convert a special character into a valid Unicode codepoint. |
Convert a special character into a valid Unicode codepoint. |
Returns \-1 on failure and 0 if no code-point exists (if this occurs, |
Returns \-1 on failure or a non-zero Unicode codepoint on success. |
the caller should fall back to |
|
.Fn mchars_spec2str ) . |
|
.It Fn mchars_spec2str |
.It Fn mchars_spec2str |
Convert a special character into an ASCII string. |
Convert a special character into an ASCII string. |
Returns NULL on failure. |
Returns NULL on failure. |
Line 334 This section consists of structural documentation for |
|
Line 336 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 375 where capitalised non-terminals represent nodes. |
|
Line 406 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 434 where capitalised non-terminals represent nodes. |
|
Line 465 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 |