mdoc.3 refers to local mdoc.7.

mdoc.7 includes its compatibility with system-dependent roff installations.

1 files changed, 33 insertions, 170 deletions

diff --git a/mdoc.3 b/mdoc.3
index 973e86fb..7b858397 100644
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.3,v 1.16 2009/03/12 23:05:21 kristaps Exp $
+.\" $Id: mdoc.3,v 1.17 2009/03/14 05:21:58 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: March 12 2009 $
+.Dd $Mdocdate: March 14 2009 $
 .Dt mdoc 3
 .Os
 .\" SECTION
@@ -49,25 +49,18 @@
 .Sh DESCRIPTION
 The
 .Nm mdoc
-library parses lines of mdoc input into an abstract syntax tree.  
-.Dq mdoc ,
-which is used to format BSD manual pages, is a macro package of the
-.Dq roff
-language.  The
-.Nm
-library implements only those macros documented in the
+library parses lines of 
 .Xr mdoc 7
-and
-.Xr mdoc.samples 7
-manuals.  Documents with 
-.Xr refer 1 ,
-.Xr eqn 1
-and other pre-processor sections aren't accomodated.
-.\" PARAGRAPH
-.Pp
+input (and
+.Em only
+mdoc) into an abstract syntax tree that generalises the semantic
+annotation of its input.  Common front-ends for 
 .Nm
-is
-.Ud
+are
+.Xr mdocterm 1 ,
+.Xr mdoclint 1 
+and
+.Xr mdoctree 1 .
 .\" PARAGRAPH
 .Pp
 In general, applications initiate a parsing sequence with
@@ -92,11 +85,9 @@ This section further defines the
 .Sx Functions 
 and
 .Sx Variables
-available to programmers.  Following that,
-.Sx Character Encoding
-describes input format.  Lastly, 
-.Sx Abstract Syntax Tree ,
-documents the output tree.
+available to programmers.  Following that, the
+.Sx Abstract Syntax Tree 
+section documents the output tree.
 .\" SUBSECTION
 .Ss Types
 Both functions (see
@@ -179,68 +170,11 @@ 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
-functions produce an abstract syntax tree (AST) describing the input
-lines in a regular form.  It may be reviewed at any time with
+functions produce an abstract syntax tree (AST) describing input in a
+regular form.  It may be reviewed at any time with
 .Fn mdoc_nodes ;
 however, if called before
 .Fn mdoc_endparse ,
@@ -248,7 +182,15 @@ or after
 .Fn mdoc_endparse 
 or
 .Fn mdoc_parseln
-fail, it may be incomplete.
+fail, it may be incomplete.  This AST is governed by the ontological
+rules dictated in
+.Xr mdoc 7
+and derives its terminology accordingly.  
+.Qq In-line
+elements described in
+.Xr mdoc 7
+are described simply as 
+.Qq elements .
 .\" PARAGRAPH
 .Pp
 The AST is composed of 
@@ -304,27 +246,6 @@ 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
-The rule-of-thumb for mapping node types to macros follows. In-line
-elements, such as 
-.Sq \&.Em foo ,
-are classified as ELEMENT nodes, which can only contain text.
-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
-.Sq \&.So
-and
-.Sq \&.Sc ,
-are BLOCK elements with no HEAD tag.  The only exception to this is
-.Sq \&.Eo 
-and
-.Sq \&.Ec ,
-which has a HEAD and TAIL node corresponding to the enclosure string.
-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
@@ -360,67 +281,11 @@ 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 system-name macros (
-.Ns Sq \&At ,
-.Sq \&Bsx ,
-.Sq \&Bx ,
-.Sq \&Fx ,
-.Sq \&Nx ,
-.Sq \&Ox ,
-and
-.Sq \&Ux )
-are callable.
-.El
-.\" SECTION
 .Sh SEE ALSO
-.Xr mdoc 7 ,
-.Xr mdoc.samples 7 ,
-.Xr groff 1 ,
-.Xr mdocml 1
+.Xr mdocterm 1 ,
+.Xr mdoclint 1 ,
+.Xr mdoctree 1 ,
+.Xr mdoc 7
 .\" SECTION
 .Sh AUTHORS
 The
@@ -429,7 +294,7 @@ utility was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS
-.Bl -bullet
+.Bl -dash -compact
 .\" LIST-ITEM
 .It
 The 
@@ -438,12 +303,10 @@ and
 .Sq \&Xo
 macros aren't handled when used to span lines for the
 .Sq \&It
-macro.  Such usage is specifically discouraged in
-.Xr mdoc.samples 7 .
+macro. 
 .\" LIST-ITEM
 .It
 The 
 .Sq \&Bsx
-macro doesn't understand yet the arguments as dictated for 
-.Nx .
+macro doesn't yet understand version arguments.
 .El