=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.73 retrieving revision 1.80 diff -u -p -r1.73 -r1.80 --- mandoc/mdoc.7 2009/11/02 11:39:40 1.73 +++ mandoc/mdoc.7 2010/01/01 16:27:32 1.80 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.73 2009/11/02 11:39:40 kristaps Exp $ +.\" $Id: mdoc.7,v 1.80 2010/01/01 16:27:32 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 2 2009 $ +.Dd $Mdocdate: January 1 2010 $ .Dt MDOC 7 .Os . @@ -131,10 +131,50 @@ and .Ss Text Decoration Terms may be text-decorated using the .Sq \ef -escape followed by an indicator: B (bold), I, (italic), or P and R -(Roman, or reset). This form is not recommended for +escape followed by an indicator: B (bold), I, (italic), R (Roman), or P +(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. 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 +escape, whose syntax is one of +.Sq \es+-n +for one-digit numerals; +.Sq \es(+-nn +or +.Sq \es+-(nn +for two-digit numerals; and +.Sq \es[+-N] , +.Sq \es+-[N] , +.Sq \es'+-N' , +or +.Sq \es+-'N' +for arbitrary-digit numerals: +.Pp +.D1 \es+1bigger\es-1 +.D1 \es[+10]much bigger\es[-10] +.D1 \es+(10much bigger\es-(10 +.D1 \es+'100'much much bigger\es-'100' +.Pp +Note these forms are +.Em not +recommended for .Nm , -which encourages semantic, not presentation, annotation. +which encourages semantic annotation. . . .Ss Predefined Strings @@ -379,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 @@ -389,8 +434,7 @@ 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 @@ -427,6 +471,14 @@ And for the third, configurations (section 4): .Pp 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 @@ -440,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 @@ -495,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. @@ -1120,7 +1174,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. @@ -1556,6 +1663,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 @@ -1790,9 +1913,29 @@ file re-write .Pp .Bl -dash -compact .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. @@ -1802,7 +1945,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 @@ -1832,7 +1976,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