summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--mdoc.7280
1 files changed, 170 insertions, 110 deletions
diff --git a/mdoc.7 b/mdoc.7
index b4869830..1387e659 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -49,36 +49,35 @@ All manuals must have
.Sq \en
line termination.
.\" SUB-SECTION
-.Ss Special Characters
-Within a macro line, the following characters are special:
-.\" PARAGRAPH
-.Pp
-.Bl -tag -width Ds -offset XXXX -compact
+.Ss Reserved Characters
+Within a macro line, the following characters are reserved:
+.Bl -tag -width 12n -offset XXXX -compact
.It \&.
-period
+.Pq period
.It \&,
-comma
+.Pq comma
.It \&:
-colon
+.Pq colon
.It \&;
-semicolon
+.Pq semicolon
.It \&(
-left-parenthesis
+.Pq left-parenthesis
.It \&)
-right-parenthesis
+.Pq right-parenthesis
.It \&[
-left-bracket
+.Pq left-bracket
.It \&]
-right-bracket
+.Pq right-bracket
.It \&?
-question
+.Pq question
.It \&!
-exclmamation
+.Pq exclmamation
.El
.Pp
Use of these characters must either be escaped with a non-breaking space
.Pq Sq \e&
-or, if applicable, an appropriate escape-sequence used.
+or, if applicable, an appropriate escape-sequence used. Use of reserved
+characters is described later in this document.
.\" SUB-SECTION
.Ss Special Characters
Special character sequences begin with the escape character
@@ -98,7 +97,6 @@ deprecated. The following is a table of all available escapes, arranged
by classification.
.Pp
Grammatic:
-.Pp
.Bl -tag -width 12n -offset "XXXX" -compact
.It \\(em
.Pq em-dash
@@ -120,7 +118,6 @@ Grammatic:
.\" PARAGRAPH
.Pp
Enclosures:
-.Pp
.Bl -tag -width 12n -offset "XXXX" -compact
.It \\(rC
.Pq right brace
@@ -152,7 +149,6 @@ Enclosures:
.\" PARAGRAPH
.Pp
Indicatives:
-.Pp
.Bl -tag -width 12n -offset "XXXX" -compact
.It \\(<-
.Pq left arrow
@@ -166,7 +162,6 @@ Indicatives:
.\" PARAGRAPH
.Pp
Mathematical:
-.Pp
.Bl -tag -width 12n -offset "XXXX" -compact
.It \\(Gt
.Pq greater-than, deprecated
@@ -204,7 +199,6 @@ Mathematical:
.\" PARAGRAPH
.Pp
Diacritics:
-.Pp
.Bl -tag -width 12n -offset "XXXX" -compact
.It \\(ga
.Pq accent grave
@@ -214,7 +208,6 @@ Diacritics:
.\" PARAGRAPH
.Pp
Special symbols:
-.Pp
.Bl -tag -width 12n -offset "XXXX" -compact
.It \\(bu
.Pq bullet
@@ -232,22 +225,23 @@ Special symbols:
.Pq ampersand, deprecated
.El
.\" SECTION
-.Sh CLASSIFICATION
+.Sh ONTOLOGY
Macros are classified in an ontology described by scope rules.
-.Bl -tag -width "in-lineX"
+.Bl -inset
.\" LIST-ITEM
.It Em Block
-Block macros enclose other block macros, in-line macros or text, and
+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.
-.Bl -tag -width "partial-blockX"
+.Bl -inset -offset XXXX
.\" LIST-ITEM
.It Em Full-block
-Always spans multiple lines. Consists optionally of one or more
+macros always span multiple lines. They consist optionally of one or
+more
.Qq heads ,
subsequent macros or text on the same line following invocation; a
.Qq body ,
@@ -256,7 +250,7 @@ which spans subsequent lines of text or macros; and an optional
macros or text on the same line following closure.
.\" LIST-ITEM
.It Em Partial-block
-May span multiple lines. Consists optionally of a
+macros may span multiple lines. They consists optionally of a
.Qq head ,
text immediately following invocation; always a
.Qq body ,
@@ -267,7 +261,7 @@ text immediately following closure.
.El
.\" LIST-ITEM
.It Em In-line
-In-line macros may only enclose text and span at most a single line. If
+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
@@ -364,14 +358,65 @@ for per-macro details.
.\" \&.Fl text0 text1 ; Ar text0 text1
.\" .Ed
.\" SECTION
+.Sh SYNTAX
+The syntax of macro invocation depends on classification.
+.Qq \-arg
+refers to the macro arguments (which may contain zero or more values).
+In these illustrations,
+.Sq \&.Yo
+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).
+.Pp
+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
+.Ed
+.Pp
+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
+\&.Yc
+.Ed
+.Pp
+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
+
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
+\(lBbody...\(rB \&Yc \(lBtail...\(rB
+.Ed
+.Pp
+Block partial-implicit (no head, body, no tail):
+.Bd -literal -offset XXXX
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB
+.Ed
+.Pp
+In-line (may be closed by end-of-line, reserved character, subsequent
+macro invocation or finite number of 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 arg0 arg1 argN
+.Ed
+.\"
.Sh MACROS
This section contains a complete list of all
.Nm
-macros, arranged ontologically then alphanumerically by macro name. A
+macros, arranged ontologically. A
.Qq callable
macro is may be invoked subsequent to the initial macro-line macro. A
.Qq parsable
-macro May be followed by further (ostensibly callable) macros.
+macro may be followed by further (ostensibly callable) macros.
.\" SUB-SECTION
.Ss Block full-implicit
The head of these macros follows invocation; the body is the content of
@@ -381,7 +426,8 @@ some
.Sq \&It \-bullet ,
.Sq \-hyphen ,
.Sq \-dash ,
-.Sq \-enum
+.Sq \-enum ,
+.Sq \-item
.Pc
don't have heads.
.Pp
@@ -405,6 +451,8 @@ the explicit scope rules. All contains bodies, some may contain heads
.It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
.It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
.It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
+.It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
+.It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
.El
.\" SUB-SECTION
.Ss Block partial-implicit
@@ -421,6 +469,9 @@ close at the invocation's end-of-line.
.It \&.Qq Ta Yes Ta Yes
.It \&.Sq Ta Yes Ta Yes
.It \&.Brq Ta Yes Ta Yes
+.It \&.D1 Ta \&No Ta \&Yes
+.It \&.Dl Ta \&No Ta Yes
+.It \&.Ql Ta Yes Ta Yes
.El
.\" SUB-SECTION
.Ss Block partial-explicit
@@ -454,84 +505,93 @@ and/or tail
.It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
.It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
.It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
+.It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
+.It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
.El
.\" SUB-SECTION
-.Ss General
-.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
-.It Em Macro Ta Em Callable Ta Em Parsable
-.It \&.Dd Ta \& Ta \&
-.It \&.Dt Ta \& Ta \&
-.It \&.Os Ta \& Ta \&
-.It \&.Pp Ta \& Ta \&
-.It \&.D1 Ta \& Ta \&
-.It \&.Dl Ta \& Ta Yes
-.It \&.Ad Ta Yes Ta Yes
-.It \&.An Ta \& Ta Yes
-.It \&.Ar Ta Yes Ta Yes
-.It \&.Cd Ta Yes Ta \&
-.It \&.Cm Ta Yes Ta Yes
-.It \&.Dv Ta Yes Ta Yes
-.It \&.Er Ta Yes Ta Yes
-.It \&.Ev Ta Yes Ta Yes
-.It \&.Ex Ta \& Ta \&
-.It \&.Fa Ta Yes Ta Yes
-.It \&.Fd Ta \& Ta \&
-.It \&.Fl Ta Yes Ta Yes
-.It \&.Fn Ta Yes Ta Yes
-.It \&.Ft Ta \& Ta \&
-.It \&.Ic Ta Yes Ta Yes
-.It \&.In Ta \& Ta \&
-.It \&.Li Ta Yes Ta Yes
-.It \&.Nd Ta \& Ta \&
-.It \&.Nm Ta Yes Ta Yes
-.It \&.Ot Ta \& Ta \&
-.It \&.Pa Ta Yes Ta Yes
-.It \&.Rv Ta \& Ta \&
-.It \&.St Ta Yes Ta \&
-.It \&.Va Ta Yes Ta Yes
-.It \&.Vt Ta Yes Ta Yes
-.It \&.Xr Ta Yes Ta Yes
-.It \&.%A Ta \& Ta \&
-.It \&.%B Ta \& Ta \&
-.It \&.%C Ta \& Ta \&
-.It \&.%D Ta \& Ta \&
-.It \&.%I Ta \& Ta \&
-.It \&.%J Ta \& Ta \&
-.It \&.%N Ta \& Ta \&
-.It \&.%O Ta \& Ta \&
-.It \&.%P Ta \& Ta \&
-.It \&.%R Ta \& Ta \&
-.It \&.%T Ta \& Ta \&
-.It \&.%V Ta \& Ta \&
-.It \&.At Ta Yes Ta Yes
-.It \&.Bsx Ta Yes Ta Yes
-.It \&.Bx Ta Yes Ta Yes
-.It \&.Db Ta \& Ta \&
-.It \&.Em Ta Yes Ta Yes
-.It \&.Fx Ta Yes Ta Yes
-.It \&.Ms Ta \& Ta Yes
-.It \&.No Ta Yes Ta Yes
-.It \&.Ns Ta Yes Ta Yes
-.It \&.Nx Ta Yes Ta Yes
-.It \&.Ox Ta Yes Ta Yes
-.It \&.Pf Ta \& Ta Yes
-.It \&.Ql Ta Yes Ta Yes
-.It \&.Re Ta \& Ta \&
-.It \&.Rs Ta \& Ta \&
-.It \&.Sm Ta \& Ta \&
-.It \&.Sx Ta Yes Ta Yes
-.It \&.Sy Ta Yes Ta Yes
-.It \&.Tn Ta Yes Ta Yes
-.It \&.Ux Ta Yes Ta Yes
-.It \&.Bk Ta \& Ta \&
-.It \&.Ek Ta \& Ta \&
-.It \&.Bt Ta \& Ta \&
-.It \&.Hf Ta \& Ta \&
-.It \&.Fr Ta \& Ta \&
-.It \&.Ud Ta \& Ta \&
-.It \&.Lb Ta \& Ta \&
-.It \&.Ap Ta Yes Ta Yes
-.It \&.Lp Ta \& Ta \&
-.It \&.Lk Ta \& Ta Yes
-.It \&.Mt Ta \& Ta Yes
+.Ss In-line
+In-line macros have only text children.
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
+.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
+.It \&.Dd Ta \&No Ta \&No Ta \&
+.It \&.Dt Ta \&No Ta \&No Ta \&
+.It \&.Os Ta \&No Ta \&No Ta \&
+.It \&.Pp Ta \&No Ta \&No Ta 0
+.It \&.Ad Ta Yes Ta Yes Ta \&
+.It \&.An Ta \&No Ta Yes Ta \&
+.It \&.Ar Ta Yes Ta Yes Ta \&
+.It \&.Cd Ta Yes Ta \&No Ta \&
+.It \&.Cm Ta Yes Ta Yes Ta \&
+.It \&.Dv Ta Yes Ta Yes Ta \&
+.It \&.Er Ta Yes Ta Yes Ta \&
+.It \&.Ev Ta Yes Ta Yes Ta \&
+.It \&.Ex Ta \&No Ta \&No Ta \&
+.It \&.Fa Ta Yes Ta Yes Ta \&
+.It \&.Fd Ta \&No Ta \&No Ta \&
+.It \&.Fl Ta Yes Ta Yes Ta \&
+.It \&.Fn Ta Yes Ta Yes Ta \&
+.It \&.Ft Ta \&No Ta Yes Ta \&
+.It \&.Ic Ta Yes Ta Yes Ta \&
+.It \&.In Ta \&No Ta \&No Ta \&
+.It \&.Li Ta Yes Ta Yes Ta \&
+.It \&.Nd Ta \&No Ta \&No Ta \&
+.It \&.Nm Ta Yes Ta Yes Ta \&
+.It \&.Ot Ta \&No Ta \&No Ta \&
+.It \&.Pa Ta Yes Ta Yes Ta \&
+.It \&.Rv Ta \&No Ta \&No Ta \&
+.It \&.St Ta \&No Ta Yes Ta \&
+.It \&.Va Ta Yes Ta Yes Ta \&
+.It \&.Vt Ta Yes Ta Yes Ta \&
+.It \&.Xr Ta Yes Ta Yes Ta \&
+.It \&.%A Ta \&No Ta \&No Ta \&
+.It \&.%B Ta \&No Ta \&No Ta \&
+.It \&.%C Ta \&No Ta \&No Ta \&
+.It \&.%D Ta \&No Ta \&No Ta \&
+.It \&.%I Ta \&No Ta \&No Ta \&
+.It \&.%J Ta \&No Ta \&No Ta \&
+.It \&.%N Ta \&No Ta \&No Ta \&
+.It \&.%O Ta \&No Ta \&No Ta \&
+.It \&.%P Ta \&No Ta \&No Ta \&
+.It \&.%R Ta \&No Ta \&No Ta \&
+.It \&.%T Ta \&No Ta \&No Ta \&
+.It \&.%V Ta \&No Ta \&No Ta \&
+.It \&.At Ta Yes Ta Yes Ta \&
+.It \&.Bsx Ta Yes Ta Yes Ta \&
+.It \&.Bx Ta Yes Ta Yes Ta \&
+.It \&.Db Ta \&No Ta \&No Ta \&
+.It \&.Em Ta Yes Ta Yes Ta \&
+.It \&.Fx Ta Yes Ta Yes Ta \&
+.It \&.Ms Ta \&No Ta Yes Ta \&
+.It \&.No Ta Yes Ta Yes Ta \&
+.It \&.Ns Ta Yes Ta Yes Ta \&
+.It \&.Nx Ta Yes Ta Yes Ta \&
+.It \&.Ox Ta Yes Ta Yes Ta \&
+.It \&.Pf Ta \&No Ta Yes Ta \&
+.It \&.Sm Ta \&No Ta \&No Ta \&
+.It \&.Sx Ta Yes Ta Yes Ta \&
+.It \&.Sy Ta Yes Ta Yes Ta \&
+.It \&.Tn Ta Yes Ta Yes Ta \&
+.It \&.Ux Ta Yes Ta Yes Ta \&
+.It \&.Bt Ta \&No Ta \&No Ta \&
+.It \&.Hf Ta \&No Ta \&No Ta \&
+.It \&.Fr Ta \&No Ta \&No Ta \&
+.It \&.Ud Ta \&No Ta \&No Ta \&
+.It \&.Lb Ta \&No Ta \&No Ta \&
+.It \&.Ap Ta Yes Ta Yes Ta \&
+.It \&.Lp Ta \&No Ta \&No Ta \&
+.It \&.Lk Ta \&No Ta Yes Ta \&
+.It \&.Mt Ta \&No Ta Yes Ta \&
.El
+.\" SECTION
+.Sh SEE ALSO
+.Xr mdoctree 1 ,
+.Xr mdoclint 1 ,
+.Xr mdocterm 1 ,
+.Xr mdoc 3
+.\" SECTION
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Kristaps Dzonsons Aq kristaps@kth.se .