summaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2009-03-14 05:21:58 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2009-03-14 05:21:58 +0000
commitdd296a1678ea613037cf62e6186201645adb26dc (patch)
tree673afab35a710bb25bfc306217970cd4e0f00bc2
parent8e37e41aceb3299a93379ef910ac09f41fb2f59b (diff)
downloadmandoc-dd296a1678ea613037cf62e6186201645adb26dc.tar.gz
mandoc-dd296a1678ea613037cf62e6186201645adb26dc.tar.zst
mandoc-dd296a1678ea613037cf62e6186201645adb26dc.zip
mdoc.3 refers to local mdoc.7.
mdoc.7 includes its compatibility with system-dependent roff installations.
-rw-r--r--argv.c8
-rw-r--r--mdoc.3203
-rw-r--r--mdoc.7174
3 files changed, 166 insertions, 219 deletions
diff --git a/argv.c b/argv.c
index fa9f5cf5..572d9590 100644
--- a/argv.c
+++ b/argv.c
@@ -1,4 +1,4 @@
-/* $Id: argv.c,v 1.50 2009/03/12 16:30:50 kristaps Exp $ */
+/* $Id: argv.c,v 1.51 2009/03/14 05:21:58 kristaps Exp $ */
/*
* Copyright (c) 2008 Kristaps Dzonsons <kristaps@kth.se>
*
@@ -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 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
diff --git a/mdoc.7 b/mdoc.7
index 72ad225c..2d66c1f0 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.3 2009/03/13 13:56:13 kristaps Exp $
+.\" $Id: mdoc.7,v 1.4 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 13 2009 $
+.Dd $Mdocdate: March 14 2009 $
.Dt mdoc 7
.Os
.\" SECTION
@@ -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