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.39 and 1.47

version 1.39, 2010/05/25 21:46:48

version 1.47, 2010/07/04 22:04:04

Line 1

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

Line 29

Line 30

.Nd mdoc macro compiler library

.Sh SYNOPSIS

.In mandoc.h

.In regs.h

.In mdoc.h

.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 43

Line 50

.Ft "const struct mdoc_node *"

.Fn mdoc_node "const struct mdoc *mdoc"

.Ft int

.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"

.Fo mdoc_parseln

.Fa "struct mdoc *mdoc"

.Fa "int line"

.Fa "char *buf"

.Fc

.Ft int

.Fn mdoc_reset "struct mdoc *mdoc"

.Sh DESCRIPTION

Line 112 Function descriptions follow:

Line 123 Function descriptions follow:

Allocates a parsing structure.

The

.Fa data

pointer is passed to callbacks in

pointer is passed to

.Fa cb ,

.Fa msgs .

which are documented further in the header file.

The

.Fa pflags

arguments are defined in

Line 208 and

Line 218 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 222 where capitalised non-terminals represent nodes.

Line 236 where capitalised non-terminals represent nodes.

.It mnode

\(<- BLOCK | ELEMENT | TEXT

.It BLOCK

\(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]

\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]

.It BLOCK

\(<- BODY [TEXT] [TAIL [TEXT]]

.It ELEMENT

\(<- TEXT*

.It HEAD

\(<- mnode+

\(<- mnode*

.It BODY

\(<- mnode+

\(<- mnode* [ENDBODY mnode*]

.It TAIL

\(<- mnode+

\(<- mnode*

.It TEXT

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

.El

.Pp

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

the BLOCK production.

the BLOCK production: these refer to punctuation marks.

These refer to punctuation marks.

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

string, in the specific case of

.Sq \&.Bd \-literal ,

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