mandoc/mandoc.3 - diff

Return to mandoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.3 between version 1.10 and 1.11

version 1.10, 2011/05/24 21:41:11

version 1.11, 2011/06/22 22:10:02

Line 177 library also contains routines for translating charact

.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

Line 187 via

Line 184 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

Line 320 This section consists of structural documentation for

Line 336 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

Line 361 where capitalised non-terminals represent nodes.

Line 406 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

Line 420 where capitalised non-terminals represent nodes.

Line 465 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

CVSweb