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

version 1.12, 2009/02/27 08:20:15

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 mdoc input into an abstract syntax tree.

library parses lines of

.Dq mdoc ,

which is used to format BSD manual pages, is a macro package of the

.Dq roff

language. The

.Nm

library implements only those macros documented in the

.Xr mdoc 7

and

input (and

.Xr mdoc.samples 7

.Em only

manuals. Documents with

mdoc) into an abstract syntax tree (AST).

.Xr refer 1 ,

.Xr eqn 1

and other pre-processor sections aren't accomodated.

.\" PARAGRAPH

.Pp

.Nm

.Ud

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

available to programmers. Following that, the

.Sx Character Encoding

.Sx Abstract Syntax Tree

describes input format. Lastly,

section documents the output tree.

.Sx Abstract Syntax Tree ,

documents the output tree.

.\" SUBSECTION

.Ss Types

Both functions (see

Line 118 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 131 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 179 An array of string-ified token names.

Line 177 An array of string-ified token names.

An array of string-ified token argument names.

.El

.\" SUBSECTION

.Ss Character Encoding

The

.Xr mdoc 3

library accepts only printable ASCII characters as defined by

.Xr isprint 3 .

Non-ASCII character sequences are delimited in various ways. All are

preceeded by an escape character

.Sq \\

and followed by either an open-parenthesis

.Sq \&(

for two-character sequences; an open-bracket

.Sq \&[

for n-character sequences (terminated at a close-bracket

.Sq \&] ) ;

an asterisk and open-parenthesis

.Sq \&*(

for two-character sequences;

an asterisk and non-open-parenthesis

.Sq \&*

for single-character sequences; or one of a small set of standalone

single characters for other escapes.

.Pp

Examples:

.Pp

.Bl -tag -width "XXXXXXXX" -offset "XXXX" -compact

.\" LIST-ITEM

.It \\*(<=

prints

.Dq \*(<=

.Pq greater-equal

.\" LIST-ITEM

.It \\(<-

prints

.Dq \(<-

.Pq left-arrow

.\" LIST-ITEM

.It \\[<-]

also prints

.Dq \(<-

.Pq left-arrow

.\" LIST-ITEM

.It \\*(Ba

prints

.Dq \*(Ba

.Pq bar

.\" LIST-ITEM

.It \\*q

prints

.Dq \*q

.Pq double-quote

.El

.\" SUBSECTION

.Ss Abstract Syntax Tree

The

.Nm

functions produce an abstract syntax tree (AST) describing the input

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

lines in a regular form. It may be reviewed at any time with

regular form. It may be reviewed at any time with

.Fn mdoc_nodes ;

however, if called before

.Fn mdoc_endparse ,

or after

.Fn mdoc_endparse

.Fn mdoc_parseln

fail, it may be incomplete.

.\" PARAGRAPH

.Pp

The AST is composed of

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

.\" PARAGRAPH

.Pp

The rule-of-thumb for mapping node types to macros follows. In-line

elements, such as

.Sq \&.Em foo ,

are classified as ELEMENT nodes, which can only contain text.

Multi-line elements, such as

.Sq \&.Sh ,

are BLOCK elements, where the HEAD constitutes line contents and the

BODY constitutes subsequent lines. In-line elements with matching

pairs, such as

.Sq \&.So

and

.Sq \&.Sc ,

are BLOCK elements with no HEAD tag. The only exception to this is

.Sq \&.Eo

and

.Sq \&.Ec ,

which has a HEAD and TAIL node corresponding to the enclosure string.

TEXT nodes, obviously, constitute text, and the ROOT node is the

document's root.

.\" 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 356 mdoc_free(mdoc);

Line 290 mdoc_free(mdoc);

.Ed

.\" SECTION

.Sh SEE ALSO

.Xr mdoc 7 ,

.Xr mandoc 1 ,

.Xr mdoc.samples 7 ,

.Xr mdoc 7

.Xr groff 1 ,

.Xr mdocml 1

.\" SECTION

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons Aq kristaps@kth.se .

.\" SECTION

.Sh BUGS

.Sh CAVEATS

Bugs, un-implemented macros and incompabilities are documented in this

.Bl -dash -compact

section. The baseline for determining whether macro parsing is

.\" LIST-ITEM

.Qq incompatible

.It

is the default

The

.Xr groff 1

.Sq \&.Xc

system bundled with

.Ox .

.\" PARAGRAPH

.Pp

Un-implemented: the

.Sq \&Xc

and

.Sq \&Xo

.Sq \&.Xo

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

.Sq \&It

.Sq \&.It

macro. Such usage is specifically discouraged in

macro.

.Xr mdoc.samples 7 .

.\" LIST-ITEM

.\" PARAGRAPH

.It

.Pp

The

Bugs: when

.Sq \&.Bsx

.Sq \&It \-column

macro family doesn't yet understand version arguments.

is invoked, whitespace is not stripped around

.\" LIST-ITEM

.Sq \&Ta

.It

or tab-character separators.

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

.\" PARAGRAPH

.Sq \&.Bd

.Pp

Bugs: elements within columns for

.Sq \&It \-column

are not yet supported.

.\" PARAGRAPH

.Pp

Incompatible: the

.Sq \&At

macro only accepts a single parameter. Furthermore, several macros

.Pf ( Sq \&Pp ,

.Sq \&It ,

and possibly others) accept multiple arguments with a warning.

.\" PARAGRAPH

.Pp

Incompatible: only those macros specified by

.Xr mdoc.samples 7

and

.Xr mdoc 7

.Sq \&.Bl

for

should be the width of

.Ox

.Qq <string> ;

are supported; support for

instead, a value of

.Nx

.Li 10n

and other

is provided.

.Bx

.\" LIST-ITEM

systems is in progress.

.It

Columns widths in

.Sq \&.Bl \-column

should default to width

.Qq <stringx>

if not included.

.El

CVSweb