=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.3 retrieving revision 1.18 diff -u -p -r1.3 -r1.18 --- mandoc/mdoc.7 2009/03/13 13:56:13 1.3 +++ mandoc/mdoc.7 2009/03/27 13:44:24 1.18 @@ -1,6 +1,6 @@ -.\" $Id: mdoc.7,v 1.3 2009/03/13 13:56:13 kristaps Exp $ +.\" $Id: mdoc.7,v 1.18 2009/03/27 13:44:24 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,13 +16,13 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 13 2009 $ +.Dd $Mdocdate: March 27 2009 $ .Dt mdoc 7 .Os .\" SECTION .Sh NAME .Nm mdoc -.Nd mdoc macro reference +.Nd mdoc language reference .\" SECTION .Sh DESCRIPTION The @@ -30,25 +30,50 @@ The language is used to format .Bx .Ux -manuals. An +manuals. In this reference document, we describe the syntax, ontology +and structure of the .Nm +language. +.\" PARAGRAPH +.Pp +An +.Nm document follows simple rules: lines beginning with the control -character +character .Sq \. are parsed for macros. Other lines are interpreted within the scope of -prior macros. This document describes the encoding, ontology and syntax -of these macros. +prior macros: +.Bd -literal -offset XXX +\&.Sh Macro lines change control state. +Other lines are interpreted within the current state. +.Ed .\" SECTION -.Sh CHARACTER ENCODING +.Sh INPUT ENCODING .Nm -documents may contain only printable alphanumeric characters, the space +documents may contain only graphable 7-bit ASCII characters, the space character .Sq \ , and, in certain circumstances, the tab character .Sq \et . All manuals must have .Sq \en -line termination. +line termination. +.Pp +The only time a blank line is acceptable is within +the context of +.Sq \&.Bd \-literal +or +.Sq \&.Bd \-unfilled . +.Pp +Tab characters +.Pq \et +are only acceptable when delimiting +.Sq \&.Bl \-column +and in +.Sq \&.Bd \-literal +or +.Sq \&.Bd \-unfilled +contexts. .\" SUB-SECTION .Ss Reserved Characters Within a macro line, the following characters are reserved: @@ -72,18 +97,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 +.Sq \e +followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket .Sq \&[ @@ -92,166 +120,454 @@ for n-character sequences (terminated at a close-brack 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. +.Sq \e* , +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 +.It \e(em .Pq em-dash -.It \\(en +.It \e(en .Pq en-dash .It \e- .Pq hyphen -.It \\\\ +.It \e\e .Pq back-slash .It \e' .Pq apostrophe .It \e` .Pq back-tick -.It \\ +.It \e .Pq space -.It \\. +.It \e. .Pq period +.It \e(r! +.Pq upside-down exclamation +.It \e(r? +.Pq upside-down question .El .\" PARAGRAPH .Pp Enclosures: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(rC +.It \e(lh +.Pq left hand +.It \e(rh +.Pq right hand +.It \e(Fo +.Pq left guillemet +.It \e(Fc +.Pq right guillemet +.It \e(fo +.Pq left guilsing +.It \e(fc +.Pq right guilsing +.It \e(rC .Pq right brace -.It \\(lC +.It \e(lC .Pq left brace -.It \\(ra +.It \e(ra .Pq right angle -.It \\(la +.It \e(la .Pq left angle -.It \\(rB +.It \e(rB .Pq right bracket -.It \\(lB +.It \e(lB .Pq left bracket -.It \\q +.It \eq .Pq double-quote -.It \\(lq +.It \e(lq .Pq left double-quote -.It \\(Lq +.It \e(Lq .Pq left double-quote, deprecated -.It \\(rq +.It \e(rq .Pq right double-quote -.It \\(Rq +.It \e(Rq .Pq right double-quote, deprecated -.It \\(oq +.It \e(oq .Pq left single-quote -.It \\(aq +.It \e(aq .Pq right single-quote +.It \e(Bq +.Pq right low double-quote +.It \e(bq +.Pq right low single-quote .El .\" PARAGRAPH .Pp Indicatives: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(<- +.It \e(<- .Pq left arrow -.It \\(-> +.It \e(-> .Pq right arrow -.It \\(ua +.It \e(ua .Pq up arrow -.It \\(da +.It \e(da .Pq down arrow +.It \e(<> +.Pq left-right arrow +.It \e(lA +.Pq left double-arrow +.It \e(rA +.Pq right double-arrow +.It \e(uA +.Pq up double-arrow +.It \e(dA +.Pq down double-arrow +.It \e(hA +.Pq left-right double-arrow .El .\" PARAGRAPH .Pp Mathematical: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(Gt +.It \e(es +.Pq empty set +.It \e(ca +.Pq intersection +.It \e(cu +.Pq union +.It \e(gr +.Pq gradient +.It \e(pd +.Pq partial differential +.It \e(ap +.Pq similarity +.It \e(=) +.Pq proper superset +.It \e((= +.Pq proper subset +.It \e(eq +.Pq equals +.It \e(di +.Pq division +.It \e(mu +.Pq multiplication +.It \e(pl +.Pq addition +.It \e(nm +.Pq not element +.It \e(mo +.Pq element +.It \e(Im +.Pq imaginary +.It \e(Re +.Pq real +.It \e(Ah +.Pq aleph +.It \e(te +.Pq existential quantifier +.It \e(fa +.Pq universal quantifier +.It \e(AN +.Pq logical AND +.It \e(OR +.Pq logical OR +.It \e(no +.Pq logical NOT +.It \e(st +.Pq such that +.It \e(tf +.Pq therefore +.It \e(~~ +.Pq approximate +.It \e(~= +.Pq approximately equals +.It \e(=~ +.Pq congruent +.It \e(Gt .Pq greater-than, deprecated -.It \\(Lt +.It \e(Lt .Pq less-than, deprecated -.It \\(<= +.It \e(<= .Pq less-than-equal -.It \\(Le +.It \e(Le .Pq less-than-equal, deprecated -.It \\(>= +.It \e(>= .Pq greater-than-equal -.It \\(Ge +.It \e(Ge .Pq greater-than-equal -.It \\(== +.It \e(== .Pq equal -.It \\(!= +.It \e(!= .Pq not equal -.It \\(Ne +.It \e(Ne .Pq not equal, deprecated -.It \\(if +.It \e(if .Pq infinity -.It \\(If +.It \e(If .Pq infinity, deprecated -.It \\(na +.It \e(na .Pq NaN , an extension -.It \\(Na +.It \e(Na .Pq NaN, deprecated -.It \\(+- +.It \e(+- .Pq plus-minus -.It \\(Pm +.It \e(Pm .Pq plus-minus, deprecated -.It \\(** +.It \e(** .Pq asterisk .El .\" PARAGRAPH .Pp -Diacritics: +Ligatures: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ga -.Pq accent grave -.It \\(aa -.Pq accent accute +.It \e(ss +.Pq German eszett +.It \e(AE +.Pq upper-case AE +.It \e(ae +.Pq lower-case AE +.It \e(OE +.Pq upper-case OE +.It \e(oe +.Pq lower-case OE +.It \e(ff +.Pq ff ligature +.It \e(fi +.Pq fi ligature +.It \e(fl +.Pq fl ligature +.It \e(Fi +.Pq ffi ligature +.It \e(Fl +.Pq ffl ligature .El .\" PARAGRAPH .Pp +Diacritics and letters: +.Bl -tag -width 12n -offset "XXXX" -compact +.It \e(ga +.Pq grave accent +.It \e(aa +.Pq accute accent +.It \e(a" +.Pq umlaut accent +.It \e(ad +.Pq dieresis accent +.It \e(a~ +.Pq tilde accent +.It \e(a^ +.Pq circumflex accent +.It \e(ac +.Pq cedilla accent +.It \e(ad +.Pq dieresis accent +.It \e(ah +.Pq caron accent +.It \e(ao +.Pq ring accent +.It \e(ho +.Pq hook accent +.It \e(ab +.Pq breve accent +.It \e(a- +.Pq macron accent +.It \e(-D +.Pq upper-case eth +.It \e(Sd +.Pq lower-case eth +.It \e(TP +.Pq upper-case thorn +.It \e(Tp +.Pq lower-case thorn +.It \e('A +.Pq upper-case acute A +.It \e('E +.Pq upper-case acute E +.It \e('I +.Pq upper-case acute I +.It \e('O +.Pq upper-case acute O +.It \e('U +.Pq upper-case acute U +.It \e('a +.Pq lower-case acute a +.It \e('e +.Pq lower-case acute e +.It \e('i +.Pq lower-case acute i +.It \e('o +.Pq lower-case acute o +.It \e('u +.Pq lower-case acute u +.It \e(`A +.Pq upper-case grave A +.It \e(`E +.Pq upper-case grave E +.It \e(`I +.Pq upper-case grave I +.It \e(`O +.Pq upper-case grave O +.It \e(`U +.Pq upper-case grave U +.It \e(`a +.Pq lower-case grave a +.It \e(`e +.Pq lower-case grave e +.It \e(`i +.Pq lower-case grave i +.It \e(`o +.Pq lower-case grave o +.It \e(`u +.Pq lower-case grave u +.It \e(~A +.Pq upper-case tilde A +.It \e(~N +.Pq upper-case tilde N +.It \e(~O +.Pq upper-case tilde O +.It \e(~a +.Pq lower-case tilde a +.It \e(~n +.Pq lower-case tilde n +.It \e(~o +.Pq lower-case tilde o +.It \e(:A +.Pq upper-case dieresis A +.It \e(:E +.Pq upper-case dieresis E +.It \e(:I +.Pq upper-case dieresis I +.It \e(:O +.Pq upper-case dieresis O +.It \e(:U +.Pq upper-case dieresis U +.It \e(:a +.Pq lower-case dieresis a +.It \e(:e +.Pq lower-case dieresis e +.It \e(:i +.Pq lower-case dieresis i +.It \e(:o +.Pq lower-case dieresis o +.It \e(:u +.Pq lower-case dieresis u +.It \e(:y +.Pq lower-case dieresis y +.It \e(^A +.Pq upper-case circumflex A +.It \e(^E +.Pq upper-case circumflex E +.It \e(^I +.Pq upper-case circumflex I +.It \e(^O +.Pq upper-case circumflex O +.It \e(^U +.Pq upper-case circumflex U +.It \e(^a +.Pq lower-case circumflex a +.It \e(^e +.Pq lower-case circumflex e +.It \e(^i +.Pq lower-case circumflex i +.It \e(^o +.Pq lower-case circumflex o +.It \e(^u +.Pq lower-case circumflex u +.It \e(,C +.Pq upper-case cedilla C +.It \e(,c +.Pq lower-case cedilla c +.It \e(/L +.Pq upper-case stroke L +.It \e(/l +.Pq lower-case stroke l +.It \e(/O +.Pq upper-case stroke O +.It \e(/o +.Pq lower-case stroke o +.It \e(oA +.Pq upper-case ring A +.It \e(oa +.Pq lower-case ring a +.El +.\" PARAGRAPH +.Pp +Monetary: +.Bl -tag -width 12n -offset "XXXX" -compact +.It \e(Cs +.Pq Scandinavian +.It \e(Do +.Pq dollar +.It \e(Po +.Pq pound +.It \e(Ye +.Pq yen +.It \e(Fn +.Pq florin +.It \e(ct +.Pq cent +.El +.\" PARAGRAPH +.Pp Special symbols: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(bu -.Pq bullet -.It \\(ba +.It \e0 +.Pq white-space +.It \e(de +.Pq degree +.It \e(ps +.Pq paragraph +.It \e(sc +.Pq section +.It \e(dg +.Pq dagger +.It \e(dd +.Pq double dagger +.It \e(ci +.Pq circle +.It \e(ba .Pq bar -.It \\(Ba +.It \e(bb +.Pq broken bar +.It \e(Ba .Pq bar, deprecated -.It \\(co +.It \e(co .Pq copyright -.It \\& +.It \e(rg +.Pq registered +.It \e(tm +.Pq trademarked +.It \e& .Pq non-breaking space -.It \\e +.It \ee .Pq escape -.It \\(Am +.It \e(Am .Pq ampersand, deprecated .El .\" SECTION -.Sh ONTOLOGY -Macros are classified in an ontology described by scope rules. +.Sh STRUCTURE +Macros are classified in an ontology described by their scope rules. +Some macros are allowed to deviate from their classifications to +preserve backward-compatibility with old macro combinations still found +in the manual corpus. These are specifically noted on a per-macro +basis. +.\" 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 , @@ -259,109 +575,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 -Macros are generally two and at times three characters in length. The -syntax of macro invocation depends on its classification. +Macros are two or 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, @@ -369,45 +636,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 .\" @@ -416,7 +686,7 @@ This section contains a complete list of all .Nm macros, arranged ontologically. A .Qq callable -macro is may be invoked subsequent to the initial macro-line macro. A +macro is invoked subsequent to the initial macro-line macro. A .Qq parsable macro may be followed by further (ostensibly callable) macros. .\" SUB-SECTION @@ -425,7 +695,7 @@ The head of these macros follows invocation; the body subsequent lines prior to closure. None of these macros have tails; some .Po -.Sq \&It \-bullet , +.Sq \&.It \-bullet , .Sq \-hyphen , .Sq \-dash , .Sq \-enum , @@ -475,13 +745,31 @@ close at the invocation's end-of-line. .It \&.Dl Ta \&No Ta Yes .It \&.Ql Ta Yes Ta Yes .El +.\" PARAGRAPH +.Pp +The +.Sq \&.Op +may be broken by +.Sq \&.Oc +as in the following example: +.Bd -literal -offset XXXX +\&.Oo +\&.Op Fl a Oc +.Ed +.Pp +In the above example, the scope of +.Sq \&.Op +is technically broken by +.Sq \&.Oc , +however, due to the overwhelming existence of this sequence, it's +allowed. .\" SUB-SECTION .Ss Block partial-explicit Each of these contains at least a body and, in limited circumstances, a head -.Pq So \&Fo Sc , So \&Eo Sc +.Pq So \&.Fo Sc , So \&.Eo Sc and/or tail -.Pq So \&Ec Sc . +.Pq So \&.Ec Sc . .Pp .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope @@ -528,25 +816,25 @@ then the macro accepts an arbitrary number of argument .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 \&.Dv Ta Yes Ta Yes Ta n .It \&.Er Ta Yes Ta Yes Ta >0 -.It \&.Ev Ta Yes Ta Yes Ta >0 +.It \&.Ev Ta Yes Ta Yes Ta n .It \&.Ex Ta \&No Ta \&No Ta 0 -.It \&.Fa Ta Yes Ta Yes Ta >0 +.It \&.Fa Ta Yes Ta Yes Ta n .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 \&.Li Ta Yes Ta Yes Ta n .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 \&.Va Ta Yes Ta Yes Ta n .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 @@ -565,7 +853,7 @@ then the macro accepts an arbitrary number of argument .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 \&.Em Ta Yes Ta Yes Ta n .It \&.Fx Ta Yes Ta Yes Ta n .It \&.Ms Ta \&No Ta Yes Ta >0 .It \&.No Ta Yes Ta Yes Ta 0 @@ -578,6 +866,7 @@ then the macro accepts an arbitrary number of argument .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 @@ -587,21 +876,145 @@ then the macro accepts an arbitrary number of argument .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 , -.Xr mdocterm 1 , -.Xr mdoc 3 +.Xr mandoc 1 .\" 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 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.). +.\" LIST-ITEM +.It +There's no way to refer to references in +.Sq \&.Rs/.Re +blocks. +.El