summaryrefslogtreecommitdiffstats
path: root/mdoc.7
diff options
context:
space:
mode:
Diffstat (limited to 'mdoc.7')
-rw-r--r--mdoc.7281
1 files changed, 183 insertions, 98 deletions
diff --git a/mdoc.7 b/mdoc.7
index 39c9fe56..74b86a62 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -72,14 +72,16 @@ Within a macro line, the following characters are reserved:
.It \&?
.Pq question
.It \&!
-.Pq exclmamation
+.Pq exclamation
.El
+.\" PARAGRAPH
.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. Use of reserved
-characters is described in
+Use of reserved characters is described in
.Sx Closure .
+For general non-reserved use, characters must either be escaped with a
+non-breaking space
+.Pq Sq \e&
+or, if applicable, an appropriate escape-sequence used.
.\" SUB-SECTION
.Ss Special Characters
Special character sequences begin with the escape character
@@ -121,6 +123,14 @@ Grammatic:
.Pp
Enclosures:
.Bl -tag -width 12n -offset "XXXX" -compact
+.It \\(lh
+.Pq left hand
+.It \\(rh
+.Pq right hand
+.It \\(<<
+.Pq left guillemot
+.It \\(>>
+.Pq right guillemot
.It \\(rC
.Pq right brace
.It \\(lC
@@ -160,6 +170,18 @@ Indicatives:
.Pq up arrow
.It \\(da
.Pq down arrow
+.It \\(<>
+.Pq left-right arrow
+.It \\(lA
+.Pq left double-arrow
+.It \\(rA
+.Pq right double-arrow
+.It \\(uA
+.Pq up double-arrow
+.It \\(dA
+.Pq down double-arrow
+.It \\(hA
+.Pq left-right double-arrow
.El
.\" PARAGRAPH
.Pp
@@ -200,12 +222,98 @@ Mathematical:
.El
.\" PARAGRAPH
.Pp
-Diacritics:
+Diacritics and letter combinations:
.Bl -tag -width 12n -offset "XXXX" -compact
.It \\(ga
.Pq accent grave
.It \\(aa
.Pq accent accute
+.It \\(ad
+.Pq accent dieresis
+.It \\(a~
+.Pq accent tilde
+.It \\(AE
+.Pq upper-case AE
+.It \\(ae
+.Pq lower-case AE
+.It \\(OE
+.Pq upper-case OE
+.It \\(oe
+.Pq lower-case OE
+.It \\('A
+.Pq upper-case acute A
+.It \\('E
+.Pq upper-case acute E
+.It \\('I
+.Pq upper-case acute I
+.It \\('O
+.Pq upper-case acute O
+.It \\('U
+.Pq upper-case acute U
+.It \\('a
+.Pq lower-case acute a
+.It \\('e
+.Pq lower-case acute e
+.It \\('i
+.Pq lower-case acute i
+.It \\('o
+.Pq lower-case acute o
+.It \\('u
+.Pq lower-case acute u
+.It \\(`A
+.Pq upper-case grave A
+.It \\(`E
+.Pq upper-case grave E
+.It \\(`I
+.Pq upper-case grave I
+.It \\(`O
+.Pq upper-case grave O
+.It \\(`U
+.Pq upper-case grave U
+.It \\(`a
+.Pq lower-case grave a
+.It \\(`e
+.Pq lower-case grave e
+.It \\(`i
+.Pq lower-case grave i
+.It \\(`o
+.Pq lower-case grave o
+.It \\(`u
+.Pq lower-case grave u
+.It \\(~A
+.Pq upper-case tilde A
+.It \\(~N
+.Pq upper-case tilde N
+.It \\(~O
+.Pq upper-case tilde O
+.It \\(~a
+.Pq lower-case tilde a
+.It \\(~n
+.Pq lower-case tilde n
+.It \\(~o
+.Pq lower-case tilde o
+.It \\(:A
+.Pq upper-case dieresis A
+.It \\(:E
+.Pq upper-case dieresis E
+.It \\(:I
+.Pq upper-case dieresis I
+.It \\(:O
+.Pq upper-case dieresis O
+.It \\(:U
+.Pq upper-case dieresis U
+.It \\(:a
+.Pq lower-case dieresis a
+.It \\(:e
+.Pq lower-case dieresis e
+.It \\(:i
+.Pq lower-case dieresis i
+.It \\(:o
+.Pq lower-case dieresis o
+.It \\(:u
+.Pq lower-case dieresis u
+.It \\(:y
+.Pq lower-case dieresis y
.El
.\" PARAGRAPH
.Pp
@@ -219,6 +327,10 @@ Special symbols:
.Pq bar, deprecated
.It \\(co
.Pq copyright
+.It \\(rg
+.Pq registered
+.It \\(tm
+.Pq trademarked
.It \\&
.Pq non-breaking space
.It \\e
@@ -239,17 +351,18 @@ may span multiple lines.
.Bl -inset -offset XXXX
.\" LIST-ITEM
.It Em Full-block
-macros always span multiple lines. They consist optionally of one or
+macros always span multiple lines. They consist of zero or
more
.Qq heads ,
-subsequent macros or text on the same line following invocation; a
+subsequent macros or text on the same line following invocation; an
+optional
.Qq body ,
which spans subsequent lines of text or macros; and an optional
.Qq tail ,
macros or text on the same line following closure.
.\" LIST-ITEM
.It Em Partial-block
-macros may span multiple lines. They consists optionally of a
+macros may span multiple lines. They consists of a optional
.Qq head ,
text immediately following invocation; always a
.Qq body ,
@@ -307,95 +420,6 @@ 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.
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit full-block. Has head, body and no tail. Scope closed by
-.\" second
-.\" .Sq \&Sh
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Sh SECTION 1
-.\" body...
-.\" \&.Sh SECTION 2
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Nested implicit full-block, where the subsection
-.\" .Sq \&Ss
-.\" is within the scope of the parent section
-.\" .Sq \&Sh
-.\" and closed along with its parent by the subsequent
-.\" .Sq \&Sh .
-.\" .Bd -literal -offset XXXX
-.\" \&.Sh SECTION 1
-.\" \&.Ss Subsection 1
-.\" body...
-.\" \&.Sh SECTION 2
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit full-block. Has a head, a body and no tail. Scope closed by
-.\" .Sq \&Ef
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Bf symbolic
-.\" body...
-.\" \&.Ef
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Nested explicit/implicit scope.
-.\" .Sq \&It
-.\" macro is an implicit block whose scope is closed by the explicit
-.\" .Sq \&El
-.\" closure.
-.\" .Bd -literal -offset XXXX
-.\" \&.Bl \-bullet
-.\" \&.It head
-.\" body...
-.\" \&.El
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit partial-block. Has head, body and tail. Scope closed by
-.\" .Sq \&Ec
-.\" invocation.
-.\" .Bd -literal -offset XXX
-.\" \&.Eo head body... \&Ec tail
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit partial-block. Has only body. Scope is closed by end-of-line.
-.\" .Bd -literal -offset XXX
-.\" \&.Sq body...
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Explicit partial-block with only body and scope closed by
-.\" .Sq \&Ac
-.\" invocation.
-.\" .Bd -literal -offset XXXX
-.\" \&.Ao body... \&Ac
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Implicit partial-block enclosing explicit partial-block.
-.\" .Bd -literal -offset XXX
-.\" \&.Sq body... \&Ao body... \&Ac
-.\" .Ed
-.\" .\" PARAGRAPH
-.\" .Pp
-.\" Inline macros, several in sequence. Scope is closed for
-.\" .Sq \&Fl
-.\" by the punctuation delimiter and
-.\" .Sq \&Ar
-.\" by the end-of-line.
-.\" .Bd -literal -offset XXXX
-.\" \&.Fl text0 text1 ; Ar text0 text1
-.\" .Ed
.\" SECTION
.Sh SYNTAX
Macros are generally two and at times three characters in length. The
@@ -640,6 +664,12 @@ compatibility with these systems.
.Bl -dash -compact
.\" LIST-ITEM
.It
+.Sq \&Fo
+and
+.Sq \&St
+historically weren't always callable. Both are now correctly callable.
+.\" LIST-ITEM
+.It
.Sq \&It \-nested
is assumed for all lists: any list may be nested and
.Sq \-enum
@@ -689,3 +719,58 @@ The
.Nm
utility was written by
.An Kristaps Dzonsons Aq kristaps@kth.se .
+.\" SECTION
+.Sh CAVEATS
+There are several ambiguous parts of mdoc.
+.Pp
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+.Sq \&Fa
+should be
+.Sq \&Va
+as function arguments are variables.
+.\" LIST-ITEM
+.It
+.Sq \&Ft
+should be
+.Sq \&Vt
+as function return types are still types. Furthermore, the
+.Sq \&Ft
+should be removed and
+.Sq \&Fo ,
+which ostensibly follows it, should follow the same convention as
+.Sq \&Va .
+.\" LIST-ITEM
+.It
+.Sq \&Va
+should formalise that only one or two arguments are acceptable: a
+variable name and optional, preceeding type.
+.\" LIST-ITEM
+.It
+.Sq \&Fd
+is ambiguous. It's commonly used to indicate an include file in the
+synopsis section.
+.Sq \&In
+should be used, instead.
+.\" LIST-ITEM
+.It
+Only the
+.Sq \-literal
+argument to
+.Sq \&Bd
+makes sense. The remaining ones should be removed.
+.\" LIST-ITEM
+.It
+The
+.Sq \&Xo
+and
+.Sq \&Xc
+macros should be deprecated.
+.\" LIST-ITEM
+.It
+The
+.Sq \&Dt
+macro lacks clarity. It should be absolutely clear which title will
+render when formatting the manual page.
+.El