Memory-corruption fix.

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index fbab170633bdfbace9fbda15dfbcc1ed587bf31c..226895b9e9e09be03aaad48b46b36b1972af8e9f 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.3,v 1.7 2009/02/23 09:46:59 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+


@@ -238,31 +300,31 @@ where capitalised non-terminals represent nodes.
 .Pp
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 .Pp
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 the BLOCK production.  These refer to punctuation marks.  Furthermore,

-although a TEXT node will generally have a non-zero-length string, it
-certain cases, such as 
-.Dq \&.Bd \-literal ,
+although a TEXT node will generally have a non-zero-length string, in
+the specific case of 
+.Sq \&.Bd \-literal ,

 an empty line will produce a zero-length string.
 .\" PARAGRAPH
 .Pp
 an empty line will produce a zero-length string.
 .\" PARAGRAPH
 .Pp

-The rule-of-thumb for mapping node types to macros follows: in-line
+The rule-of-thumb for mapping node types to macros follows. In-line

 elements, such as 
 elements, such as 

-.Dq \&.Em foo ,
+.Sq \&.Em foo ,

 are classified as ELEMENT nodes, which can only contain text.
 are classified as ELEMENT nodes, which can only contain text.

-Multi-line elements such as
-.Dq \&.Sh
+Multi-line elements, such as
+.Sq \&.Sh ,

 are BLOCK elements, where the HEAD constitutes line contents and the
 BODY constitutes subsequent lines.  In-line elements with matching
 pairs, such as
 are BLOCK elements, where the HEAD constitutes line contents and the
 BODY constitutes subsequent lines.  In-line elements with matching
 pairs, such as

-.Dq \&.So
+.Sq \&.So

 and
 and

-.Dq \&.Sc ,
+.Sq \&.Sc ,

 are BLOCK elements with no HEAD tag.  The only exception to this is
 are BLOCK elements with no HEAD tag.  The only exception to this is

-.Dq \&.Eo 
+.Sq \&.Eo 

 and
 and

-.Dq \&.Ec ,
+.Sq \&.Ec ,

 which has a HEAD and TAIL node corresponding to the enclosure string.
 which has a HEAD and TAIL node corresponding to the enclosure string.

-TEXT nodes, obviously, constitute text; the ROOT node is the document's
-root.
+TEXT nodes, obviously, constitute text, and the ROOT node is the
+document's root.

 .\" SECTION
 .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating
 .\" SECTION
 .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating


@@ -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