=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.10 retrieving revision 1.18 diff -u -p -r1.10 -r1.18 --- mandoc/mdoc.7 2009/03/20 15:14:01 1.10 +++ mandoc/mdoc.7 2009/03/27 13:44:24 1.18 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.10 2009/03/20 15:14:01 kristaps Exp $ +.\" $Id: mdoc.7,v 1.18 2009/03/27 13:44:24 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,13 +16,13 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 20 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,18 +30,28 @@ 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 characters, the space character +documents may contain only graphable 7-bit ASCII characters, the space +character .Sq \ , and, in certain circumstances, the tab character .Sq \et . @@ -51,18 +61,18 @@ line termination. .Pp The only time a blank line is acceptable is within the context of -.Sq \&Bd \-literal +.Sq \&.Bd \-literal or -.Sq \&Bd \-unfilled . +.Sq \&.Bd \-unfilled . .Pp Tab characters .Pq \et are only acceptable when delimiting -.Sq \&Bl \-column +.Sq \&.Bl \-column and in -.Sq \&Bd \-literal +.Sq \&.Bd \-literal or -.Sq \&Bd \-unfilled +.Sq \&.Bd \-unfilled contexts. .\" SUB-SECTION .Ss Reserved Characters @@ -100,7 +110,7 @@ or, if applicable, an appropriate escape-sequence used .\" SUB-SECTION .Ss Special Characters Special character sequences begin with the escape character -.Sq \\ +.Sq \e followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket @@ -110,426 +120,432 @@ 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 \\* , +.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 \\(r! +.It \e(r! .Pq upside-down exclamation -.It \\(r? +.It \e(r? .Pq upside-down question .El .\" PARAGRAPH .Pp Enclosures: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(lh +.It \e(lh .Pq left hand -.It \\(rh +.It \e(rh .Pq right hand -.It \\(Fo +.It \e(Fo .Pq left guillemet -.It \\(Fc +.It \e(Fc .Pq right guillemet -.It \\(fo +.It \e(fo .Pq left guilsing -.It \\(fc +.It \e(fc .Pq right guilsing -.It \\(rC +.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 \\(Bq +.It \e(Bq .Pq right low double-quote -.It \\(bq +.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 \\(<> +.It \e(<> .Pq left-right arrow -.It \\(lA +.It \e(lA .Pq left double-arrow -.It \\(rA +.It \e(rA .Pq right double-arrow -.It \\(uA +.It \e(uA .Pq up double-arrow -.It \\(dA +.It \e(dA .Pq down double-arrow -.It \\(hA +.It \e(hA .Pq left-right double-arrow .El .\" PARAGRAPH .Pp Mathematical: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(es +.It \e(es .Pq empty set -.It \\(ca +.It \e(ca .Pq intersection -.It \\(cu +.It \e(cu .Pq union -.It \\(gr +.It \e(gr .Pq gradient -.It \\(pd +.It \e(pd .Pq partial differential -.It \\(ap +.It \e(ap .Pq similarity -.It \\(=) +.It \e(=) .Pq proper superset -.It \\((= +.It \e((= .Pq proper subset -.It \\(eq +.It \e(eq .Pq equals -.It \\(di +.It \e(di .Pq division -.It \\(mu +.It \e(mu .Pq multiplication -.It \\(pl +.It \e(pl .Pq addition -.It \\(nm +.It \e(nm .Pq not element -.It \\(mo +.It \e(mo .Pq element -.It \\(Im +.It \e(Im .Pq imaginary -.It \\(Re +.It \e(Re .Pq real -.It \\(Ah +.It \e(Ah .Pq aleph -.It \\(te +.It \e(te .Pq existential quantifier -.It \\(fa +.It \e(fa .Pq universal quantifier -.It \\(AN +.It \e(AN .Pq logical AND -.It \\(OR +.It \e(OR .Pq logical OR -.It \\(no +.It \e(no .Pq logical NOT -.It \\(st +.It \e(st .Pq such that -.It \\(tf +.It \e(tf .Pq therefore -.It \\(~~ +.It \e(~~ .Pq approximate -.It \\(~= +.It \e(~= .Pq approximately equals -.It \\(=~ +.It \e(=~ .Pq congruent -.It \\(Gt +.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 Ligatures: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ss +.It \e(ss .Pq German eszett -.It \\(AE +.It \e(AE .Pq upper-case AE -.It \\(ae +.It \e(ae .Pq lower-case AE -.It \\(OE +.It \e(OE .Pq upper-case OE -.It \\(oe +.It \e(oe .Pq lower-case OE -.It \\(ff +.It \e(ff .Pq ff ligature -.It \\(fi +.It \e(fi .Pq fi ligature -.It \\(fl +.It \e(fl .Pq fl ligature -.It \\(Fi +.It \e(Fi .Pq ffi ligature -.It \\(Fl +.It \e(Fl .Pq ffl ligature .El .\" PARAGRAPH .Pp Diacritics and letters: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ga +.It \e(ga .Pq grave accent -.It \\(aa +.It \e(aa .Pq accute accent -.It \\(a" +.It \e(a" .Pq umlaut accent -.It \\(ad +.It \e(ad .Pq dieresis accent -.It \\(a~ +.It \e(a~ .Pq tilde accent -.It \\(a^ +.It \e(a^ .Pq circumflex accent -.It \\(ac +.It \e(ac .Pq cedilla accent -.It \\(ad +.It \e(ad .Pq dieresis accent -.It \\(ah +.It \e(ah .Pq caron accent -.It \\(ao +.It \e(ao .Pq ring accent -.It \\(ho +.It \e(ho .Pq hook accent -.It \\(ab +.It \e(ab .Pq breve accent -.It \\(a- +.It \e(a- .Pq macron accent -.It \\(-D +.It \e(-D .Pq upper-case eth -.It \\(Sd +.It \e(Sd .Pq lower-case eth -.It \\(TP +.It \e(TP .Pq upper-case thorn -.It \\(Tp +.It \e(Tp .Pq lower-case thorn -.It \\('A +.It \e('A .Pq upper-case acute A -.It \\('E +.It \e('E .Pq upper-case acute E -.It \\('I +.It \e('I .Pq upper-case acute I -.It \\('O +.It \e('O .Pq upper-case acute O -.It \\('U +.It \e('U .Pq upper-case acute U -.It \\('a +.It \e('a .Pq lower-case acute a -.It \\('e +.It \e('e .Pq lower-case acute e -.It \\('i +.It \e('i .Pq lower-case acute i -.It \\('o +.It \e('o .Pq lower-case acute o -.It \\('u +.It \e('u .Pq lower-case acute u -.It \\(`A +.It \e(`A .Pq upper-case grave A -.It \\(`E +.It \e(`E .Pq upper-case grave E -.It \\(`I +.It \e(`I .Pq upper-case grave I -.It \\(`O +.It \e(`O .Pq upper-case grave O -.It \\(`U +.It \e(`U .Pq upper-case grave U -.It \\(`a +.It \e(`a .Pq lower-case grave a -.It \\(`e +.It \e(`e .Pq lower-case grave e -.It \\(`i +.It \e(`i .Pq lower-case grave i -.It \\(`o +.It \e(`o .Pq lower-case grave o -.It \\(`u +.It \e(`u .Pq lower-case grave u -.It \\(~A +.It \e(~A .Pq upper-case tilde A -.It \\(~N +.It \e(~N .Pq upper-case tilde N -.It \\(~O +.It \e(~O .Pq upper-case tilde O -.It \\(~a +.It \e(~a .Pq lower-case tilde a -.It \\(~n +.It \e(~n .Pq lower-case tilde n -.It \\(~o +.It \e(~o .Pq lower-case tilde o -.It \\(:A +.It \e(:A .Pq upper-case dieresis A -.It \\(:E +.It \e(:E .Pq upper-case dieresis E -.It \\(:I +.It \e(:I .Pq upper-case dieresis I -.It \\(:O +.It \e(:O .Pq upper-case dieresis O -.It \\(:U +.It \e(:U .Pq upper-case dieresis U -.It \\(:a +.It \e(:a .Pq lower-case dieresis a -.It \\(:e +.It \e(:e .Pq lower-case dieresis e -.It \\(:i +.It \e(:i .Pq lower-case dieresis i -.It \\(:o +.It \e(:o .Pq lower-case dieresis o -.It \\(:u +.It \e(:u .Pq lower-case dieresis u -.It \\(:y +.It \e(:y .Pq lower-case dieresis y -.It \\(^A +.It \e(^A .Pq upper-case circumflex A -.It \\(^E +.It \e(^E .Pq upper-case circumflex E -.It \\(^I +.It \e(^I .Pq upper-case circumflex I -.It \\(^O +.It \e(^O .Pq upper-case circumflex O -.It \\(^U +.It \e(^U .Pq upper-case circumflex U -.It \\(^a +.It \e(^a .Pq lower-case circumflex a -.It \\(^e +.It \e(^e .Pq lower-case circumflex e -.It \\(^i +.It \e(^i .Pq lower-case circumflex i -.It \\(^o +.It \e(^o .Pq lower-case circumflex o -.It \\(^u +.It \e(^u .Pq lower-case circumflex u -.It \\(,C +.It \e(,C .Pq upper-case cedilla C -.It \\(,c +.It \e(,c .Pq lower-case cedilla c -.It \\(/L +.It \e(/L .Pq upper-case stroke L -.It \\(/l +.It \e(/l .Pq lower-case stroke l -.It \\(/O +.It \e(/O .Pq upper-case stroke O -.It \\(/o +.It \e(/o .Pq lower-case stroke o -.It \\(oA +.It \e(oA .Pq upper-case ring A -.It \\(oa +.It \e(oa .Pq lower-case ring a .El .\" PARAGRAPH .Pp Monetary: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(Cs +.It \e(Cs .Pq Scandinavian -.It \\(Do +.It \e(Do .Pq dollar -.It \\(Po +.It \e(Po .Pq pound -.It \\(Ye +.It \e(Ye .Pq yen -.It \\(Fn +.It \e(Fn .Pq florin -.It \\(ct +.It \e(ct .Pq cent .El .\" PARAGRAPH .Pp Special symbols: .Bl -tag -width 12n -offset "XXXX" -compact -.It \\(de +.It \e0 +.Pq white-space +.It \e(de .Pq degree -.It \\(ps +.It \e(ps .Pq paragraph -.It \\(sc +.It \e(sc .Pq section -.It \\(dg +.It \e(dg .Pq dagger -.It \\(dd +.It \e(dd .Pq double dagger -.It \\(ci +.It \e(ci .Pq circle -.It \\(ba +.It \e(ba .Pq bar -.It \\(bb +.It \e(bb .Pq broken bar -.It \\(Ba +.It \e(Ba .Pq bar, deprecated -.It \\(co +.It \e(co .Pq copyright -.It \\(rg +.It \e(rg .Pq registered -.It \\(tm +.It \e(tm .Pq trademarked -.It \\& +.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 @@ -611,8 +627,8 @@ subsequent tokens are interpreted as if the scope had 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, @@ -670,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 @@ -679,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 , @@ -729,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 @@ -782,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 @@ -819,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 @@ -847,11 +881,11 @@ then the macro accepts an arbitrary number of argument .El .Pp The -.Sq \&Ot , -.Sq \&Fr , -.Sq \&Es +.Sq \&.Ot , +.Sq \&.Fr , +.Sq \&.Es and -.Sq \&En , +.Sq \&.En , macros are obsolete. .\" SECTION .Sh COMPATIBILITY @@ -864,55 +898,52 @@ compatibility with these systems. .Bl -dash -compact .\" LIST-ITEM .It -.Sq \&Fo +.Sq \&.Fo and -.Sq \&St +.Sq \&.St historically weren't always callable. Both are now correctly callable. .\" LIST-ITEM .It -.Sq \&It \-nested +.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 +.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 +.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 , +.Ns Sq \&.At , +.Sq \&.Bsx , +.Sq \&.Bx , +.Sq \&.Fx , +.Sq \&.Nx , +.Sq \&.Ox , and -.Sq \&Ux ) +.Sq \&.Ux ) are callable. .\" LIST-ITEM .It Some manuals use -.Sq \&Li +.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 +.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 AUTHORS The @@ -926,59 +957,64 @@ There are several ambiguous parts of mdoc. .Bl -dash -compact .\" LIST-ITEM .It -.Sq \&Fa +.Sq \&.Fa should be -.Sq \&Va +.Sq \&.Va as function arguments are variables. .\" LIST-ITEM .It -.Sq \&Ft +.Sq \&.Ft should be -.Sq \&Vt +.Sq \&.Vt as function return types are still types. Furthermore, the -.Sq \&Ft +.Sq \&.Ft should be removed and -.Sq \&Fo , +.Sq \&.Fo , which ostensibly follows it, should follow the same convention as -.Sq \&Va . +.Sq \&.Va . .\" LIST-ITEM .It -.Sq \&Va +.Sq \&.Va should formalise that only one or two arguments are acceptable: a variable name and optional, preceeding type. .\" LIST-ITEM .It -.Sq \&Fd +.Sq \&.Fd is ambiguous. It's commonly used to indicate an include file in the synopsis section. -.Sq \&In +.Sq \&.In should be used, instead. .\" LIST-ITEM .It Only the .Sq \-literal argument to -.Sq \&Bd +.Sq \&.Bd makes sense. The remaining ones should be removed. .\" LIST-ITEM .It The -.Sq \&Xo +.Sq \&.Xo and -.Sq \&Xc +.Sq \&.Xc macros should be deprecated. .\" LIST-ITEM .It The -.Sq \&Dt +.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 +.Sq \&.Lx should be provided for Linux (\(`a la -.Sq \&Ox , -.Sq \&Nx +.Sq \&.Ox , +.Sq \&.Nx etc.). +.\" LIST-ITEM +.It +There's no way to refer to references in +.Sq \&.Rs/.Re +blocks. .El