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.20 and 1.32

version 1.20, 2009/03/20 15:14:01

version 1.32, 2009/07/19 08:34:59

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 36

Line 34

.Vt extern const char * const * mdoc_argnames;

.Ft "struct mdoc *"

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

.Ft void

.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

Line 56 library parses lines of

Line 54 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 140 Returns NULL on failure. If non-NULL, the pointer mus

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

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

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

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

Line 219 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 275 will truncate the file's last character (see

Line 265 will truncate the file's last character (see

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

Line 307 mdoc_free(mdoc);

Line 297 mdoc_free(mdoc);

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@openbsd.org .

.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