Add more documentation for libmandoc.

diff --git a/mandoc.3 b/mandoc.3
index 300f2981bb475072a89cb1569e92df621214da5c..16aa612585aaae7c0b03fe4cc8e6aacb2ecb158b 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.10 2011/05/24 21:41:11 kristaps Exp $
+.\"    $Id: mandoc.3,v 1.11 2011/06/22 22:10:02 kristaps Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: May 24 2011 $
+.Dd $Mdocdate: June 22 2011 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Dt MANDOC 3
 .Os
 .Sh NAME


@@ -177,9 +177,6 @@ library also contains routines for translating character strings into glyphs
 .Pq see Fn mchars_alloc
 and parsing escape sequences from strings
 .Pq see Fn mandoc_escape .
 .Pq see Fn mchars_alloc
 and parsing escape sequences from strings
 .Pq see Fn mandoc_escape .

-.Pp
-This library is
-.Ud

 .Sh REFERENCE
 This section documents the functions, types, and variables available
 via
 .Sh REFERENCE
 This section documents the functions, types, and variables available
 via


@@ -187,16 +184,35 @@ via
 .Ss Types
 .Bl -ohang
 .It Vt "enum mandoc_esc"
 .Ss Types
 .Bl -ohang
 .It Vt "enum mandoc_esc"

+An escape sequence classification.

 .It Vt "enum mandocerr"
 .It Vt "enum mandocerr"

+A fatal error, error, or warning message during parsing.

 .It Vt "enum mandoclevel"
 .It Vt "enum mandoclevel"

+A classification of an
+.Vt "enum mandoclevel"
+as regards system operation.

 .It Vt "struct mchars"
 An opaque pointer to an object allowing for translation between
 character strings and glyphs.
 See
 .Fn mchars_alloc .
 .It Vt "enum mparset"
 .It Vt "struct mchars"
 An opaque pointer to an object allowing for translation between
 character strings and glyphs.
 See
 .Fn mchars_alloc .
 .It Vt "enum mparset"

+The type of parser when reading input.
+This should usually be
+.Va MPARSE_AUTO
+for auto-detection.

 .It Vt "struct mparse"
 .It Vt "struct mparse"

+An opaque pointer to a running parse sequence.
+Created with
+.Fn mparse_alloc
+and freed with
+.Fn mparse_free .
+This may be used across parsed input if
+.Fn mparse_reset
+is called between parses.

 .It Vt "mandocmsg"
 .It Vt "mandocmsg"

+A prototype for a function to handle fatal error, error, and warning
+messages emitted by the parser.

 .El
 .Ss Functions
 .Bl -ohang
 .El
 .Ss Functions
 .Bl -ohang


@@ -320,7 +336,36 @@ This section consists of structural documentation for
 .Xr mdoc 7
 and
 .Xr man 7
 .Xr mdoc 7
 and
 .Xr man 7

-syntax trees.
+syntax trees and strings.
+.Ss Man and Mdoc Strings
+Strings may be extracted from mdoc and man meta-data, or from text
+nodes (MDOC_TEXT and MAN_TEXT, respectively).
+These strings have special non-printing formatting cues embedded in the
+text itself, as well as
+.Xr roff 7
+escapes preserved from input.
+Implementing systems will need to handle both situations to produce
+human-readable text.
+In general, strings may be assumed to consist of 7-bit ASCII characters.
+.Pp
+The following non-printing characters may be embedded in text strings:
+.Bl -tag -width Ds
+.It Dv ASCII_NBRSP
+A non-breaking space character.
+.It Dv ASCII_HYPH
+A soft hyphen.
+.El
+.Pp
+Escape characters are also passed verbatim into text strings.
+An escape character is a sequence of characters beginning with the
+backslash
+.Pq Sq \e .
+To construct human-readable text, these should be intercepted with
+.Fn mandoc_escape
+and converted with one of
+.Fn mchars_num2char ,
+.Fn mchars_spec2str ,
+and so on.

 .Ss Man Abstract Syntax Tree
 This AST is governed by the ontological rules dictated in
 .Xr man 7
 .Ss Man Abstract Syntax Tree
 This AST is governed by the ontological rules dictated in
 .Xr man 7


@@ -361,7 +406,7 @@ where capitalised non-terminals represent nodes.
 .It ELEMENT
 \(<- ELEMENT | TEXT*
 .It TEXT
 .It ELEMENT
 \(<- ELEMENT | TEXT*
 .It TEXT

-\(<- [[:alpha:]]*
+\(<- [[:ascii:]]*

 .El
 .Pp
 The only elements capable of nesting other elements are those with
 .El
 .Pp
 The only elements capable of nesting other elements are those with


@@ -420,7 +465,7 @@ where capitalised non-terminals represent nodes.
 .It TAIL
 \(<- mnode*
 .It TEXT
 .It TAIL
 \(<- mnode*
 .It TEXT

-\(<- [[:printable:],0x1e]*
+\(<- [[:ascii:]]*

 .El
 .Pp
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 .El
 .Pp
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of