diff options
Diffstat (limited to 'mandoc.3')
| -rw-r--r-- | mandoc.3 | 57 |
1 files changed, 51 insertions, 6 deletions
@@ -177,9 +177,6 @@ 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 . -.Pp -This library is -.Ud .Sh REFERENCE This section documents the functions, types, and variables available via @@ -187,16 +184,35 @@ via .Ss Types .Bl -ohang .It Vt "enum mandoc_esc" +An escape sequence classification. .It Vt "enum mandocerr" +A fatal error, error, or warning message during parsing. .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" +The type of parser when reading input. +This should usually be +.Va MPARSE_AUTO +for auto-detection. .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" +A prototype for a function to handle fatal error, error, and warning +messages emitted by the parser. .El .Ss Functions .Bl -ohang @@ -320,7 +336,36 @@ This section consists of structural documentation for .Xr mdoc 7 and .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 This AST is governed by the ontological rules dictated in .Xr man 7 @@ -361,7 +406,7 @@ where capitalised non-terminals represent nodes. .It ELEMENT \(<- ELEMENT | TEXT* .It TEXT -\(<- [[:alpha:]]* +\(<- [[:ascii:]]* .El .Pp The only elements capable of nesting other elements are those with @@ -420,7 +465,7 @@ where capitalised non-terminals represent nodes. .It TAIL \(<- mnode* .It TEXT -\(<- [[:printable:],0x1e]* +\(<- [[:ascii:]]* .El .Pp Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of |