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>
 .\"
 .\"
 .\" 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


@@ -99,7 +104,7 @@ Both functions (see
 and variables (see
 .Sx Variables )
 may use the following types:
 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
 .\" LIST-ITEM
 .It Vt struct mdoc
 An opaque type defined in


@@ -120,7 +125,7 @@ for details.
 .\" SUBSECTION
 .Ss Functions
 Function descriptions follow:
 .\" SUBSECTION
 .Ss Functions
 Function descriptions follow:

-.Bl -ohang 
+.Bl -ohang -offset "XXXX"

 .\" LIST-ITEM
 .It Fn mdoc_alloc
 Allocates a parsing structure.  The
 .\" 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:
 .\" 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.
 .\" 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
 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


@@ -213,7 +275,7 @@ field).
 The tree itself is arranged according to the following normal form,
 where capitalised non-terminals represent nodes.
 .Pp
 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+
 .\" 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.
 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;
 struct mdoc *mdoc;
 struct mdoc_node *node;
 char *buf;


@@ -318,6 +380,7 @@ is the default
 .Xr groff 1
 system bundled with 
 .Ox .
 .Xr groff 1
 system bundled with 
 .Ox .

+.\" PARAGRAPH

 .Pp
 Un-implemented: the 
 .Sq \&Xc
 .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 .
 .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.
 .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
 .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.
 .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
 .Pp
 Incompatible: only those macros specified by
 .Xr mdoc.samples 7