mandoc/mdoc.3 - diff

Return to mdoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/mdoc.3 between version 1.6 and 1.10

version 1.6, 2009/02/23 09:33:34

version 1.10, 2009/02/24 13:46:54

Line 50

The

.Nm mdoc

library parses lines of mdoc input into an abstract syntax tree.

.Dq mdoc

.Dq mdoc ,

is a macro package of the

which is used to format BSD manual pages, is a macro package of the

.Dq roff

language, which is used to format BSD manual pages. The

language. The

.Nm

library implements only those macros documented in the

.Xr mdoc 7

Line 89 This section further defines the

.Sx Functions

and

.Sx Variables

available to programmers. The last sub-section,

available to programmers. Following that,

.Sx Character Encoding

describes input format. Lastly,

.Sx Abstract Syntax Tree ,

documents the output tree.

.\" SUBSECTION

Line 99 Both functions (see

Line 101 Both functions (see

and variables (see

.Sx Variables )

may use the following types:

.Bl -ohang

.Bl -ohang -offset "XXXX"

.\" LIST-ITEM

.It Vt struct mdoc

An opaque type defined in

Line 120 for details.

Line 122 for details.

.\" SUBSECTION

.Ss Functions

Function descriptions follow:

.Bl -ohang

.Bl -ohang -offset "XXXX"

.\" LIST-ITEM

.It Fn mdoc_alloc

Allocates a parsing structure. The

Line 165 return 0, the data will be incomplete.

Line 167 return 0, the data will be incomplete.

.\" SUBSECTION

.Ss Variables

The following variables are also defined:

.Bl -ohang

.Bl -ohang -offset "XXXX"

.\" LIST-ITEM

.It Va mdoc_macronames

An array of string-ified token names.

Line 174 An array of string-ified token names.

Line 176 An array of string-ified token names.

An array of string-ified token argument names.

.El

.\" SUBSECTION

.Ss Character Encoding

The

.Xr mdoc 3

library accepts only printable ASCII characters as defined by

.Xr isprint 3 .

Non-ASCII character sequences are escaped with an escape character

.Sq \\

and followed by either an open-parenthesis

.Sq \&(

for two-character sequences; an open-bracket

.Sq \&[

for n-character sequences (terminated at a close-bracket

.Sq \&] ) ;

or one of a small set of single characters for other escapes.

.\" SUBSECTION

.Ss Abstract Syntax Tree

The

.Nm

Line 213 field).

Line 230 field).

The tree itself is arranged according to the following normal form,

where capitalised non-terminals represent nodes.

.Pp

.Bl -tag -width "ELEMENTXX" -compact

.Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"

.\" LIST-ITEM

.It ROOT

\(<- mnode+

Line 238 where capitalised non-terminals represent nodes.

Line 255 where capitalised non-terminals represent nodes.

.Pp

Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of

the BLOCK production. These refer to punctuation marks. Furthermore,

although a TEXT node will generally have a non-zero-length string, it

although a TEXT node will generally have a non-zero-length string, in

certain cases, such as

the specific case of

.Dq \&.Bd \-literal ,

.Sq \&.Bd \-literal ,

an empty line will produce a zero-length string.

.\" PARAGRAPH

.Pp

The rule-of-thumb for mapping node types to macros follows: in-line

The rule-of-thumb for mapping node types to macros follows. In-line

elements, such as

.Dq \&.Em foo ,

.Sq \&.Em foo ,

are classified as ELEMENT nodes, which can only contain text.

Multi-line elements such as

Multi-line elements, such as

.Dq \&.Sh

.Sq \&.Sh ,

are BLOCK elements, where the HEAD constitutes line contents and the

BODY constitutes subsequent lines. In-line elements with matching

pairs, such as

.Dq \&.So

.Sq \&.So

and

.Dq \&.Sc ,

.Sq \&.Sc ,

are BLOCK elements with no HEAD tag. The only exception to this is

.Dq \&.Eo

.Sq \&.Eo

and

.Dq \&.Ec ,

.Sq \&.Ec ,

which has a HEAD and TAIL node corresponding to the enclosure string.

TEXT nodes, obviously, constitute text; the ROOT node is the document's

TEXT nodes, obviously, constitute text, and the ROOT node is the

root.

document's root.

.\" SECTION

.Sh EXAMPLES

The following example reads lines from stdin and parses them, operating

Line 272 Note that, if the last line of the file isn't newline-

Line 289 Note that, if the last line of the file isn't newline-

will truncate the file's last character (see

.Xr fgetln 3 ) .

Further, this example does not error-check nor free memory upon failure.

.Bd -literal

.Bd -literal -offset "XXXX"

struct mdoc *mdoc;

struct mdoc_node *node;

char *buf;

Line 318 is the default

Line 335 is the default

.Xr groff 1

system bundled with

.Ox .

.\" PARAGRAPH

.Pp

Un-implemented: the

.Sq \&Xc

Line 327 macros aren't handled when used to span lines for the

Line 345 macros aren't handled when used to span lines for the

.Sq \&It

macro. Such usage is specifically discouraged in

.Xr mdoc.samples 7 .

.\" PARAGRAPH

.Pp

Bugs: when

.Sq \&It \-column

is invoked, whitespace is not stripped around

.Sq \&Ta

or tab-character separators.

.\" PARAGRAPH

.Pp

Bugs: elements within columns for

.Sq \&It \-column

are not yet supported.

.\" PARAGRAPH

.Pp

Incompatible: the

.Sq \&At

macro only accepts a single parameter. Furthermore, several macros

.Pf ( Sq \&Pp ,

.Sq \&It ,

and possibly others) accept multiple arguments with a warning.

.\" PARAGRAPH

.Pp

Incompatible: only those macros specified by

.Xr mdoc.samples 7

CVSweb