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.42 and 1.46

version 1.42, 2010/06/26 15:36:37

version 1.46, 2010/07/01 09:33:39

Line 34

.Vt extern const char * const * mdoc_macronames;

.Vt extern const char * const * mdoc_argnames;

.Ft "struct mdoc *"

.Fn mdoc_alloc "void *data" "int pflags" "mandocmsg msgs"

.Fo mdoc_alloc

.Fa "struct regset *regs"

.Fa "void *data"

.Fa "int pflags"

.Fa "mandocmsg msgs"

.Fc

.Ft int

.Fn mdoc_endparse "struct mdoc *mdoc"

.Ft void

Line 46

Line 51

.Ft int

.Fo mdoc_parseln

.Fa "struct mdoc *mdoc"

.Fa "const struct regset *regs"

.Fa "int line"

.Fa "char *buf"

.Fc

Line 213 and

Line 217 and

fields), its position in the tree (the

.Va parent ,

.Va child ,

.Va nchild ,

.Va next

and

.Va prev

fields) and some type-specific data.

fields) and some type-specific data, in particular, for nodes generated

from macros, the generating macro in the

.Va tok

field.

.Pp

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

where capitalised non-terminals represent nodes.

Line 231 where capitalised non-terminals represent nodes.

Line 239 where capitalised non-terminals represent nodes.

.It ELEMENT

\(<- TEXT*

.It HEAD

\(<- mnode+

\(<- mnode*

.It BODY

\(<- mnode+

\(<- mnode* [ENDBODY mnode*]

.It TAIL

\(<- mnode+

\(<- mnode*

.It TEXT

\(<- [[:printable:],0x1e]*

.El

Line 249 an empty line will produce a zero-length string.

Line 257 an empty line will produce a zero-length string.

Multiple body parts are only found in invocations of

.Sq \&Bl \-column ,

where a new body introduces a new phrase.

.Ss Badly-nested Blocks

The ENDBODY node is available to end the formatting associated

with a given block before the physical end of that block.

It has a non-null

.Va end

field, is of the BODY

.Va type ,

has the same

.Va tok

as the BLOCK it is ending, and has a

.Va pending

field pointing to that BLOCK's BODY node.

It is an indirect child of that BODY node

and has no children of its own.

.Pp

An ENDBODY node is generated when a block ends while one of its child

blocks is still open, like in the following example:

.Bd -literal -offset indent

\&.Ao ao

\&.Bo bo ac

\&.Ac bc

\&.Bc end

.Ed

.Pp

This example results in the following block structure:

.Bd -literal -offset indent

BLOCK Ao

HEAD Ao

BODY Ao

TEXT ao

BLOCK Bo, pending -> Ao

HEAD Bo

BODY Bo

TEXT bo

TEXT ac

ENDBODY Ao, pending -> Ao

TEXT bc

TEXT end

.Ed

.Pp

Here, the formatting of the

.Sq \&Ao

block extends from TEXT ao to TEXT ac,

while the formatting of the

.Sq \&Bo

block extends from TEXT bo to TEXT bc.

It renders as follows in

.Fl T Ns Cm ascii

mode:

.Pp

.Dl <ao [bo ac> bc] end

.Pp

Support for badly-nested blocks is only provided for backward

compatibility with some older

.Xr mdoc 7

implementations.

Using badly-nested blocks is

.Em strongly discouraged :

the

.Fl T Ns Cm html

and

.Fl T Ns Cm xhtml

front-ends are unable to render them in any meaningful way.

Furthermore, behaviour when encountering badly-nested blocks is not

consistent across troff implementations, especially when using multiple

levels of badly-nested blocks.

.Sh EXAMPLES

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

on the finished parse tree with

.Fn parsed .

This example does not error-check nor free memory upon failure.

.Bd -literal -offset indent

struct regset regs;

struct mdoc *mdoc;

const struct mdoc_node *node;

char *buf;

size_t len;

int line;

bzero(&regs, sizeof(struct regset));

line = 1;

mdoc = mdoc_alloc(NULL, 0, NULL);

mdoc = mdoc_alloc(&regs, NULL, 0, NULL);

buf = NULL;

alloc_len = 0;

CVSweb