=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.15 retrieving revision 1.19 diff -u -p -r1.15 -r1.19 --- mandoc/mdoc.7 2009/03/23 16:02:56 1.15 +++ mandoc/mdoc.7 2009/03/27 14:56:15 1.19 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.15 2009/03/23 16:02:56 kristaps Exp $ +.\" $Id: mdoc.7,v 1.19 2009/03/27 14:56:15 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 23 2009 $ +.Dd $Mdocdate: March 27 2009 $ .Dt mdoc 7 .Os .\" SECTION @@ -47,11 +47,6 @@ prior macros: \&.Sh Macro lines change control state. Other lines are interpreted within the current state. .Ed -.\" PARAGRAPH -.Pp -Macros are two- or three-character sequences whose scope rules, rules -that dictate handling of subsequent-line or same-line arguments, are -governed by one of five classifications described in this document. .\" SECTION .Sh INPUT ENCODING .Nm @@ -66,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 @@ -115,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 @@ -125,425 +120,10 @@ 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 -.Pq em-dash -.It \\(en -.Pq en-dash -.It \e- -.Pq hyphen -.It \\\\ -.Pq back-slash -.It \e' -.Pq apostrophe -.It \e` -.Pq back-tick -.It \\ -.Pq space -.It \\. -.Pq period -.It \\(r! -.Pq upside-down exclamation -.It \\(r? -.Pq upside-down question -.El -.\" PARAGRAPH -.Pp -Enclosures: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(lh -.Pq left hand -.It \\(rh -.Pq right hand -.It \\(Fo -.Pq left guillemet -.It \\(Fc -.Pq right guillemet -.It \\(fo -.Pq left guilsing -.It \\(fc -.Pq right guilsing -.It \\(rC -.Pq right brace -.It \\(lC -.Pq left brace -.It \\(ra -.Pq right angle -.It \\(la -.Pq left angle -.It \\(rB -.Pq right bracket -.It \\(lB -.Pq left bracket -.It \\q -.Pq double-quote -.It \\(lq -.Pq left double-quote -.It \\(Lq -.Pq left double-quote, deprecated -.It \\(rq -.Pq right double-quote -.It \\(Rq -.Pq right double-quote, deprecated -.It \\(oq -.Pq left single-quote -.It \\(aq -.Pq right single-quote -.It \\(Bq -.Pq right low double-quote -.It \\(bq -.Pq right low single-quote -.El -.\" PARAGRAPH -.Pp -Indicatives: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(<- -.Pq left arrow -.It \\(-> -.Pq right arrow -.It \\(ua -.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 -Mathematical: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(es -.Pq empty set -.It \\(ca -.Pq intersection -.It \\(cu -.Pq union -.It \\(gr -.Pq gradient -.It \\(pd -.Pq partial differential -.It \\(ap -.Pq similarity -.It \\(=) -.Pq proper superset -.It \\((= -.Pq proper subset -.It \\(eq -.Pq equals -.It \\(di -.Pq division -.It \\(mu -.Pq multiplication -.It \\(pl -.Pq addition -.It \\(nm -.Pq not element -.It \\(mo -.Pq element -.It \\(Im -.Pq imaginary -.It \\(Re -.Pq real -.It \\(Ah -.Pq aleph -.It \\(te -.Pq existential quantifier -.It \\(fa -.Pq universal quantifier -.It \\(AN -.Pq logical AND -.It \\(OR -.Pq logical OR -.It \\(no -.Pq logical NOT -.It \\(st -.Pq such that -.It \\(tf -.Pq therefore -.It \\(~~ -.Pq approximate -.It \\(~= -.Pq approximately equals -.It \\(=~ -.Pq congruent -.It \\(Gt -.Pq greater-than, deprecated -.It \\(Lt -.Pq less-than, deprecated -.It \\(<= -.Pq less-than-equal -.It \\(Le -.Pq less-than-equal, deprecated -.It \\(>= -.Pq greater-than-equal -.It \\(Ge -.Pq greater-than-equal -.It \\(== -.Pq equal -.It \\(!= -.Pq not equal -.It \\(Ne -.Pq not equal, deprecated -.It \\(if -.Pq infinity -.It \\(If -.Pq infinity, deprecated -.It \\(na -.Pq NaN , an extension -.It \\(Na -.Pq NaN, deprecated -.It \\(+- -.Pq plus-minus -.It \\(Pm -.Pq plus-minus, deprecated -.It \\(** -.Pq asterisk -.El -.\" PARAGRAPH -.Pp -Ligatures: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ss -.Pq German eszett -.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 \\(ff -.Pq ff ligature -.It \\(fi -.Pq fi ligature -.It \\(fl -.Pq fl ligature -.It \\(Fi -.Pq ffi ligature -.It \\(Fl -.Pq ffl ligature -.El -.\" PARAGRAPH -.Pp -Diacritics and letters: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ga -.Pq grave accent -.It \\(aa -.Pq accute accent -.It \\(a" -.Pq umlaut accent -.It \\(ad -.Pq dieresis accent -.It \\(a~ -.Pq tilde accent -.It \\(a^ -.Pq circumflex accent -.It \\(ac -.Pq cedilla accent -.It \\(ad -.Pq dieresis accent -.It \\(ah -.Pq caron accent -.It \\(ao -.Pq ring accent -.It \\(ho -.Pq hook accent -.It \\(ab -.Pq breve accent -.It \\(a- -.Pq macron accent -.It \\(-D -.Pq upper-case eth -.It \\(Sd -.Pq lower-case eth -.It \\(TP -.Pq upper-case thorn -.It \\(Tp -.Pq lower-case thorn -.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 -.It \\(^A -.Pq upper-case circumflex A -.It \\(^E -.Pq upper-case circumflex E -.It \\(^I -.Pq upper-case circumflex I -.It \\(^O -.Pq upper-case circumflex O -.It \\(^U -.Pq upper-case circumflex U -.It \\(^a -.Pq lower-case circumflex a -.It \\(^e -.Pq lower-case circumflex e -.It \\(^i -.Pq lower-case circumflex i -.It \\(^o -.Pq lower-case circumflex o -.It \\(^u -.Pq lower-case circumflex u -.It \\(,C -.Pq upper-case cedilla C -.It \\(,c -.Pq lower-case cedilla c -.It \\(/L -.Pq upper-case stroke L -.It \\(/l -.Pq lower-case stroke l -.It \\(/O -.Pq upper-case stroke O -.It \\(/o -.Pq lower-case stroke o -.It \\(oA -.Pq upper-case ring A -.It \\(oa -.Pq lower-case ring a -.El -.\" PARAGRAPH -.Pp -Monetary: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(Cs -.Pq Scandinavian -.It \\(Do -.Pq dollar -.It \\(Po -.Pq pound -.It \\(Ye -.Pq yen -.It \\(Fn -.Pq florin -.It \\(ct -.Pq cent -.El -.\" PARAGRAPH -.Pp -Special symbols: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(de -.Pq degree -.It \\(ps -.Pq paragraph -.It \\(sc -.Pq section -.It \\(dg -.Pq dagger -.It \\(dd -.Pq double dagger -.It \\(ci -.Pq circle -.It \\(ba -.Pq bar -.It \\(bb -.Pq broken bar -.It \\(Ba -.Pq bar, deprecated -.It \\(co -.Pq copyright -.It \\(rg -.Pq registered -.It \\(tm -.Pq trademarked -.It \\& -.Pq non-breaking space -.It \\e -.Pq escape -.It \\(Am -.Pq ampersand, deprecated -.El .\" SECTION -.Sh ONTOLOGY +.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 @@ -630,8 +210,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, @@ -689,7 +269,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 @@ -698,7 +278,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 , @@ -751,26 +331,28 @@ close at the invocation's end-of-line. .\" PARAGRAPH .Pp The -.Sq \&Op -may be broken by \&Oc as in the following example: +.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 +.Sq \&.Op is technically broken by -.Sq \&Oc , +.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 @@ -854,7 +436,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 n +.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 @@ -882,11 +464,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 @@ -899,52 +481,53 @@ 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 mandoc 1 +.Xr mandoc 1 , +.Xr mandoc_char 7 .\" SECTION .Sh AUTHORS The @@ -958,64 +541,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 +.Sq \&.Rs/.Re blocks. .El