summaryrefslogtreecommitdiffstats
path: root/mdoc.7
diff options
context:
space:
mode:
Diffstat (limited to 'mdoc.7')
-rw-r--r--mdoc.7170
1 files changed, 127 insertions, 43 deletions
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