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

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

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

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

Line 26

.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

Line 34

Line 35

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

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

Line 53 library parses lines of

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

Line 75 and

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

Line 123 Allocates a parsing structure. The

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

.\" LIST-ITEM

.It Fn mdoc_free

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

invocation.

Line 182 or after

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

Line 209 fields), its position in the tree (the

Line 220 fields), its position in the tree (the

.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 263 size_t len;

Line 272 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';

Line 282 mdoc_free(mdoc);

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

.An Kristaps Dzonsons Aq kristaps@openbsd.org .

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

.\" LIST-ITEM

.It

List-width suffix

.Qq m

isn't handled.

.\" LIST-ITEM

.It

Contents of the SYNOPSIS section aren't checked.

.El

CVSweb