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.17 and 1.36

version 1.17, 2009/03/14 05:21:58

version 1.36, 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 mdoc 3

.Dt MDOC 3

.Os

.\" SECTION

.Sh NAME

Line 26

Line 24

.Nm mdoc_endparse ,

.Nm mdoc_node ,

.Nm mdoc_meta ,

.Nm mdoc_free

.Nm mdoc_free ,

.Nm mdoc_reset

.Nd mdoc macro compiler library

.\" SECTION

.Sh SYNOPSIS

.Fd #include <mdoc.h>

.In mdoc.h

.Vt extern const char * const * mdoc_macronames;

.Vt extern const char * const * mdoc_argnames;

.Ft "struct mdoc *"

.Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"

.Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"

.Ft int

.Fn mdoc_reset "struct mdoc *mdoc"

.Ft void

.Fn mdoc_free "struct mdoc *mdoc"

.Ft int

.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"

.Ft "const struct mdoc_node *"

.Fn mdoc_node "struct mdoc *mdoc"

.Fn mdoc_node "const struct mdoc *mdoc"

.Ft "const struct mdoc_meta *"

.Fn mdoc_meta "struct mdoc *mdoc"

.Fn mdoc_meta "const struct mdoc *mdoc"

.Ft int

.Fn mdoc_endparse "struct mdoc *mdoc"

.\" SECTION

.Sh DESCRIPTION

The

.Nm mdoc

library parses lines of

.Xr mdoc 7

input (and

.Em only

mdoc) into an abstract syntax tree that generalises the semantic

mdoc) into an abstract syntax tree (AST).

annotation of its input. Common front-ends for

.Nm

are

.Xr mdocterm 1 ,

.Xr mdoclint 1

and

.Xr mdoctree 1 .

.\" PARAGRAPH

.Pp

In general, applications initiate a parsing sequence with

.Fn mdoc_alloc ,

parse each line in a document with

.Fn mdoc_parseln ,

close the parsing session with

.Fn mdoc_endparse ,

operate over the syntax tree returned by

.Fn mdoc_node

and

.Fn mdoc_meta ,

then free all allocated memory with

.Fn mdoc_free .

See the

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 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 109 A set of message callbacks defined in

Line 106 A set of message callbacks defined in

.It Vt struct mdoc_node

A parsed node. Defined in

.Pa mdoc.h .

See

.Sx Abstract Syntax Tree

for details.

.El

Line 122 Function descriptions follow:

Line 119 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. Returns NULL on

which are documented further in the header file.

failure. If non-NULL, the pointer must be freed with

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 .

.\" LIST-ITEM

.It Fn mdoc_reset

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

.Fn mdoc_parseln

behaves as if invoked for the first time. If it returns 0, memory could

not be allocated.

.\" LIST-ITEM

.It Fn mdoc_free

Free all resources of a parser. The pointer is no longer valid after

invocation.

.\" LIST-ITEM

.It Fn mdoc_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 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.

.\" LIST-ITEM

.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

Line 171 An array of string-ified token argument names.

Line 178 An array of string-ified token argument 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 179 regular form. It may be reviewed at any time with

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

however, if called before

.Fn mdoc_endparse ,

or after

.Fn mdoc_endparse

.Fn mdoc_parseln

fail, it may be incomplete. This AST is governed by the ontological

fail, it may be incomplete.

.\" PARAGRAPH

.Pp

This AST is governed by the ontological

rules dictated in

.Xr mdoc 7

and derives its terminology accordingly.

.Qq In-line

elements described in

.Xr mdoc 7

are described simply as

.Qq elements .

.\" PARAGRAPH

.Pp

The AST is composed of

.Vt struct mdoc_node

nodes with block, head, body, element, root and text types as declared

by the

Line 206 and

Line 216 and

fields), its position in the tree (the

.Va parent ,

.Va child ,

.Va next

and

.Va prev

fields) and type-specific data (the

fields) and some type-specific data.

.Va data

field).

.\" PARAGRAPH

.Pp

The tree itself is arranged according to the following normal form,

Line 243 where capitalised non-terminals represent nodes.

Line 251 where capitalised non-terminals represent nodes.

Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of

the BLOCK production. These refer to punctuation marks. Furthermore,

although a TEXT node will generally have a non-zero-length string, in

the specific case of

.Sq \&.Bd \-literal ,

an empty line will produce a zero-length string.

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

struct mdoc *mdoc;

struct mdoc_node *node;

const struct mdoc_node *node;

char *buf;

size_t len;

int line;

line = 1;

mdoc = mdoc_alloc(NULL, NULL);

mdoc = mdoc_alloc(NULL, 0, NULL);

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

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

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

if ( ! mdoc_parseln(mdoc, line, buf))

errx(1, "mdoc_parseln");

line++;

Line 282 mdoc_free(mdoc);

Line 290 mdoc_free(mdoc);

.Ed

.\" SECTION

.Sh SEE ALSO

.Xr mdocterm 1 ,

.Xr mandoc 1 ,

.Xr mdoclint 1 ,

.Xr mdoctree 1 ,

.Xr mdoc 7

.\" SECTION

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

.\" SECTION

.Sh CAVEATS

.Bl -dash -compact

.\" LIST-ITEM

.It

The

.Sq \&Xc

.Sq \&.Xc

and

.Sq \&Xo

.Sq \&.Xo

macros aren't handled when used to span lines for the

.Sq \&It

.Sq \&.It

macro.

.\" LIST-ITEM

.It

The

.Sq \&Bsx

.Sq \&.Bsx

macro doesn't yet understand version arguments.

macro family doesn't yet understand version arguments.

.\" LIST-ITEM

.It

If not given a value, the \-offset argument to

.Sq \&.Bd

and

.Sq \&.Bl

should be the width of

.Qq <string> ;

instead, a value of

.Li 10n

is provided.

.\" LIST-ITEM

.It

Columns widths in

.Sq \&.Bl \-column

should default to width

.Qq <stringx>

if not included.

.El

CVSweb