mdoc.3 refers to local mdoc.7.

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

3 files changed, 161 insertions, 214 deletions

diff --git a/argv.c b/argv.c
index 7228e5f4..d745b336 100644
--- a/argv.c
+++ b/argv.c
@@ -60,7 +60,7 @@ enum	merr {
 static	int		 argv_a2arg(int, const char *);
 static	int		 args(struct mdoc *, int, int *, 
 				char *, int, char **);
-static	int		 argv(struct mdoc *, int, int,
+static	int		 argv(struct mdoc *, int, 
 				struct mdoc_argv *, int *, char *);
 static	int		 argv_single(struct mdoc *, int, 
 				struct mdoc_argv *, int *, char *);
@@ -292,7 +292,7 @@ mdoc_argv(struct mdoc *mdoc, int line, int tok,
 
 	/* FIXME: whitespace if no value. */
 
-	if ( ! argv(mdoc, tok, line, &tmp, pos, buf))
+	if ( ! argv(mdoc, line, &tmp, pos, buf))
 		return(ARGV_ERROR);
 
 	if (NULL == (arg = *v)) {
@@ -841,7 +841,7 @@ argv_single(struct mdoc *mdoc, int line,
  * multiple parameters.
  */
 static int
-argv(struct mdoc *mdoc, int tok, int line, 
+argv(struct mdoc *mdoc, int line, 
 		struct mdoc_argv *v, int *pos, char *buf)
 {
 
diff --git a/mdoc.3 b/mdoc.3
index 2feb6d98..6d7ba0e7 100644
--- a/mdoc.3
+++ b/mdoc.3
@@ -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
diff --git a/mdoc.7 b/mdoc.7
index b80119c3..39c9fe56 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -78,12 +78,13 @@ Within a macro line, the following characters are reserved:
 Use of these characters must either be escaped with a non-breaking space
 .Pq Sq \e&
 or, if applicable, an appropriate escape-sequence used.  Use of reserved
-characters is described later in this document.
+characters is described in
+.Sx Closure .
 .\" SUB-SECTION
 .Ss Special Characters
 Special character sequences begin with the escape character
 .Sq \\
-and followed by either an open-parenthesis 
+followed by either an open-parenthesis 
 .Sq \&(
 for two-character sequences; an open-bracket
 .Sq \&[
@@ -93,9 +94,9 @@ or a single one-character sequence.
 .Pp
 Characters may alternatively be escaped by a slash-asterisk,
 .Sq \\* ,
-with the same combinations as described above.  This form, however, is
-deprecated.  The following is a table of all available escapes, arranged
-by classification.  
+with the same combinations as described above.  This form is deprecated.  
+.Pp
+The following is a table of all available escapes.
 .Pp
 Grammatic:
 .Bl -tag -width 12n -offset "XXXX" -compact
@@ -228,16 +229,13 @@ Special symbols:
 .\" SECTION
 .Sh ONTOLOGY
 Macros are classified in an ontology described by scope rules.  
+.\" SUB-SECTION
+.Ss Scope
 .Bl -inset 
 .\" LIST-ITEM
 .It Em Block
 macros enclose other block macros, in-line macros or text, and
-may span multiple lines.  
-.Qq Implicit 
-block scope is closed by a subsequent invocation of the same macro,
-one of a set of corresponding closure macros or end-of-file.
-.Qq Explicit 
-block scope is closed by a corresponding closure macro.
+may span multiple lines.
 .Bl -inset -offset XXXX
 .\" LIST-ITEM
 .It Em Full-block
@@ -259,16 +257,56 @@ text or macros following the head on the same and subsequent lines; and
 optionally a
 .Qq tail ,
 text immediately following closure.
-.El
 .\" LIST-ITEM
 .It Em In-line
-macros may only enclose text and span at most a single line.  If
-a macro is parsable, its scope may be closed by subsequent macros or
-delimiting punctuation.  In-line macros follow different conventions for
-closure; see 
-.Sx MACROS 
-for per-macro details.
+macros may only enclose text and span at most a single line. 
+.El
+.El
+.\" SUB-SECTION
+.Ss Closure
+Closure of a macro's scope depends first on its classification, then
+on whether it's parsable.  In this table,
+.Sq BFE
+refers to block full-explicit and so on.
+.\" PARAGRAPH
+.Pp
+.Bl -tag -width 12n -offset XXXX -compact
+.It BPE , BFE
+corresponding explicit closure macro
+.It BFI
+end-of-file or a corresponding implicit closure macro
+.It BPI
+end-of-line (body may be closed by >0 space-separated
+.Sx Reserved Characters ,
+although block scope will still be open)
+.It INL
+end-of-line
 .El
+.\" PARAGRAPH
+.Pp
+If a macro (block or in-line) is parsable, it may also be closed out by
+one of the following scenarios (unless specifically noted otherwise):
+.\" PARAGRAPH
+.Pp
+.Bl -dash -offset XXXX -compact
+.It 
+a sequence of >0 space-separated
+.Sx Reserved Characters ,
+.It
+another macro,
+.It
+end-of-line, or
+.It
+completion of a set number of arguments.
+.El
+.\" PARAGRAPH
+.Pp
+If >0 space-separated
+.Sx Reserved Characters
+are followed by non-reserved characters, the behaviour differs per
+macro.  In general, scope of the macro is closed and re-opened:
+subsequent tokens are interpreted as if the scope had just been opened.
+In other circumstances, scope is simply closed out.
 .\" .\" SUB-SECTION
 .\" .Ss Examples
 .\" The following examples illustrate each macro classification.
@@ -369,44 +407,47 @@ In these illustrations,
 opens the scope of a macro, and if specified,
 .Sq \&.Yc
 closes it out (closure may be implicit at end-of-line or end-of-file).
+.\" PARAGRAPH
 .Pp
-Block full-explicit (may contain head, body, tail):
+Block full-explicit (may contain head, body, tail).
 .Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
-\(lBbody...\(rB
-\&.Yc \(lBtail...\(rB
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB 
+\(lBbody...\(rB 
+\&.Yc \(lBtail...\(rB 
 .Ed
+.\" PARAGRAPH
 .Pp
-Block full-implicit (may contain zero or more heads, body, no tail):
+Block full-implicit (may contain zero or more heads, body, no tail).
 .Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
-\(lBbody...\(rB
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 
+\(lBbody...\(rB 
 \&.Yc
 .Ed
+.\" PARAGRAPH
 .Pp
-Block partial-explicit (may contain head, multi-line body, tail):
+Block partial-explicit (may contain head, multi-line body, tail).
 .Bd -literal -offset XXXX
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB 
-\(lBbody...\(rB
-\&.Yc \(lBtail...\(rB
+\(lBbody...\(rB 
+\&.Yc \(lBtail...\(rB 
 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
-\(lBbody...\(rB \&Yc \(lBtail...\(rB
+\(lBbody...\(rB \&Yc \(lBtail...\(rB 
 .Ed
+.\" PARAGRAPH
 .Pp
-Block partial-implicit (no head, body, no tail):
+Block partial-implicit (no head, body, no tail).  Note that the body
+section may be followed by zero or more 
+.Sx Reserved Words .
+These are in the block scope, but not in the body scope.
 .Bd -literal -offset XXXX
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
 .Ed
+.\" PARAGRAPH
 .Pp
-In-line (may be closed by end-of-line, reserved character, subsequent
-macro invocation or finite number of arguments):
+In-lines have \(>=0 scoped arguments.
 .Bd -literal -offset XXX
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args...
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... ;
-
-\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... Xx
+\&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
 
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed
@@ -589,17 +630,60 @@ then the macro accepts an arbitrary number of arguments.
 .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
 .El
 .\" SECTION
+.Sh COMPATIBILITY
+The mdoc language was traditionally a 
+.Qq roff
+macro package; most existing manuals were written with mdoc syntax
+dictated by system-dependent roff installations.  This section documents
+compatibility with these systems.
+.Pp
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+.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
+.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
+The system-name macros (
+.Ns Sq \&At ,
+.Sq \&Bsx ,
+.Sq \&Bx ,
+.Sq \&Fx ,
+.Sq \&Nx ,
+.Sq \&Ox ,
+and
+.Sq \&Ux )
+are callable.
+.\" LIST-ITEM
+.It
+Some manuals use
+.Sq \&Li
+incorrectly by following it with a reserved character and expecting the
+delimiter to render.  This is not supported.
+.\" LIST-ITEM
+.It
+.Sq \&Cd
+is callable.
+.El
+.\" SECTION
 .Sh SEE ALSO
 .Xr mdoctree 1 ,
 .Xr mdoclint 1 ,
 .Xr mdocterm 1 ,
 .Xr mdoc 3
 .\" SECTION
-.Sh HISTORY
-This manual describes the language accepted by
-.Xr mdoc 3 ,
-which implements the roff-mdoc macro package.
-.\" SECTION
 .Sh AUTHORS
 The
 .Nm