=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.54 retrieving revision 1.63 diff -u -p -r1.54 -r1.63 --- mandoc/mdoc.7 2009/07/27 12:35:54 1.54 +++ mandoc/mdoc.7 2009/10/19 07:34:43 1.63 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.54 2009/07/27 12:35:54 kristaps Exp $ +.\" $Id: mdoc.7,v 1.63 2009/10/19 07:34:43 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,14 +14,16 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 27 2009 $ +.Dd $Mdocdate: October 19 2009 $ .Dt MDOC 7 .Os -.\" SECTION--------------------------------------------- +. +. .Sh NAME .Nm mdoc .Nd mdoc language reference -.\" SECTION--------------------------------------------- +. +. .Sh DESCRIPTION The .Nm mdoc @@ -35,7 +37,7 @@ The .Sx COMPATIBILITY section describes compatibility with .Xr groff 1 . -.\" PARAGRAPH------------ +. .Pp An .Nm @@ -48,7 +50,8 @@ prior macros: \&.Sh Macro lines change control state. Other lines are interpreted within the current state. .Ed -.\" SECTION--------------------------------------------- +. +. .Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space @@ -56,17 +59,21 @@ character, and, in certain circumstances, the tab char manuals must have .Ux line terminators. -.\" SUB-SECTION---------------------- +. +. .Ss Comments Text following a .Sq \e" , whether in a macro or free-form text line, is ignored to the end of line. A macro line with only a control character and comment escape, .Sq \&.\e" , -is also ignored. -.\" SUB-SECTION---------------------- +is also ignored. Macro lines with only a control charater and optionally +whitespace are stripped from input. +. +. .Ss Reserved Characters Within a macro line, the following characters are reserved: +.Pp .Bl -tag -width Ds -offset indent -compact .It \&. .Pq period @@ -91,7 +98,7 @@ Within a macro line, the following characters are rese .It \&| .Pq vertical bar .El -.\" PARAGRAPH------------ +. .Pp Use of reserved characters is described in .Sx MACRO SYNTAX . @@ -99,7 +106,8 @@ For general use in macro lines, these characters must with a non-breaking space .Pq Sq \e& or, if applicable, an appropriate escape sequence used. -.\" SUB-SECTION---------------------- +. +. .Ss Special Characters Special characters may occur in both macro and free-form lines. Sequences begin with the escape character @@ -118,7 +126,8 @@ for a complete list. Examples include and .Sq \ee .Pq back-slash . -.\" SUB-SECTION---------------------- +. +. .Ss Text Decoration Terms may be text-decorated using the .Sq \ef @@ -126,7 +135,8 @@ escape followed by an indicator: B (bold), I, (italic) (Roman, or reset). This form is not recommended for .Nm , which encourages semantic, not presentation, annotation. -.\" SUB-SECTION---------------------- +. +. .Ss Predefined Strings Historically, .Xr groff 1 @@ -151,7 +161,8 @@ for a complete list. Examples include and .Sq \e*(Ba .Pq vertical bar . -.\" SUB-SECTION---------------------- +. +. .Ss Whitespace In non-literal free-form lines, consecutive blocks of whitespace are pruned from input and added later in the output filter, if applicable: @@ -161,25 +172,26 @@ These spaces are pruned from input. These are not. \&.Ed .Ed -.\" PARAGRAPH------------ +. .Pp In macro lines, whitespace delimits arguments and is discarded. If arguments are quoted, whitespace within the quotes is retained. -.\" PARAGRAPH------------ +. .Pp Blank lines are only permitted within literal contexts, as are lines containing only whitespace. Tab characters are only acceptable when delimiting .Sq \&Bl \-column or when in a literal context. -.\" SUB-SECTION---------------------- +. +. .Ss Quotation Macro arguments may be quoted with a double-quote to group space-delimited terms or to retain blocks of whitespace. A quoted argument begins with a double-quote preceded by whitespace. The next double-quote not pair-wise adjacent to another double-quote terminates the literal, regardless of surrounding whitespace. -.\" PARAGRAPH------------ +. .Pp This produces tokens .Sq a" , @@ -193,10 +205,67 @@ considered literal text. Thus, the following produces .Bd -literal -offset indent \&.Em "Em a" .Ed -.\" PARAGRAPH------------ +. .Pp In free-form mode, quotes are regarded as opaque text. -.\" SECTION--------------------------------------------- +. +.Ss Dates +TODO. +. +.Ss Scaling Widths +Many macros support scaled widths for their arguments, such as +stipulating a two-inch list indentation with the following: +.Bd -literal -offset indent +\&.Bl -tag -width 2i +.Ed +. +.Pp +The syntax for scaled widths is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , +where a decimal must be preceded or proceeded by at least one digit. +Negative numbers, while accepted, are truncated to zero. The following +scaling units are accepted: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (~1/6 inch) +.It p +point (~1/72 inch) +.It f +synonym for +.Sq u +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span +.It M +mini-em (~1/100 em) +.El +.Pp +Using anything other than +.Sq m , +.Sq n , +.Sq u , +or +.Sq v +is necessarily non-portable across output media. See +.Sx COMPATIBILITY . +. +. .Sh MANUAL STRUCTURE Each .Nm @@ -213,20 +282,61 @@ followed by \&.Dd $\&Mdocdate$ \&.Dt mdoc 7 \&.Os +\&. \&.Sh NAME -\&.Nm mdoc -\&.Nd mdoc language reference +\&.Nm foo +\&.Nd a description goes here +\&.\e\*q The next is for sections 2 & 3 only. +\&.\e\*q .Sh LIBRARY +\&. +\&.Sh SYNOPSIS +\&.Nm foo +\&.Op Fl options +\&.Ar +\&. +\&.Sh DESCRIPTION +The +\&.Nm +utility processes files ... +\&.\e\*q .Sh IMPLEMENTATION NOTES +\&.\e\*q The next is for sections 1 & 8 only. +\&.\e\*q .Sh EXIT STATUS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .Sh RETURN VALUES +\&.\e\*q The next is for sections 1, 6, 7, & 8 only. +\&.\e\*q .Sh ENVIRONMENT +\&.\e\*q .Sh FILES +\&.\e\*q .Sh EXAMPLES +\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. +\&.\e\*q .Sh DIAGNOSTICS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .Sh ERRORS +\&.\e\*q .Sh SEE ALSO +\&.\e\*q .Xr foobar 1 +\&.\e\*q .Sh STANDARDS +\&.\e\*q .Sh HISTORY +\&.\e\*q .Sh AUTHORS +\&.\e\*q .Sh CAVEATS +\&.\e\*q .Sh BUGS +\&.\e\*q .Sh SECURITY CONSIDERATIONS .Ed -.\" PARAGRAPH------------ +. .Pp Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged, but non-compulsory. -.\" SECTION--------------------------------------------- +. +. .Sh MACRO SYNTAX -Every line beginning with the control character -.Sq \. -is processed for macros, two- or three-character sequences. -.\" PARAGRAPH------------ +Macros are one to three three characters in length and begin with a +control character , +.Sq \&. , +at the beginning of the line. An arbitrary amount of whitespace may +sit between the control character and the macro name. Thus, +.Sq \&.Pp +and +.Sq \&.\ \ \ \&Pp +are equivalent. Macro names are two or three characters in length. +. .Pp The syntax of a macro depends on its classification. In this section, .Sq \-arg @@ -237,18 +347,30 @@ parameters; opens the scope of a macro; and if specified, .Sq \&Yc closes it out. -.\" PARAGRAPH------------ +. .Pp The .Em Callable column indicates that the macro may be called subsequent to the initial -line-macro. The +line-macro. If a macro is not callable, then its invocation after the +initial line macro is interpreted as opaque text, such that +.Sq \&.Fl \&Sh +produces +.Sq Fl \&Sh . +. +.Pp +The .Em Parsable column indicates whether the macro may be followed by further -(ostensibly callable) macros. The +(ostensibly callable) macros. If a macro is not parsable, subsequent +macro invocations on the line will be interpreted as opaque text. +. +.Pp +The .Em Scope column, if applicable, describes closure rules. -.\" SUB-SECTION---------------------- +. +. .Ss Block full-explicit Multi-line scope closed by an explicit closing macro. All macros contains bodies; only @@ -259,7 +381,7 @@ contains a head. \(lBbody...\(rB \&.Yc .Ed -.\" PARAGRAPH------------ +. .Pp .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX" .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope @@ -272,7 +394,8 @@ contains a head. .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk .It \&El Ta \&No Ta \&No Ta opened by \&Bl .El -.\" SUB-SECTION---------------------- +. +. .Ss Block full-implicit Multi-line scope closed by end-of-file or implicitly by another macro. All macros have bodies; some @@ -290,7 +413,7 @@ may have multiple heads. \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB \(lBbody...\(rB .Ed -.\" PARAGRAPH------------ +. .Pp .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX" .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope @@ -299,7 +422,8 @@ may have multiple heads. .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss .El -.\" SUB-SECTION---------------------- +. +. .Ss Block partial-explicit Like block full-explicit, but also with single-line scope. Each has at least a body and, in limited circumstances, a head @@ -314,12 +438,12 @@ and/or tail \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ \(lBbody...\(rB \&Yc \(lBtail...\(rB .Ed -.\" PARAGRAPH------------ +. .Pp .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope -.It \&Ac Ta Yes Ta Yes Ta opened by \&Ao -.It \&Ao Ta Yes Ta Yes Ta closed by \&Ac +.It \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao +.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro @@ -336,14 +460,15 @@ and/or tail .It \&Po Ta Yes Ta Yes Ta opened by \&Pc .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc -.It \&Re Ta \&No Ta \&No Ta opened by \&Rs -.It \&Rs Ta \&No Ta \&No Ta closed by \&Re +.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs +.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re .It \&Sc Ta Yes Ta Yes Ta opened by \&So .It \&So Ta Yes Ta Yes Ta closed by \&Sc .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc .El -.\" SUB-SECTION---------------------- +. +. .Ss Block partial-implicit Like block full-implicit, but with single-line scope closed by .Sx Reserved Characters @@ -351,7 +476,7 @@ or end of line. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB .Ed -.\" PARAGRAPH------------ +. .Pp .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable @@ -367,7 +492,8 @@ or end of line. .It \&Qq Ta Yes Ta Yes .It \&Sq Ta Yes Ta Yes .El -.\" SUB-SECTION---------------------- +. +. .Ss In-line Closed by .Sx Reserved Characters , @@ -383,22 +509,22 @@ then the macro accepts an arbitrary number of argument \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN .Ed -.\" PARAGRAPH------------ +. .Pp .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments -.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 Sx \&%A Ta \&No Ta \&No Ta >0 +.It Sx \&%B Ta \&No Ta \&No Ta >0 +.It Sx \&%C Ta \&No Ta \&No Ta >0 +.It Sx \&%D Ta \&No Ta \&No Ta >0 +.It Sx \&%I Ta \&No Ta \&No Ta >0 +.It Sx \&%J Ta \&No Ta \&No Ta >0 +.It Sx \&%N Ta \&No Ta \&No Ta >0 +.It Sx \&%O Ta \&No Ta \&No Ta >0 +.It Sx \&%P Ta \&No Ta \&No Ta >0 +.It Sx \&%R Ta \&No Ta \&No Ta >0 +.It Sx \&%T Ta \&No Ta \&No Ta >0 +.It Sx \&%V Ta \&No Ta \&No Ta >0 .It \&Ad Ta Yes Ta Yes Ta n .It \&An Ta Yes Ta Yes Ta n .It \&Ap Ta Yes Ta Yes Ta 0 @@ -419,7 +545,7 @@ then the macro accepts an arbitrary number of argument .It \&Er Ta Yes Ta Yes Ta >0 .It \&Es Ta \&No Ta \&No Ta 0 .It \&Ev Ta Yes Ta Yes Ta n -.It \&Ex Ta \&No Ta \&No Ta 0 +.It \&Ex Ta \&No Ta \&No Ta n .It \&Fa Ta Yes Ta Yes Ta n .It \&Fd Ta \&No Ta \&No Ta >0 .It \&Fl Ta Yes Ta Yes Ta n @@ -446,7 +572,7 @@ then the macro accepts an arbitrary number of argument .It \&Pa Ta Yes Ta Yes Ta n .It \&Pf Ta \&No Ta Yes Ta 1 .It \&Pp Ta \&No Ta \&No Ta 0 -.It \&Rv Ta \&No Ta \&No Ta 0 +.It \&Rv Ta \&No Ta \&No Ta n .It \&Sm Ta \&No Ta \&No Ta 1 .It \&St Ta \&No Ta Yes Ta 1 .It \&Sx Ta Yes Ta Yes Ta >0 @@ -459,8 +585,253 @@ then the macro accepts an arbitrary number of argument .It \&Xr Ta Yes Ta Yes Ta >0, <3 .It \&br Ta \&No Ta \&No Ta 0 .It \&sp Ta \&No Ta \&No Ta 1 -.El -.\" SECTION--------------------------------------------- +.El +. +. +.Sh REFERENCE +This section is a canonical reference of all macros, arranged +alphabetically. For the scoping of individual macros, see +.Sx MACRO SYNTAX . +. +.Ss \&%A +Author name of an +.Sx \&Rs +block. Multiple authors should each be accorded their own +.Sq \%%A +line. +.Pp +Author names should be ordered with full or abbreviated forename(s) +first, then full surname. +.Ss \&%B +Book title of an +.Sx \&Rs +block. This macro may also be used in a non-bibliographic context when +referring to book titles. +.Ss \&%C +Publication city or location of an +.Sx \&Rs +block. +.Pp +.Em Compatibility remark : +this macro is not implemented in +.Xr groff 1 . +.Ss \&%D +Publication date of an +.Sx \&Rs +block. This should follow the canonical syntax for +.Sx Dates . +.Ss \&%I +Publisher or issuer name of an +.Sx \&Rs +block. +.Ss \&%J +Journal name of an +.Sx \&Rs +block. +.Ss \&%N +Issue number (usually for journals) of an +.Sx \&Rs +block. +.Ss \&%O +Optional information of an +.Sx \&Rs +block. +.Ss \&%P +Book or journal page number of an +.Sx \&Rs +block. +.Ss \&%Q +Institutional author (school, government, etc.) of an +.Sx \&Rs +block. Multiple institutional authors should each be accorded their own +.Sq \&%Q +line. +.Ss \&%R +Technical report name of an +.Sx \&Rs +block. +.Ss \&%T +Article title of an +.Sx \&Rs +block. This macro may also be used in a non-bibliographical context +when referring to article titles. +.Ss \&%V +Volume number of an +.Sx \&Rs +block. +.Ss \&Ac +Closes an +.Sx \&Ao +block. Does not have any tail arguments. +.Ss \&Ad +Address construct: usually in the context of an computational address in +memory, not a physical (post) address. +.Pp +Example: +.Bd -literal -offset indent +\&.Ad [0,$] +\&.Ad 0x00000000 +.Ed +.Ss \&An +.Ss \&Ao +Begins a block enclosed by angled brackets. Does not have any head +arguments. +.Pp +Example: +.Bd -literal -offset indent +\&.Fl -key= Ns Ao Ar val Ac +.Ed +.Pp +Note that, although this is overwhelmingly used to note URIs, the +.Sx \&Lk +and +.Sx \&Mt +macros are better suited for this purpose. +.Ss \&Ap +.Ss \&Aq +.Ss \&Ar +.Ss \&At +.Ss \&Bc +.Ss \&Bd +.Ss \&Bf +.Ss \&Bk +.Ss \&Bl +.Ss \&Bo +.Ss \&Bq +.Ss \&Brc +.Ss \&Bro +.Ss \&Brq +.Ss \&Bsx +.Ss \&Bt +.Ss \&Bx +.Ss \&Cd +.Ss \&Cm +.Ss \&D1 +.Ss \&Db +.Ss \&Dc +.Ss \&Dd +.Ss \&Dl +.Ss \&Do +.Ss \&Dq +.Ss \&Dt +.Ss \&Dv +.Ss \&Dx +.Ss \&Ec +.Ss \&Ed +.Ss \&Ef +.Ss \&Ek +.Ss \&El +.Ss \&Em +.Ss \&En +.Ss \&Eo +.Ss \&Er +.Ss \&Es +.Ss \&Ev +.Ss \&Ex +.Ss \&Fa +.Ss \&Fc +.Ss \&Fd +.Ss \&Fl +.Ss \&Fn +.Ss \&Fo +.Ss \&Fr +.Ss \&Ft +.Ss \&Fx +.Ss \&Hf +.Ss \&Ic +.Ss \&In +.Ss \&It +.Ss \&Lb +.Ss \&Li +.Ss \&Lk +.Ss \&Lp +.Ss \&Ms +.Ss \&Mt +.Ss \&Nd +.Ss \&Nm +.Ss \&No +.Ss \&Ns +.Ss \&Nx +.Ss \&Oc +.Ss \&Oo +.Ss \&Op +.Ss \&Os +.Ss \&Ot +.Ss \&Ox +.Ss \&Pa +.Ss \&Pc +.Ss \&Pf +.Ss \&Po +.Ss \&Pp +.Ss \&Pq +.Ss \&Qc +.Ss \&Ql +.Ss \&Qo +.Ss \&Qq +.Ss \&Re +Closes a +.Sx \&Rs +block. Does not have any tail arguments. +.Ss \&Rs +Begins a bibliographic +.Pq Dq reference +block. Does not have any head arguments. The block macro and may only +contain +.Sx \&%A , +.Sx \&%B , +.Sx \&%C , +.Sx \&%D , +.Sx \&%I , +.Sx \&%J , +.Sx \&%N , +.Sx \&%O , +.Sx \&%P , +.Sx \&%Q , +.Sx \&%R , +.Sx \&%T , +and +.Sx \&%V +child macros (at least one must be specified). +.Pp +Example: +.Bd -literal -offset indent +\&.Rs +\&.%A J. E. Hopcroft +\&.%A J. D. Ullman +\&.%B Introduction to Automata Theory, Languages, and Computation +\&.%I Addison-Wesley +\&.%C Reading, Massachusettes +\&.%D 1979 +\&.Re +.Ed +.Pp +If an +.Sx \&Rs +block is used within a SEE ALSO section, a vertical space is asserted +before the rendered output, else the block continues on the current +line. +.Ss \&Rv +.Ss \&Sc +.Ss \&Sh +.Ss \&Sm +.Ss \&So +.Ss \&Sq +.Ss \&Ss +.Ss \&St +.Ss \&Sx +.Ss \&Sy +.Ss \&Tn +.Ss \&Ud +.Ss \&Ux +.Ss \&Va +.Ss \&Vt +.Ss \&Xc +.Ss \&Xo +.Ss \&Xr +.Ss \&br +.Ss \&sp +. +. .Sh COMPATIBILITY This section documents compatibility with other roff implementations, at this time limited to @@ -471,11 +842,17 @@ refers to those versions before the .Pa doc.tmac file re-write .Pq somewhere between 1.15 and 1.19 . -.\" PARAGRAPH------------ +. .Pp .Bl -dash -compact -.\" LIST-ITEM .It +Negative scaling units are now truncated to zero instead of creating +interesting conditions, such as with +.Sq \&sp -1i . +Furthermore, the +.Sq f +scaling unit, while accepted, is rendered as the default unit. +.It The .Sq \-split or @@ -484,85 +861,76 @@ argument to .Sq \&An applies to the whole document, not just to the current section as it does in groff. -.\" LIST-ITEM .It In quoted literals, groff allowed pair-wise double-quotes to produce a standalone double-quote in formatted output. This idiosyncratic behaviour is no longer applicable. -.\" LIST-ITEM .It The .Sq \&sp macro does not accept negative numbers. -.\" LIST-ITEM .It Blocks of whitespace are stripped from both macro and free-form text lines (except when in literal mode), while groff would retain whitespace in free-form text lines. -.\" LIST-ITEM .It Historic groff has many un-callable macros. Most of these (excluding some block-level macros) are now callable, conforming to the non-historic groff version. -.\" LIST-ITEM .It The vertical bar .Sq \(ba made historic groff .Qq go orbital but is a proper delimiter in this implementation. -.\" LIST-ITEM .It .Sq \&It \-nested is assumed for all lists (it wasn't in historic groff): 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 preceded by other arguments (instead of proceeded) is not supported. -.\" LIST-ITEM .It The .Sq \&At macro only accepts a single parameter. -.\" 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 In groff, the .Sq \&Fo macro only produces the first parameter. This is no longer the case. .El -.\" SECTION--------------------------------------------- +. +. .Sh SEE ALSO .Xr mandoc 1 , .Xr mandoc_char 7 -.\" SECTION--------------------------------------------- +. +. .Sh AUTHORS The .Nm reference was written by .An Kristaps Dzonsons Aq kristaps@kth.se . -.\" SECTION--------------------------------------------- +. +. .Sh CAVEATS There are many ambiguous parts of mdoc. -.\" PARAGRAPH------------ +. .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 @@ -573,39 +941,33 @@ 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, preceding 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 @@ -613,14 +975,13 @@ 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. -.\" LIST-ITEM .It The \-split and \-nosplit dictates via .Sq \&An are re-set when entering and leaving the AUTHORS section. .El +.