=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.2 retrieving revision 1.6 diff -u -p -r1.2 -r1.6 --- mandoc/mdoc.7 2009/03/13 09:08:59 1.2 +++ mandoc/mdoc.7 2009/03/16 23:37:28 1.6 @@ -1,6 +1,6 @@ -.\" $Id: mdoc.7,v 1.2 2009/03/13 09:08:59 kristaps Exp $ +.\" $Id: mdoc.7,v 1.6 2009/03/16 23:37:28 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons +.\" Copyright (c) 2009 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the @@ -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 16 2009 $ .Dt mdoc 7 .Os .\" SECTION @@ -36,12 +36,12 @@ document follows simple rules: lines beginning with t character .Sq \. are parsed for macros. Other lines are interpreted within the scope of -prior macros. Macros are either two or three characters in length. +prior macros. This document describes the encoding, ontology and syntax +of these macros. .\" SECTION .Sh CHARACTER ENCODING .Nm -documents may contain only printable alphanumeric characters, the space -character +documents may contain only printable characters, the space character .Sq \ , and, in certain circumstances, the tab character .Sq \et . @@ -71,18 +71,21 @@ Within a macro line, the following characters are rese .It \&? .Pq question .It \&! -.Pq exclmamation +.Pq exclamation .El +.\" PARAGRAPH .Pp -Use of these characters must either be escaped with a non-breaking space +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. Use of reserved -characters is described later in this document. +or, if applicable, an appropriate escape-sequence used. .\" 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 \&[ @@ -92,10 +95,10 @@ 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 .It \\(em @@ -119,6 +122,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 @@ -158,6 +169,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 @@ -198,12 +221,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 @@ -217,6 +326,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 @@ -227,30 +340,28 @@ 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 -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 , @@ -258,108 +369,60 @@ text or macros following the head on the same and subs 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 -.\" .\" 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 +.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. .\" SECTION .Sh SYNTAX -The syntax of macro invocation depends on classification. +Macros are generally two and at times three characters in length. The +syntax of macro invocation depends on its classification. .Qq \-arg refers to the macro arguments (which may contain zero or more values). In these illustrations, @@ -367,45 +430,48 @@ 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 \(lBargs...\(rB -\&.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 .\" @@ -510,80 +576,148 @@ and/or tail .El .\" SUB-SECTION .Ss In-line -In-line macros have only text children. +In-line macros have only text children. If a number (or inequality) of +arguments is +.Pq n , +then the macro accepts an arbitrary number of arguments. .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 \&.Dd Ta \&No Ta \&No Ta >0 +.It \&.Dt Ta \&No Ta \&No Ta n +.It \&.Os Ta \&No Ta \&No Ta n .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 \& +.It \&.Ad Ta Yes Ta Yes Ta n +.It \&.An Ta \&No Ta Yes Ta n +.It \&.Ar Ta Yes Ta Yes Ta n +.It \&.Cd Ta Yes Ta \&No Ta >0 +.It \&.Cm Ta Yes Ta Yes Ta n +.It \&.Dv Ta Yes Ta Yes Ta >0 +.It \&.Er Ta Yes Ta Yes Ta >0 +.It \&.Ev Ta Yes Ta Yes Ta >0 +.It \&.Ex Ta \&No Ta \&No Ta 0 +.It \&.Fa Ta Yes Ta Yes Ta >0 +.It \&.Fd Ta \&No Ta \&No Ta >0 +.It \&.Fl Ta Yes Ta Yes Ta n +.It \&.Fn Ta Yes Ta Yes Ta >0 +.It \&.Ft Ta \&No Ta Yes Ta n +.It \&.Ic Ta Yes Ta Yes Ta >0 +.It \&.In Ta \&No Ta \&No Ta n +.It \&.Li Ta Yes Ta Yes Ta >0 +.It \&.Nd Ta \&No Ta \&No Ta n +.It \&.Nm Ta Yes Ta Yes Ta n +.It \&.Ot Ta \&No Ta \&No Ta n +.It \&.Pa Ta Yes Ta Yes Ta n +.It \&.Rv Ta \&No Ta \&No Ta 0 +.It \&.St Ta \&No Ta Yes Ta 1 +.It \&.Va Ta Yes Ta Yes Ta >0 +.It \&.Vt Ta Yes Ta Yes Ta >0 +.It \&.Xr Ta Yes Ta Yes Ta >0, <3 +.It \&.%A Ta \&No Ta \&No Ta >0 +.It \&.%B Ta \&No Ta \&No Ta >0 +.It \&.%C Ta \&No Ta \&No Ta >0 +.It \&.%D Ta \&No Ta \&No Ta >0 +.It \&.%I Ta \&No Ta \&No Ta >0 +.It \&.%J Ta \&No Ta \&No Ta >0 +.It \&.%N Ta \&No Ta \&No Ta >0 +.It \&.%O Ta \&No Ta \&No Ta >0 +.It \&.%P Ta \&No Ta \&No Ta >0 +.It \&.%R Ta \&No Ta \&No Ta >0 +.It \&.%T Ta \&No Ta \&No Ta >0 +.It \&.%V Ta \&No Ta \&No Ta >0 +.It \&.At Ta Yes Ta Yes Ta 1 +.It \&.Bsx Ta Yes Ta Yes Ta n +.It \&.Bx Ta Yes Ta Yes Ta n +.It \&.Db Ta \&No Ta \&No Ta 1 +.It \&.Em Ta Yes Ta Yes Ta >0 +.It \&.Fx Ta Yes Ta Yes Ta n +.It \&.Ms Ta \&No Ta Yes Ta >0 +.It \&.No Ta Yes Ta Yes Ta 0 +.It \&.Ns Ta Yes Ta Yes Ta 0 +.It \&.Nx Ta Yes Ta Yes Ta n +.It \&.Ox Ta Yes Ta Yes Ta n +.It \&.Pf Ta \&No Ta Yes Ta 1 +.It \&.Sm Ta \&No Ta \&No Ta 1 +.It \&.Sx Ta Yes Ta Yes Ta >0 +.It \&.Sy Ta Yes Ta Yes Ta >0 +.It \&.Tn Ta Yes Ta Yes Ta >0 +.It \&.Ux Ta Yes Ta Yes Ta n +.It \&.Dx Ta Yes Ta Yes Ta n +.It \&.Bt Ta \&No Ta \&No Ta 0 +.It \&.Hf Ta \&No Ta \&No Ta n +.It \&.Fr Ta \&No Ta \&No Ta n +.It \&.Ud Ta \&No Ta \&No Ta 0 +.It \&.Lb Ta \&No Ta \&No Ta 1 +.It \&.Ap Ta Yes Ta Yes Ta 0 +.It \&.Lp Ta \&No Ta \&No Ta 0 +.It \&.Lk Ta \&No Ta Yes Ta >0 +.It \&.Mt Ta \&No Ta Yes Ta >0 +.It \&.Es Ta \&No Ta \&No Ta 0 +.It \&.En Ta \&No Ta \&No Ta 0 .El +.Pp +The +.Sq \&Ot , +.Sq \&Fr , +.Sq \&Es +and +.Sq \&En , +macros are obsolete. .\" 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 \&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 +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 , @@ -594,4 +728,67 @@ In-line macros have only text children. The .Nm utility was written by -.An Kristaps Dzonsons Aq kristaps@kth.se . +.An Kristaps Dzonsons Aq kristaps@openbsd.org . +.\" 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. +.\" LIST-ITEM +.It +A +.Sq \&Lx +should be provided for Linux (\(`a la +.Sq \&Ox , +.Sq \&Nx +etc.). +.El