mandoc/mdoc.3 - diff - 1.56

Return to mdoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/mdoc.3 between version 1.47 and 1.56

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

version 1.56, 2011/02/09 09:05:52

Line 30

Line 30

.Nd mdoc macro compiler library

.Nd mdoc macro compiler library

.Sh SYNOPSIS

.Sh SYNOPSIS

.In mandoc.h

.In mandoc.h

.In regs.h

.In mdoc.h

.In mdoc.h

.Vt extern const char * const * mdoc_macronames;

.Vt extern const char * const * mdoc_macronames;

.Vt extern const char * const * mdoc_argnames;

.Vt extern const char * const * mdoc_argnames;

.Ft int

.Fo mdoc_addeqn

.Fa "struct mdoc *mdoc"

.Fa "const struct eqn *eqn"

.Fc

.Ft int

.Fo mdoc_addspan

.Fa "struct mdoc *mdoc"

.Fa "const struct tbl_span *span"

.Fc

.Ft "struct mdoc *"

.Ft "struct mdoc *"

.Fo mdoc_alloc

.Fo mdoc_alloc

.Fa "struct regset *regs"

.Fa "struct regset *regs"

.Fa "void *data"

.Fa "void *data"

.Fa "int pflags"

.Fa "mandocmsg msgs"

.Fa "mandocmsg msgs"

.Fc

.Fc

.Ft int

.Ft int

Line 81 The

Line 89 The

.Fn mdoc_reset

.Fn mdoc_reset

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

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

sequence.

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

.Ss Types

Both functions (see

.Sx Functions )

and variables (see

.Sx Variables )

may use the following types:

.Bl -ohang

.Bl -ohang

.It Vt struct mdoc

.It Vt struct mdoc

An opaque type defined in

An opaque type.

.Pa mdoc.c .

Its values are only used privately within the library.

Its values are only used privately within the library.

.It Vt struct mdoc_node

.It Vt struct mdoc_node

A parsed node.

A parsed node.

Defined in

.Pa mdoc.h .

See

See

.Sx Abstract Syntax Tree

.Sx Abstract Syntax Tree

for details.

for details.

.It Vt mandocmsg

A function callback type defined in

.Pa mandoc.h .

.El

.El

.Ss Functions

.Ss Functions

Function descriptions follow:

If

.Fn mdoc_addeqn ,

.Fn mdoc_addspan ,

.Fn mdoc_parseln ,

or

.Fn mdoc_endparse

return 0, calls to any function but

.Fn mdoc_reset

or

.Fn mdoc_free

will raise an assertion.

.Bl -ohang

.Bl -ohang

.It Fn mdoc_addeqn

Add an equation to the parsing stream.

Returns 0 on failure, 1 on success.

.It Fn mdoc_addspan

Add a table span to the parsing stream.

Returns 0 on failure, 1 on success.

.It Fn mdoc_alloc

.It Fn mdoc_alloc

Allocates a parsing structure.

Allocates a parsing structure.

The

The

.Fa data

.Fa data

pointer is passed to

pointer is passed to

.Fa msgs .

.Fa msgs .

The

Always returns a valid pointer.

.Fa pflags

The pointer must be freed with

arguments are defined in

.Pa mdoc.h .

Returns NULL on failure.

If non-NULL, the pointer must be freed with

.Fn mdoc_free .

.Fn mdoc_free .

.It Fn mdoc_reset

.It Fn mdoc_reset

Reset the parser for another parse routine.

Reset the parser for another parse routine.

Line 150 The input buffer

Line 146 The input buffer

is modified by this function.

is modified by this function.

.It Fn mdoc_endparse

.It Fn mdoc_endparse

Signals that the parse is complete.

Signals that the parse is complete.

Note that if

.Fn mdoc_endparse

is called subsequent to

.Fn mdoc_node ,

the resulting tree is incomplete.

Returns 0 on failure, 1 on success.

Returns 0 on failure, 1 on success.

.It Fn mdoc_node

.It Fn mdoc_node

Returns the first node of the parse.

Returns the first node of the parse.

Note that if

.Fn mdoc_parseln

or

.Fn mdoc_endparse

return 0, the tree will be incomplete.

.It Fn mdoc_meta

.It Fn mdoc_meta

Returns the document's parsed meta-data.

Returns the document's parsed meta-data.

If this information has not yet been supplied or

.Fn mdoc_parseln

or

.Fn mdoc_endparse

return 0, the data will be incomplete.

.El

.El

.Ss Variables

.Ss Variables

The following variables are also defined:

.Bl -ohang

.Bl -ohang

.It Va mdoc_macronames

.It Va mdoc_macronames

An array of string-ified token names.

An array of string-ified token names.

Line 339 int line;

Line 319 int line;

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

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

line = 1;

line = 1;

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

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

buf = NULL;

buf = NULL;

alloc_len = 0;

alloc_len = 0;

Line 360 parsed(mdoc, node);

Line 340 parsed(mdoc, node);

mdoc_free(mdoc);

mdoc_free(mdoc);

.Ed

.Ed

.Pp

.Pp

Please see

To compile this, execute

.Pp

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

.Pp

where

.Pa main.c

.Pa main.c

in the source archive for a rigorous reference.

is the example file.

.Sh SEE ALSO

.Sh SEE ALSO

.Xr mandoc 1 ,

.Xr mandoc 1 ,

.Xr mdoc 7

.Xr mdoc 7