-.\" $Id: mdoc.3,v 1.7 2009/02/23 09:46:59 kristaps Exp $
+.\" $Id: mdoc.3,v 1.13 2009/02/27 09:14:02 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: February 23 2009 $
+.Dd $Mdocdate: February 27 2009 $
.Dt mdoc 3
.Os
.\" SECTION
.Xr mdoc 7
and
.Xr mdoc.samples 7
-manuals.
+manuals. Documents with
+.Xr refer 1 ,
+.Xr eqn 1
+and other pre-processor sections aren't accomodated.
.\" PARAGRAPH
.Pp
.Nm
.Sx Functions
and
.Sx Variables
-available to programmers. The last sub-section,
+available to programmers. Following that,
+.Sx Character Encoding
+describes input format. Lastly,
.Sx Abstract Syntax Tree ,
documents the output tree.
.\" SUBSECTION
and variables (see
.Sx Variables )
may use the following types:
-.Bl -ohang
+.Bl -ohang -offset "XXXX"
.\" LIST-ITEM
.It Vt struct mdoc
An opaque type defined in
.\" SUBSECTION
.Ss Functions
Function descriptions follow:
-.Bl -ohang
+.Bl -ohang -offset "XXXX"
.\" LIST-ITEM
.It Fn mdoc_alloc
Allocates a parsing structure. The
.\" SUBSECTION
.Ss Variables
The following variables are also defined:
-.Bl -ohang
+.Bl -ohang -offset "XXXX"
.\" LIST-ITEM
.It Va mdoc_macronames
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.
+.\" PARAGRAPH
+.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
+.\" PARAGRAPH
+.Pp
+All escaped sequences are syntax-checked, but it's up to the front-end
+system to correctly render them to the output device.
+.\" SUBSECTION
.Ss Abstract Syntax Tree
The
.Nm
The tree itself is arranged according to the following normal form,
where capitalised non-terminals represent nodes.
.Pp
-.Bl -tag -width "ELEMENTXX" -compact
+.Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
.\" LIST-ITEM
.It ROOT
\(<- mnode+
.Pp
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, it
-certain cases, such as
-.Dq \&.Bd \-literal ,
+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
+The rule-of-thumb for mapping node types to macros follows. In-line
elements, such as
-.Dq \&.Em foo ,
+.Sq \&.Em foo ,
are classified as ELEMENT nodes, which can only contain text.
-Multi-line elements such as
-.Dq \&.Sh
+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
-.Dq \&.So
+.Sq \&.So
and
-.Dq \&.Sc ,
+.Sq \&.Sc ,
are BLOCK elements with no HEAD tag. The only exception to this is
-.Dq \&.Eo
+.Sq \&.Eo
and
-.Dq \&.Ec ,
+.Sq \&.Ec ,
which has a HEAD and TAIL node corresponding to the enclosure string.
-TEXT nodes, obviously, constitute text; the ROOT node is the document's
-root.
+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
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
+.Bd -literal -offset "XXXX"
struct mdoc *mdoc;
struct mdoc_node *node;
char *buf;
.Xr groff 1
system bundled with
.Ox .
+.\" PARAGRAPH
.Pp
Un-implemented: the
.Sq \&Xc
.Sq \&It
macro. Such usage is specifically discouraged in
.Xr mdoc.samples 7 .
+.\" PARAGRAPH
.Pp
Bugs: when
.Sq \&It \-column
is invoked, whitespace is not stripped around
.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
.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
git.ckatri.com / mandoc.git / blobdiff