===================================================================
RCS file: /cvs/mandoc/Attic/mdoc.3,v
retrieving revision 1.9
retrieving revision 1.15
diff -u -p -r1.9 -r1.15
--- mandoc/Attic/mdoc.3	2009/02/23 15:19:47	1.9
+++ mandoc/Attic/mdoc.3	2009/03/12 16:30:50	1.15
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.3,v 1.9 2009/02/23 15:19:47 kristaps Exp $
+.\" $Id: mdoc.3,v 1.15 2009/03/12 16:30:50 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: March 12 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
@@ -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
@@ -298,6 +360,58 @@ parsed(mdoc, node);
 mdoc_free(mdoc);
 .Ed
 .\" SECTION
+.Sh COMPATIBILITY
+In general, only those macros specified by
+.Xr mdoc.samples 7
+and
+.Xr mdoc 7
+for
+.Ox
+and
+.Nx
+are supported; support for other 
+.Bx
+systems is in progress.
+.Bl -bullet
+.\" LIST-ITEM
+.It
+.Sq \&Cd
+isn't labelled as callable but is.
+.\" LIST-ITEM
+.It
+NetBSD
+.Sq \&It \-nested
+is assumed for all lists: any list may be nested and
+.Sq \-enum
+lists will restart the sequence only for the sub-list.
+.\" LIST-ITEM
+.It
+Newer NetBSD-style
+.Sq \&It \-column
+syntax, where column widths may be preceeded by other arguments (instead
+of proceeded), is not supported.
+.\" LIST-ITEM
+.It
+The 
+.Sq \&At
+macro only accepts a single parameter.
+.\" LIST-ITEM
+.It
+Some manuals use
+.Sq \&Li
+incorrectly by following it with a delimeter (see
+.Xr mdoc.samples 7 )
+and expecting the delimiter to render.  This is not supported.
+.\" LIST-ITEM
+.It
+The 
+.Sq Bx
+family of macros (
+.Sq Ux ,
+.Sq Nx
+and so on) are not callable as they are in NetBSD.
+.El
+.\" SECTION
 .Sh SEE ALSO
 .Xr mdoc 7 ,
 .Xr mdoc.samples 7 ,
@@ -310,17 +424,11 @@ The
 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 
-.Qq incompatible
-is the default
-.Xr groff 1
-system bundled with 
-.Ox .
-.\" PARAGRAPH
-.Pp
-Un-implemented: the 
+.Sh CAVEATS
+.Bl -bullet
+.\" LIST-ITEM
+.It
+The 
 .Sq \&Xc
 and
 .Sq \&Xo
@@ -328,36 +436,4 @@ 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
-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.
+.El