mandoc/man.3 - diff

Return to man.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/man.3 between version 1.1 and 1.11

version 1.1, 2009/03/27 14:56:15

version 1.11, 2010/01/07 19:10:09

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

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

.\" above copyright notice and this permission notice appear in all

.\" copyright notice and this permission notice appear in all copies.

.\" copies.

.\"

.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL

.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES

.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED

.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE

.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR

.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL

.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR

.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER

.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR

.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

.\" PERFORMANCE OF THIS SOFTWARE.

.\"

.Dd $Mdocdate$

.Dt man 3

.Dt MAN 3

.Os

.\" SECTION

.Sh NAME

Line 31

Line 29

.Nd man macro compiler library

.\" SECTION

.Sh SYNOPSIS

.Fd #include <man.h>

.In man.h

.Vt extern const char * const * man_macronames;

.Ft "struct man *"

.Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"

Line 42

Line 40

.Ft int

.Fn man_parseln "struct man *man" "int line" "char *buf"

.Ft "const struct man_node *"

.Fn man_node "struct man *man"

.Fn man_node "const struct man *man"

.Ft "const struct man_meta *"

.Fn man_meta "struct man *man"

.Fn man_meta "const struct man *man"

.Ft int

.Fn man_endparse "struct man *man"

.\" SECTION

.Sh DESCRIPTION

The

.Nm man

library parses lines of

.Xr man 7

input (and

.Em only

Line 60 man) into an abstract syntax tree (AST).

Line 58 man) into an abstract syntax tree (AST).

.Pp

In general, applications initiate a parsing sequence with

.Fn man_alloc ,

parse each line in a document with

.Fn man_parseln ,

close the parsing session with

.Fn man_endparse ,

operate over the syntax tree returned by

.Fn man_node

and

.Fn man_meta ,

then free all allocated memory with

Line 78 sequence. See the

Line 76 sequence. See the

section for a full example.

.\" PARAGRAPH

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

.\" SUBSECTION

.Ss Types

Line 107 A set of message callbacks defined in

Line 105 A set of message callbacks defined in

.It Vt struct man_node

A parsed node. Defined in

.Pa man.h .

See

.Sx Abstract Syntax Tree

for details.

.El

Line 120 Function descriptions follow:

Line 118 Function descriptions follow:

Allocates a parsing structure. The

.Fa data

pointer is passed to callbacks in

.Fa cb ,

which are documented further in the header file.

The

.Fa pflags

arguments are defined in

Line 130 Returns NULL on failure. If non-NULL, the pointer mus

Line 128 Returns NULL on failure. If non-NULL, the pointer mus

.Fn man_free .

.\" LIST-ITEM

.It Fn man_reset

Reset the parser for another parse routine. After its use,

.Fn man_parseln

behaves as if invoked for the first time.

.\" LIST-ITEM

Line 140 invocation.

Line 138 invocation.

.\" LIST-ITEM

.It Fn man_parseln

Parse a nil-terminated line of input. This line should not contain the

trailing newline. Returns 0 on failure, 1 on success. The input buffer

.Fa buf

is modified by this function.

.\" LIST-ITEM

.It Fn man_endparse

Signals that the parse is complete. Note that if

.Fn man_endparse

is called subsequent to

.Fn man_node ,

the resulting tree is incomplete. Returns 0 on failure, 1 on success.

.\" LIST-ITEM

.It Fn man_node

Returns the first node of the parse. Note that if

.Fn man_parseln

.Fn man_endparse

return 0, the tree will be incomplete.

.It Fn man_meta

Returns the document's parsed meta-data. If this information has not

yet been supplied or

.Fn man_parseln

.Fn man_endparse

Line 175 An array of string-ified token names.

Line 173 An array of string-ified token names.

.El

.\" SUBSECTION

.Ss Abstract Syntax Tree

The

.Nm

functions produce an abstract syntax tree (AST) describing input in a

regular form. It may be reviewed at any time with

Line 183 regular form. It may be reviewed at any time with

Line 181 regular form. It may be reviewed at any time with

however, if called before

.Fn man_endparse ,

or after

.Fn man_endparse

.Fn man_parseln

fail, it may be incomplete.

.\" PARAGRAPH

.Pp

This AST is governed by the ontological

rules dictated in

.Xr man 7

and derives its terminology accordingly.

.\" PARAGRAPH

.Pp

The AST is composed of

.Vt struct man_node

nodes with element, root and text types as declared

by the

Line 208 and

Line 206 and

fields), its position in the tree (the

.Va parent ,

.Va child ,

.Va next

and

.Va prev

fields) and some type-specific data.

.\" PARAGRAPH

.Pp

Line 222 where capitalised non-terminals represent nodes.

Line 220 where capitalised non-terminals represent nodes.

.It ROOT

\(<- mnode+

.It mnode

\(<- ELEMENT | TEXT

\(<- ELEMENT | TEXT | BLOCK

.It BLOCK

\(<- HEAD BODY

.It HEAD

\(<- mnode*

.It BODY

\(<- mnode*

.It ELEMENT

\(<- ELEMENT | TEXT*

.It TEXT

Line 236 next-lint scope as documented in

Line 240 next-lint scope as documented in

.\" SECTION

.Sh EXAMPLES

The following example reads lines from stdin and parses them, operating

on the finished parse tree with

.Fn parsed .

Note that, if the last line of the file isn't newline-terminated, this

will truncate the file's last character (see

.Xr fgetln 3 ) .

Further, this example does not error-check nor free memory upon failure.

.Bd -literal -offset "XXXX"

Line 253 line = 1;

Line 257 line = 1;

man = man_alloc(NULL, 0, NULL);

while ((buf = fgetln(fp, &len))) {

buf[len - 1] = '\\0';

buf[len - 1] = '\e0';

if ( ! man_parseln(man, line, buf))

errx(1, "man_parseln");

line++;

Line 275 man_free(man);

Line 279 man_free(man);

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@openbsd.org .

.An Kristaps Dzonsons Aq kristaps@kth.se .

CVSweb