=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.76 retrieving revision 1.87 diff -u -p -r1.76 -r1.87 --- mandoc/mdoc.7 2009/11/09 05:11:46 1.76 +++ mandoc/mdoc.7 2010/03/31 07:13:53 1.87 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.76 2009/11/09 05:11:46 kristaps Exp $ +.\" $Id: mdoc.7,v 1.87 2010/03/31 07:13:53 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 9 2009 $ +.Dd $Mdocdate: March 31 2010 $ .Dt MDOC 7 .Os . @@ -132,12 +132,22 @@ and Terms may be text-decorated using the .Sq \ef escape followed by an indicator: B (bold), I, (italic), R (Roman), or P -(revert to previous mode): +(revert to previous mode): .Pp .D1 \efBbold\efR \efIitalic\efP .Pp A numerical representation 3, 2, or 1 (bold, italic, and Roman, -respectively) may be used instead. +respectively) may be used instead. A text decoration is valid within +the current font scope only: if a macro opens a font scope alongside +its own scope, such as +.Sx \&Bf +.Cm \&Sy , +in-scope invocations of +.Sq \ef +are only valid within the font scope of the macro. If +.Sq \ef +is specified outside of any font scope, such as in unenclosed, free-form +text, it will affect the remainder of the document. .Pp Text may also be sized with the .Sq \es @@ -160,19 +170,19 @@ for arbitrary-digit numerals: .D1 \es+(10much bigger\es-(10 .D1 \es+'100'much much bigger\es-'100' .Pp -Note these forms are +Note these forms are .Em not -recommended for +recommended for .Nm , which encourages semantic annotation. . . .Ss Predefined Strings -Historically, +Historically, .Xr groff 1 -also defined a set of package-specific +also defined a set of package-specific .Dq predefined strings , -which, like +which, like .Sx Special Characters , demark special output characters and strings by way of input codes. Predefined strings are escaped with the slash-asterisk, @@ -333,7 +343,7 @@ and .Sx \&Os macros, is required for every document. .Pp -The first section (sections are denoted by +The first section (sections are denoted by .Sx \&Sh ) must be the NAME section, consisting of at least one .Sx \&Nm @@ -409,6 +419,11 @@ The macro(s) must precede the .Sx \&Nd macro. +.Pp +See +.Sx \&Nm +and +.Sx \&Nd . . .It Em LIBRARY The name of the library containing the documented material, which is @@ -419,12 +434,11 @@ this is as follows: .Ed .Pp See -.Sx \&Lb -for details. +.Sx \&Lb . . .It Em SYNOPSIS Documents the utility invocation syntax, function call syntax, or device -configuration. +configuration. .Pp For the first, utilities (sections 1, 6, and 8), this is generally structured as follows: @@ -455,11 +469,19 @@ And for the third, configurations (section 4): \&.Cd \*qit* at isa? port 0x4e\*q .Ed .Pp -Manuals not in these sections generally don't need a +Manuals not in these sections generally don't need a .Em SYNOPSIS . +.Pp +See +.Sx \&Op , +.Sx \&Cd , +.Sx \&Fn , +.Sx \&Ft , +and +.Sx \&Vt . . .It Em DESCRIPTION -This expands upon the brief, one-line description in +This expands upon the brief, one-line description in .Em NAME . It usually contains a break-down of the options (if documenting a command), such as: @@ -470,6 +492,7 @@ The arguments are as follows: Print verbose information. \&.El .Ed +.Pp Manuals not documenting a command won't include the above fragment. . .It Em IMPLEMENTATION NOTES @@ -525,7 +548,8 @@ for manuals in sections 1, 6, and 8; however, this pra discouraged. .Pp See -.Sx \&Bl No \-diag . +.Sx \&Bl +.Fl diag . . .It Em ERRORS Documents error handling in sections 2, 3, and 9. @@ -659,7 +683,7 @@ All macros have bodies; some don't have heads; only one .Po .Sx \&It Fl column -.Pc +.Pc has multiple heads. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB @@ -746,7 +770,16 @@ or end of line. .It Sx \&Ql Ta Yes Ta Yes .It Sx \&Qq Ta Yes Ta Yes .It Sx \&Sq Ta Yes Ta Yes +.It Sx \&Vt Ta Yes Ta Yes .El +.Pp +Note that the +.Sx \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a SYNOPSIS section line, else it is +.Sx In-line . . . .Ss In-line @@ -839,10 +872,10 @@ then the macro accepts an arbitrary number of argument .It Sx \&Ux Ta Yes Ta Yes Ta n .It Sx \&Va Ta Yes Ta Yes Ta n .It Sx \&Vt Ta Yes Ta Yes Ta >0 -.It Sx \&Xr Ta Yes Ta Yes Ta >0, <3 +.It Sx \&Xr Ta Yes Ta Yes Ta >0 .It Sx \&br Ta \&No Ta \&No Ta 0 .It Sx \&sp Ta \&No Ta \&No Ta 1 -.El +.El . . .Sh REFERENCE @@ -1002,7 +1035,7 @@ a function: .Ed . .Ss \&Aq -Encloses its arguments in angled brackets. +Encloses its arguments in angled brackets. .Pp Examples: .Bd -literal -offset indent @@ -1049,7 +1082,7 @@ Note that these parameters do not begin with a hyphen. .Pp Examples: .Bd -literal -offset indent -\&.At +\&.At \&.At V.1 .Ed .Pp @@ -1150,7 +1183,60 @@ and .Ss \&Bf .Ss \&Bk .Ss \&Bl -. +.\" Begins a list composed of one or more list entries. A list entry is +.\" specified by the +.\" .Sx \&It +.\" macro, which consists of a head and optional body. By default, a list +.\" is preceded by a blank line. A list must specify one of the following +.\" list types: +.\" .Bl -tag -width 12n +.\" .It Fl bullet +.\" A list offset by a bullet. The head of list entries must be empty. +.\" List entry bodies are justified after the bullet. +.\" .It Fl column +.\" A columnated list. The number of columns is specified as arguments to +.\" the +.\" .Sx \&Bl +.\" macro (the deprecated form of following the invocation of +.\" .Fl column +.\" is also accepted). Arguments dictate the width of columns specified in +.\" list entries. List entry bodies must be left empty. Columns specified +.\" in the list entry head are justified to their position in the sequence +.\" of columns. +.\" .It Fl dash +.\" A list offset by a dash (hyphen). The head of list entries must be +.\" empty. List entry bodies are justified past the dash. +.\" .It Fl diag +.\" Like +.\" .Fl inset +.\" lists, but with additional formatting to the head. +.\" .It Fl enum +.\" A list offset by a number indicating list entry position. The head of +.\" list entries must be empty. List entry bodies are justified past the +.\" enumeration. +.\" .It Fl hang +.\" Like +.\" .Fl tag , +.\" but instead of list bodies justifying to the head on the first line, +.\" they trail the head text. +.\" .It Fl hyphen +.\" Synonym for +.\" .Fl dash . +.\" .It Fl inset +.\" Like +.\" .Fl tag , +.\" but list entry bodies aren't justified. +.\" .It Fl item +.\" An un-justified list. This produces blocks of text. +.\" .It Fl ohang +.\" List bodies are placed on the line following the head. +.\" .It Fl tag +.\" A list offset by list entry heads. List entry bodies are justified +.\" after the head. +.\" .El +.\" .Pp +.\" More... +.\" . .Ss \&Bo Begins a block enclosed by square brackets. Does not have any head arguments. @@ -1165,7 +1251,7 @@ See also .Sx \&Bq . . .Ss \&Bq -Encloses its arguments in square brackets. +Encloses its arguments in square brackets. .Pp Examples: .Bd -literal -offset indent @@ -1312,7 +1398,7 @@ manual. Its calling syntax is as follows: .Pp .D1 \. Ns Sx \&Dd Cm date .Pp -The +The .Cm date field may be either .Ar $\&Mdocdate$ , @@ -1361,7 +1447,7 @@ See also .Sx \&Dq . . .Ss \&Dq -Encloses its arguments in double quotes. +Encloses its arguments in double quotes. .Pp Examples: .Bd -literal -offset indent @@ -1467,6 +1553,7 @@ subsequent that. It, too, is optional. It must be on .Ar hppa64 , .Ar i386 , .Ar landisk , +.Ar loongson , .Ar luna88k , .Ar mac68k , .Ar macppc , @@ -1586,6 +1673,22 @@ is provided. .Ss \&Fc .Ss \&Fd .Ss \&Fl +Command-line flag. Used when listing arguments to command-line +utilities. Prints a fixed-width hyphen +.Sq \- +before each delimited argument. If no arguments are provided, a hyphen +is still printed. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fl a b c +\&.Fl +\&.Op Fl o Ns Ar file +.Ed +.Pp +See also +.Sx \&Cm . +. .Ss \&Fn .Ss \&Fo .Ss \&Fr @@ -1799,9 +1902,65 @@ and . .Ss \&Va .Ss \&Vt +A variable type. This is also used for indicating global variables in the +SYNOPSIS section, in which case a variable name is also specified. Note that +it accepts +.Sx Block partial-implicit +syntax when invoked as the first macro in the SYNOPSIS section, else it +accepts ordinary +.Sx In-line +syntax. +.Pp +Note that this should not be confused with +.Sx \&Ft , +which is used for function return types. +.Pp +Examples: +.Bd -literal -offset indent +\&.Vt unsigned char +\&.Vt extern const char * const sys_signame[] ; +.Ed +.Pp +See also +.Sx \&Ft +and +.Sx \&Va . +. .Ss \&Xc +Close a scope opened by +.Sx \&Xo . +. .Ss \&Xo +Open an extension scope. This macro originally existed to extend the +9-argument limit of troff; since this limit has been lifted, the macro +has been deprecated. +. .Ss \&Xr +Link to another manual +.Pq Qq cross-reference . +Its calling syntax is +.Pp +.D1 \. Ns Sx \&Xr Cm name section +.Pp +The +.Cm name +and +.Cm section +are the name and section of the linked manual. If +.Cm section +is followed by non-punctuation, an +.Sx \&Ns +is inserted into the token stream. This behaviour is for compatibility +with +.Xr groff 1 . +.Pp +Examples: +.Bd -literal -offset indent +\&.Xr mandoc 1 +\&.Xr mandoc 1 ; +\&.Xr mandoc 1 s behaviour +.Ed +. .Ss \&br .Ss \&sp . @@ -1820,9 +1979,33 @@ file re-write .Pp .Bl -dash -compact .It +The comment syntax +.Sq \e." +is no longer accepted. +.It +In +.Xr groff 1 , +the +.Sx \&Pa +macro does not format its arguments when used in the FILES section under +certain list types. This irregular behaviour has been discontinued. +.It +Historic +.Xr groff 1 +does not print a dash for empty +.Sx \&Fl +arguments. This behaviour has been discontinued. +.It +.Xr groff 1 +behaves strangely (even between versions) when specifying +.Sq \ef +escapes within line-macro scopes. These aberrations have been +normalised. +.It Negative scaling units are now truncated to zero instead of creating interesting conditions, such as with -.Sq \&sp -1i . +.Sx \&sp +.Fl 1i . Furthermore, the .Sq f scaling unit, while accepted, is rendered as the default unit. @@ -1832,7 +2015,8 @@ standalone double-quote in formatted output. This idi behaviour is no longer applicable. .It Display types -.Sx \&Bd Fl center +.Sx \&Bd +.Fl center and .Fl right are aliases for @@ -1862,7 +2046,8 @@ made historic groff .Qq go orbital but is a proper delimiter in this implementation. .It -.Sx \&It Fl nested +.Sx \&It +.Fl nested is assumed for all lists (it wasn't in historic groff): any list may be nested and .Fl enum