summaryrefslogtreecommitdiffstats
path: root/mdoc.3
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2009-02-23 09:33:34 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2009-02-23 09:33:34 +0000
commite6d5d6c4fa9992652ddd38c1f1a1bd0c10a275a2 (patch)
treed8b9fd946d7e6a443abba618088edc43f5936b3e /mdoc.3
parent63967ed8bf5ca40c3477ce83deda9051e813afd4 (diff)
downloadmandoc-e6d5d6c4fa9992652ddd38c1f1a1bd0c10a275a2.tar.gz
Considerable mdoc.3 documentation.
Added a few more escapes and macros.
Diffstat (limited to 'mdoc.3')
-rw-r--r--mdoc.3200
1 files changed, 181 insertions, 19 deletions
diff --git a/mdoc.3 b/mdoc.3
index bdf54294..3c93c44e 100644
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,8 +1,25 @@
+.\" $Id$
+.\"
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the
+.\" above copyright notice and this permission notice appear in all
+.\" copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
+.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt mdoc 3
.Os
-.\"
+.\" SECTION
.Sh NAME
.Nm mdoc_alloc ,
.Nm mdoc_parseln ,
@@ -11,7 +28,7 @@
.Nm mdoc_meta ,
.Nm mdoc_free
.Nd mdoc macro compiler library
-.\"
+.\" SECTION
.Sh SYNOPSIS
.Fd #include <mdoc.h>
.Vt extern const char * const * mdoc_macronames;
@@ -28,11 +45,28 @@
.Fn mdoc_meta "struct mdoc *mdoc"
.Ft int
.Fn mdoc_endparse "struct mdoc *mdoc"
-.\"
+.\" SECTION
.Sh DESCRIPTION
The
.Nm mdoc
-library parses lines of mdoc-macro text into an abstract syntax tree.
+library parses lines of mdoc input into an abstract syntax tree.
+.Dq mdoc
+is a macro package of the
+.Dq roff
+language, which is used to format BSD manual pages. The
+.Nm
+library implements only those macros documented in the
+.Xr mdoc 7
+and
+.Xr mdoc.samples 7
+manuals.
+.\" PARAGRAPH
+.Pp
+.Nm
+is
+.Ud
+.\" PARAGRAPH
+.Pp
In general, applications initiate a parsing sequence with
.Fn mdoc_alloc ,
parse each line in a document with
@@ -48,10 +82,46 @@ then free all allocated memory with
See the
.Sx EXAMPLES
section for a full example.
+.\" PARAGRAPH
.Pp
-.\" Function descriptions.
+This section further defines the
+.Sx Types ,
+.Sx Functions
+and
+.Sx Variables
+available to programmers. The last sub-section,
+.Sx Abstract Syntax Tree ,
+documents the output tree.
+.\" SUBSECTION
+.Ss Types
+Both functions (see
+.Sx Functions )
+and variables (see
+.Sx Variables )
+may use the following types:
+.Bl -ohang
+.\" LIST-ITEM
+.It Vt struct mdoc
+An opaque type defined in
+.Pa mdoc.c .
+Its values are only used privately within the library.
+.\" LIST-ITEM
+.It Vt struct mdoc_cb
+A set of message callbacks defined in
+.Pa mdoc.h .
+.\" LIST-ITEM
+.It Vt struct mdoc_node
+A parsed node. Defined in
+.Pa mdoc.h .
+See
+.Sx Abstract Syntax Tree
+for details.
+.El
+.\" SUBSECTION
+.Ss Functions
Function descriptions follow:
-.Bl -ohang -offset indent
+.Bl -ohang
+.\" LIST-ITEM
.It Fn mdoc_alloc
Allocates a parsing structure. The
.Fa data
@@ -60,20 +130,24 @@ pointer is passed to callbacks in
which are documented further in the header file. Returns NULL on
failure. If non-NULL, the pointer must be freed with
.Fn mdoc_free .
+.\" 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
@@ -88,20 +162,108 @@ or
.Fn mdoc_endparse
return 0, the data will be incomplete.
.El
-.Pp
-.\" Variable descriptions.
+.\" SUBSECTION
+.Ss Variables
The following variables are also defined:
-.Bl -ohang -offset indent
+.Bl -ohang
+.\" LIST-ITEM
.It Va mdoc_macronames
An array of string-ified token names.
+.\" LIST-ITEM
.It Va mdoc_argnames
An array of string-ified token argument names.
.El
-.Pp
+.\" SUBSECTION
+.Ss Abstract Syntax Tree
+The
.Nm
-is
-.Ud
-.\"
+functions produce an abstract syntax tree (AST) describing the input
+lines in a 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
+or
+.Fn mdoc_parseln
+fail, it may be incomplete.
+.\" 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
+.Va type
+field. Each node also provides its parse point (the
+.Va line ,
+.Va sec ,
+and
+.Va pos
+fields), its position in the tree (the
+.Va parent ,
+.Va child ,
+.Va next
+and
+.Va prev
+fields) and type-specific data (the
+.Va data
+field).
+.\" PARAGRAPH
+.Pp
+The tree itself is arranged according to the following normal form,
+where capitalised non-terminals represent nodes.
+.Pp
+.Bl -tag -width "ELEMENTXX" -compact
+.\" LIST-ITEM
+.It ROOT
+\(<- mnode+
+.It mnode
+\(<- BLOCK | ELEMENT | TEXT
+.It BLOCK
+\(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
+.It BLOCK
+\(<- BODY [TEXT] [TAIL [TEXT]]
+.It ELEMENT
+\(<- TEXT*
+.It HEAD
+\(<- mnode+
+.It BODY
+\(<- mnode+
+.It TAIL
+\(<- mnode+
+.It TEXT
+\(<- [[:alpha:]]*
+.El
+.\" PARAGRAPH
+.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 ,
+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
+.Dq \&.Em foo ,
+are classified as ELEMENT nodes, which can only contain text.
+Multi-line elements such as
+.Dq \&.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
+and
+.Dq \&.Sc ,
+are BLOCK elements with no HEAD tag. The only exception to this is
+.Dq \&.Eo
+and
+.Dq \&.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.
+.\" SECTION
.Sh EXAMPLES
The following example reads lines from stdin and parses them, operating
on the finished parse tree with
@@ -135,21 +297,19 @@ if (NULL == (node = mdoc_node(mdoc)))
parsed(mdoc, node);
mdoc_free(mdoc);
.Ed
-.\"
+.\" SECTION
.Sh SEE ALSO
.Xr mdoc 7 ,
.Xr mdoc.samples 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
Bugs, un-implemented macros and incompabilities are documented in this
section. The baseline for determining whether macro parsing is
@@ -189,4 +349,6 @@ for
.Ox
are supported; support for
.Nx
-and other BSD systems is in progress.
+and other
+.Bx
+systems is in progress.