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.45 and 1.54

version 1.45, 2010/06/29 19:20:38

version 1.54, 2011/01/03 13:55:26

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 int

.Fo mdoc_addspan

.Fa "struct mdoc *mdoc"

.Fa "const struct tbl_span *span"

.Fc

.Ft "struct mdoc *"

.Fo mdoc_alloc

.Fa "struct regset *regs"

.Fa "void *data"

.Fa "int pflags"

.Fa "mandocmsg msgs"

.Fc

.Ft int

Line 80 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:

.Fn mdoc_addspan ,

.Fn mdoc_parseln ,

.Fn mdoc_endparse

return 0, calls to any function but

.Fn mdoc_reset

.Fn mdoc_free

will raise an assertion.

.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

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 .

.It Fn mdoc_reset

Reset the parser for another parse routine.

Line 149 The input buffer

Line 137 The input buffer

is modified by this function.

.It Fn mdoc_endparse

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.

.It Fn mdoc_node

Returns the first node of the parse.

Note that if

.Fn mdoc_parseln

.Fn mdoc_endparse

return 0, the tree will be incomplete.

.It Fn mdoc_meta

Returns the document's parsed meta-data.

If this information has not yet been supplied or

.Fn mdoc_parseln

.Fn mdoc_endparse

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

Line 229 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

.Ss Badly-nested Blocks

A special kind of node is available to end the formatting

The ENDBODY node is available to end the formatting associated

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

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

Such an ENDBODY node has a non-null

It has a non-null

.Va end

field, is of the BODY

.Va type ,

Line 297 BLOCK Ao

Line 269 BLOCK Ao

TEXT end

.Ed

.Pp

Here, the formatting of the Ao block extends from TEXT ao to TEXT ac,

Here, the formatting of the

while the formatting of the Bo block extends from TEXT bo to TEXT bc,

.Sq \&Ao

rendering like this in

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

Support for badly nested blocks is only provided for backward

.Pp

Support for badly-nested blocks is only provided for backward

compatibility with some older

.Xr mdoc 7

implementations.

Using them in new code is stronly discouraged:

Using badly-nested blocks is

Some frontends, in particular

.Em strongly discouraged :

.Fl T Ns Cm html ,

the

are unable to render them in any meaningful way,

.Fl T Ns Cm html

many other

and

.Xr mdoc 7

.Fl T Ns Cm xhtml

implementations do not support them, and even for those that do,

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

the behaviour is not well-defined, in particular when using multiple

Furthermore, behaviour when encountering badly-nested blocks is not

levels of badly nested blocks.

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

Line 331 int line;

Line 310 int line;

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

line = 1;

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

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

buf = NULL;

alloc_len = 0;

Line 352 parsed(mdoc, node);

Line 331 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