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.41 and 1.52

version 1.41, 2010/05/30 22:56:02

version 1.52, 2011/01/01 12:18:37

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 32

Line 33

.In mdoc.h

.Vt extern const char * const * mdoc_macronames;

.Vt extern const char * const * mdoc_argnames;

.Ft int

.Fo mdoc_addspan

.Fa "struct mdoc *mdoc"

.Fa "const struct tbl_span *span"

.Fc

.Ft "struct mdoc *"

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

.Fo mdoc_alloc

.Fa "struct regset *regs"

.Fa "void *data"

.Fa "mandocmsg msgs"

.Fc

.Ft int

.Fn mdoc_endparse "struct mdoc *mdoc"

.Ft void

Line 43

Line 53

.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 70 The

Line 84 The

.Fn mdoc_reset

function may be used in order to reset the parser for another input

sequence.

See the

.Sx EXAMPLES

section for a simple example.

.Pp

This section further defines the

.Sx Types ,

.Sx Functions

and

.Sx Variables

available to programmers.

Following that, the

.Sx Abstract Syntax Tree

section documents the output tree.

.Ss Types

Both functions (see

.Sx Functions )

and variables (see

.Sx Variables )

may use the following types:

.Bl -ohang

.It Vt struct mdoc

An opaque type defined in

An opaque type.

.Pa mdoc.c .

Its values are only used privately within the library.

.It Vt struct mdoc_node

A parsed node.

Defined in

.Pa mdoc.h .

See

.Sx Abstract Syntax Tree

for details.

.It Vt mandocmsg

A function callback type defined in

.Pa mandoc.h .

.El

.Ss Functions

Function descriptions follow:

.Bl -ohang

.It Fn mdoc_addspan

Add a table span to the parsing stream.

Returns 0 on failure, 1 on success.

.It Fn mdoc_alloc

Allocates a parsing structure.

The

.Fa data

pointer is passed to

.Fa msgs .

The

.Fa pflags

arguments are defined in

.Pa mdoc.h .

Returns NULL on failure.

If non-NULL, the pointer must be freed with

.Fn mdoc_free .

Line 161 or

Line 149 or

return 0, the data will be incomplete.

.El

.Ss Variables

The following variables are also defined:

.Bl -ohang

.It Va mdoc_macronames

An array of string-ified token names.

Line 207 and

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

Line 216 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 243 an empty line will produce a zero-length string.

Line 234 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, NULL);

buf = NULL;

alloc_len = 0;

Line 277 parsed(mdoc, node);

Line 336 parsed(mdoc, node);

mdoc_free(mdoc);

.Ed

.Pp

Please see

To compile this, execute

.Pp

.Dl % cc main.c libmdoc.a libmandoc.a

.Pp

where

.Pa main.c

in the source archive for a rigorous reference.

is the example file.

.Sh SEE ALSO

.Xr mandoc 1 ,

.Xr mdoc 7

CVSweb