Added more character-escape regressions.

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index 059d8cf5973857240c22451f4b5545a958cff553..226895b9e9e09be03aaad48b46b36b1972af8e9f 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.3,v 1.9 2009/02/23 15:19:47 kristaps Exp $
+.\" $Id: mdoc.3,v 1.13 2009/02/27 09:14:02 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\"
 .\" 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.
 .\" 
 .\" 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
 .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
 .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
 .\" PARAGRAPH
 .Pp
 .Nm


@@ -89,7 +92,9 @@ This section further defines the
 .Sx Functions 
 and
 .Sx Variables
 .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
 .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
 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
 .Ss Abstract Syntax Tree
 The 
 .Nm