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.11 and 1.20

version 1.11, 2009/02/25 17:02:47

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

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 49

Line 52

.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

input (and

.Em only

mdoc) into an abstract syntax tree that generalises the semantic

annotation of its input. Common front-ends for

.Nm

are

.Xr mdocterm 1 ,

.Xr mdoclint 1

and

.Xr mdoc.samples 7

.Xr mdoctree 1 .

manuals. Documents with

.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

Line 82 and

Line 78 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 92 This section further defines the

Line 91 This section further defines the

.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 132 Allocates a parsing structure. The

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

Line 185 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 escaped with 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 \&] ) ;

or one of a small set of single characters for other escapes.

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

Line 206 or after

Line 197 or after

.Fn mdoc_endparse

.Fn mdoc_parseln

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

Line 262 although a TEXT node will generally have a non-zero-le

Line 264 although a TEXT node will generally have a non-zero-le

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

Line 319 mdoc_free(mdoc);

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

.An Kristaps Dzonsons Aq kristaps@openbsd.org .

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

system bundled with

.Ox .

.\" PARAGRAPH

.Pp

Un-implemented: the

.Sq \&Xc

and

.Sq \&Xo

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

.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 doesn't yet understand version arguments.

is invoked, whitespace is not stripped around

.El

.Sq \&Ta

or tab-character separators.

.\" PARAGRAPH

.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

for

.Ox

are supported; support for

.Nx

and other

.Bx

systems is in progress.

CVSweb