Return to mdoc.3 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.10, 2009/02/24 13:46:54 | version 1.19, 2009/03/16 23:37:28 | ||
---|---|---|---|
|
|
||
.\" $Id$ | .\" $Id$ | ||
.\" | .\" | ||
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> | .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org> | ||
.\" | .\" | ||
.\" Permission to use, copy, modify, and distribute this software for any | .\" 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 | ||
|
|
||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | The | ||
.Nm mdoc | .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 | .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 | and | ||
.Xr mdoc.samples 7 | .Xr mdoctree 1 . | ||
manuals. | |||
.\" PARAGRAPH | .\" PARAGRAPH | ||
.Pp | .Pp | ||
.Nm | |||
is | |||
.Ud | |||
.\" PARAGRAPH | |||
.Pp | |||
In general, applications initiate a parsing sequence with | In general, applications initiate a parsing sequence with | ||
.Fn mdoc_alloc , | .Fn mdoc_alloc , | ||
parse each line in a document with | parse each line in a document with | ||
|
|
||
.Sx Functions | .Sx Functions | ||
and | and | ||
.Sx Variables | .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 | .\" SUBSECTION | ||
.Ss Types | .Ss Types | ||
Both functions (see | Both functions (see | ||
|
|
||
An array of string-ified token argument names. | An array of string-ified token argument names. | ||
.El | .El | ||
.\" SUBSECTION | .\" 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 | .Ss Abstract Syntax Tree | ||
The | The | ||
.Nm | .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 ; | .Fn mdoc_nodes ; | ||
however, if called before | however, if called before | ||
.Fn mdoc_endparse , | .Fn mdoc_endparse , | ||
|
|
||
.Fn mdoc_endparse | .Fn mdoc_endparse | ||
or | or | ||
.Fn mdoc_parseln | .Fn mdoc_parseln | ||
fail, it may be incomplete. | fail, it may be incomplete. | ||
.\" PARAGRAPH | .\" PARAGRAPH | ||
.Pp | .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 | The AST is composed of | ||
.Vt struct mdoc_node | .Vt struct mdoc_node | ||
nodes with block, head, body, element, root and text types as declared | nodes with block, head, body, element, root and text types as declared | ||
|
|
||
the specific case of | the specific case of | ||
.Sq \&.Bd \-literal , | .Sq \&.Bd \-literal , | ||
an empty line will produce a zero-length string. | 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 | .\" SECTION | ||
.Sh EXAMPLES | .Sh EXAMPLES | ||
The following example reads lines from stdin and parses them, operating | The following example reads lines from stdin and parses them, operating | ||
|
|
||
.Ed | .Ed | ||
.\" SECTION | .\" SECTION | ||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr mdoc 7 , | .Xr mdocterm 1 , | ||
.Xr mdoc.samples 7 , | .Xr mdoclint 1 , | ||
.Xr groff 1 , | .Xr mdoctree 1 , | ||
.Xr mdocml 1 | .Xr mdoc 7 | ||
.\" SECTION | .\" SECTION | ||
.Sh AUTHORS | .Sh AUTHORS | ||
The | The | ||
.Nm | .Nm | ||
utility was written by | utility was written by | ||
.An Kristaps Dzonsons Aq kristaps@kth.se . | .An Kristaps Dzonsons Aq kristaps@openbsd.org . | ||
.\" SECTION | .\" 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 | .Sq \&Xc | ||
and | and | ||
.Sq \&Xo | .Sq \&Xo | ||
macros aren't handled when used to span lines for the | 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 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. |