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

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

version 1.50, 2010/10/10 09:47:05

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;

Line 37

.Fo mdoc_alloc

.Fa "struct regset *regs"

.Fa "void *data"

.Fa "int pflags"

.Fa "mandocmsg msgs"

.Fc

.Ft int

Line 80 The

Line 79 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_alloc

Allocates a parsing structure.

Line 124 The

Line 98 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 171 or

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

Line 226 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 266 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 307 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 328 parsed(mdoc, node);

mdoc_free(mdoc);

.Ed

.Pp

Please see

To compile this, execute

.Pp

.D1 % 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