mdocterm now using new API.

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index ae2e12c38382384f1854256373f56717b0fb0214..226895b9e9e09be03aaad48b46b36b1972af8e9f 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.3,v 1.8 2009/02/23 12:45:19 kristaps Exp $
+.\" $Id: mdoc.3,v 1.13 2009/02/27 09:14:02 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -16,7 +16,7 @@
 .\" 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
@@ -59,7 +59,10 @@ library implements only those macros documented in the
 .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
@@ -89,7 +92,9 @@ This section further defines the
 .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
@@ -99,7 +104,7 @@ Both functions (see
 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
@@ -120,7 +125,7 @@ for details.
 .\" SUBSECTION
 .Ss Functions
 Function descriptions follow:
-.Bl -ohang 
+.Bl -ohang -offset "XXXX"
 .\" LIST-ITEM
 .It Fn mdoc_alloc
 Allocates a parsing structure.  The
@@ -165,7 +170,7 @@ return 0, the data will be incomplete.
 .\" 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.
@@ -174,6 +179,63 @@ 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
@@ -213,7 +275,7 @@ field).
 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+
@@ -272,7 +334,7 @@ Note that, if the last line of the file isn't newline-terminated, this
 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;
@@ -318,6 +380,7 @@ is the default
 .Xr groff 1
 system bundled with 
 .Ox .
+.\" PARAGRAPH
 .Pp
 Un-implemented: the 
 .Sq \&Xc
@@ -327,12 +390,19 @@ macros aren't handled when used to span lines for the
 .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
@@ -340,6 +410,7 @@ 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