=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.44 retrieving revision 1.58 diff -u -p -r1.44 -r1.58 --- mandoc/man.7 2009/11/02 09:53:15 1.44 +++ mandoc/man.7 2010/03/25 07:28:16 1.58 @@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.44 2009/11/02 09:53:15 kristaps Exp $ +.\" $Id: man.7,v 1.58 2010/03/25 07:28:16 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: March 25 2010 $ .Dt MAN 7 .Os . @@ -67,15 +67,7 @@ line termination. Blank lines are acceptable; where found, the output will assert a vertical space. . -.Pp -The -.Sq \ec -escape is common in historical -.Nm -documents; if encountered at the end of a word, it ensures that the -subsequent word isn't off-set by whitespace. . -. .Ss Comments Text following a .Sq \e\*" , @@ -109,8 +101,45 @@ 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). +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 only valid, if +specified in free-form text, until the next macro invocation; if +specified within a macro, it's only valid until the macro closes scope. +Note that macros like +.Sx \&BR +open and close a font scope with each argument. +.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 +Both +.Sq \es +and +.Sq \ef +attributes are forgotten when entering or exiting a macro block. . . .Ss Whitespace @@ -266,7 +295,7 @@ the C library, this may be as follows: .D1 Standard C Library (libc, -lc) .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: @@ -281,10 +310,10 @@ And for the third, configurations (section 4): .Pp .D1 \&.B name* at cardbus ? function ? .Pp -Manuals not in these sections generally don't need a +Manuals not in these sections generally don't need a .Em SYNOPSIS . .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). @@ -332,7 +361,7 @@ Documents error handling in sections 2, 3, and 9. . .It Em SEE ALSO References other manuals with related topics. This section should exist -for most manuals. +for most manuals. .Pp .D1 \&.BR bar \&( 1 \&), .Pp @@ -394,8 +423,8 @@ subsequent lines until closed by another block macro. .Ss Line Macros Line macros are generally scoped to the current line, with the body consisting of zero or more arguments. If a macro is scoped to the next -line and the line arguments are empty, the next line is used instead, -else the general syntax is used. Thus: +line and the line arguments are empty, the next line, which must be +text, is used instead. Thus: .Bd -literal -offset indent \&.I foo @@ -404,63 +433,69 @@ foo .Pp is equivalent to .Sq \&.I foo . -If next-line macros are invoked consecutively, only the last is used; in -other words, if a next-line macro is preceded by a block macro, it is -ignored. +If next-line macros are invoked consecutively, only the last is used. +If a next-line macro is followed by a non-next-line macro, an error is +raised (unless in the case of +.Sx \&br , +.Sx \&sp , +.Sx \&Sp , +or +.Sx \&na ) . +.Pp +The syntax is as follows: .Bd -literal -offset indent \&.YO \(lBbody...\(rB \(lBbody...\(rB .Ed . .Pp -.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" -.It Em Macro Ta Em Arguments Ta Em Scope -.It Sx \&B Ta n Ta next-line -.It Sx \&BI Ta n Ta current -.It Sx \&BR Ta n Ta current -.It Sx \&DT Ta 0 Ta current -.It Sx \&I Ta n Ta next-line -.It Sx \&IB Ta n Ta current -.It Sx \&IR Ta n Ta current -.It Sx \&PD Ta n Ta current -.It Sx \&R Ta n Ta next-line -.It Sx \&RB Ta n Ta current -.It Sx \&RI Ta n Ta current -.It Sx \&SB Ta n Ta next-line -.It Sx \&SM Ta n Ta next-line -.It Sx \&TH Ta >1, <6 Ta current -.It Sx \&UC Ta n Ta current -.It Sx \&br Ta 0 Ta current -.It Sx \&fi Ta 0 Ta current -.It Sx \&i Ta n Ta current -.It Sx \&na Ta 0 Ta current -.It Sx \&nf Ta 0 Ta current -.It Sx \&r Ta 0 Ta current -.It Sx \&sp Ta 1 Ta current +.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" +.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes +.It Sx \&B Ta n Ta next-line Ta \& +.It Sx \&BI Ta n Ta current Ta \& +.It Sx \&BR Ta n Ta current Ta \& +.It Sx \&DT Ta 0 Ta current Ta \& +.It Sx \&I Ta n Ta next-line Ta \& +.It Sx \&IB Ta n Ta current Ta \& +.It Sx \&IR Ta n Ta current Ta \& +.\" .It Sx \&PD Ta n Ta current Ta compat +.It Sx \&R Ta n Ta next-line Ta \& +.It Sx \&RB Ta n Ta current Ta \& +.It Sx \&RI Ta n Ta current Ta \& +.It Sx \&SB Ta n Ta next-line Ta \& +.It Sx \&SM Ta n Ta next-line Ta \& +.It Sx \&TH Ta >1, <6 Ta current Ta \& +.\" .It Sx \&UC Ta n Ta current Ta compat +.It Sx \&br Ta 0 Ta current Ta compat +.It Sx \&fi Ta 0 Ta current Ta compat +.It Sx \&i Ta n Ta current Ta compat +.It Sx \&na Ta 0 Ta current Ta compat +.It Sx \&nf Ta 0 Ta current Ta compat +.It Sx \&r Ta 0 Ta current Ta compat +.It Sx \&sp Ta 1 Ta current Ta compat +.\" .It Sx \&Sp Ta 0 Ta current Ta compat +.\" .It Sx \&Vb Ta <1 Ta current Ta compat +.\" .It Sx \&Ve Ta 0 Ta current Ta compat .El . .Pp -The -.Sx \&PD , -.Sx \&RS , -.Sx \&RE , -.Sx \&UC , -.Sx \&br , -.Sx \&fi , -.Sx \&i , -.Sx \&na , -.Sx \&nf , -.Sx \&r , -and -.Sx \&sp -macros should not be used. They're included for compatibility. +Macros marked as +.Qq compat +are included for compatibility with the significant corpus of existing +manuals that mix dialects of roff. These macros should not be used for +portable +.Nm +manuals. . . .Ss Block Macros Block macros are comprised of a head and body. Like for in-line macros, the head is scoped to the current line and, in one circumstance, the -next line; the body is scoped to subsequent lines and is closed out by a -subsequent block macro invocation. +next line (the next-line stipulations as in +.Sx Line Macros +apply here as well). +.Pp +The syntax is as follows: .Bd -literal -offset indent \&.YO \(lBhead...\(rB \(lBhead...\(rB @@ -475,7 +510,7 @@ sub-section, closed by a section or .Sx \&SS ; part, closed by a section, sub-section, or .Sx \&RE ; -or paragraph, closed by a section, sub-section, part, +or paragraph, closed by a section, sub-section, part, .Sx \&HP , .Sx \&IP , .Sx \&LP , @@ -486,33 +521,34 @@ or No closure refers to an explicit block closing macro. . .Pp -.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent -.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope -.It Sx \&HP Ta <2 Ta current Ta paragraph -.It Sx \&IP Ta <3 Ta current Ta paragraph -.It Sx \&LP Ta 0 Ta current Ta paragraph -.It Sx \&P Ta 0 Ta current Ta paragraph -.It Sx \&PP Ta 0 Ta current Ta paragraph -.It Sx \&RE Ta 0 Ta current Ta none -.It Sx \&RS Ta 1 Ta current Ta part -.It Sx \&SH Ta >0 Ta next-line Ta section -.It Sx \&SS Ta >0 Ta next-line Ta sub-section -.It Sx \&TP Ta n Ta next-line Ta paragraph +As a rule, block macros may not be nested; thus, calling a block macro +while another block macro scope is open, and the open scope is not +implicitly closed, is syntactically incorrect. +. +.Pp +.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" +.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes +.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& +.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& +.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& +.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& +.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& +.It Sx \&RE Ta 0 Ta current Ta none Ta compat +.It Sx \&RS Ta 1 Ta current Ta part Ta compat +.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& +.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& +.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& .El +.Pp . +Macros marked +.Qq compat +are as mentioned in +.Sx Line Macros . +. .Pp If a block macro is next-line scoped, it may only be followed by in-line -macros (excluding -.Sx \&DT , -.Sx \&PD , -.Sx \&TH , -.Sx \&UC , -.Sx \&br , -.Sx \&na , -.Sx \&sp , -.Sx \&nf , -and -.Sx \&fi ) . +macros for decorating text. . . .Sh REFERENCE @@ -534,24 +570,22 @@ and . . .Ss \&BI -Text is rendered alternately in bold face and italic. Thus, +Text is rendered alternately in bold face and italic. Thus, .Sq .BI this word and that causes .Sq this and .Sq and -to render in bold face, while +to render in bold face, while .Sq word and .Sq that render in italics. Whitespace between arguments is omitted in output. .Pp Examples: -.Bd -filled -offset indent -.Pf \. Sx \&BI -bold italic bold italic -.Ed .Pp +.D1 \&.BI bold italic bold italic +.Pp The output of this example will be emboldened .Dq bold and italicised @@ -604,12 +638,12 @@ If specified, it's saved for later paragraph left-marg saved or default width is used. .Pp See also -.Sx IP , -.Sx LP , -.Sx P , -.Sx PP , +.Sx \&IP , +.Sx \&LP , +.Sx \&P , +.Sx \&PP , and -.Sx TP . +.Sx \&TP . . . .Ss \&I @@ -661,12 +695,12 @@ argument is used as a leading term, flushed to the lef useful for bulleted paragraphs and so on. .Pp See also -.Sx HP , -.Sx LP , -.Sx P , -.Sx PP , +.Sx \&HP , +.Sx \&LP , +.Sx \&P , +.Sx \&PP , and -.Sx TP . +.Sx \&TP . . . .Ss \&IR @@ -692,12 +726,12 @@ subsequent paragraph, sub-section, section, or end of paragraph left-margin width is re-set to the default. .Pp See also -.Sx HP , -.Sx IP , -.Sx P , -.Sx PP , +.Sx \&HP , +.Sx \&IP , +.Sx \&P , +.Sx \&PP , and -.Sx TP . +.Sx \&TP . . . .Ss \&P @@ -705,12 +739,12 @@ Synonym for .Sx \&LP . .Pp See also -.Sx HP , -.Sx IP , -.Sx LP , -.Sx PP , +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&PP , and -.Sx TP . +.Sx \&TP . . . .Ss \&PP @@ -718,12 +752,12 @@ Synonym for .Sx \&LP . .Pp See also -.Sx HP , -.Sx IP , -.Sx LP , -.Sx P , +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&P , and -.Sx TP . +.Sx \&TP . . . .Ss \&R @@ -792,7 +826,7 @@ The .Cm width argument must conform to .Sx Scaling Widths . -If not specified, the saved or default width is used. +If not specified, the saved or default width is used. . . .Ss \&SB @@ -841,9 +875,8 @@ string replaces the default rendered volume, which is manual section. .Pp Examples: -.Bd -filled -offset indent -\&.TH CVS 5 "1992-02-12" GNU -.Ed +.Pp +.D1 \&.TH CVS 5 "1992-02-12" GNU . . .Ss \&TP @@ -864,22 +897,22 @@ If specified, it's saved for later paragraph left-marg unspecified, the saved or default width is used. .Pp See also -.Sx HP , -.Sx IP , -.Sx LP , -.Sx P , +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&P , and -.Sx PP . +.Sx \&PP . +.\" . +.\" . +.\" .Ss \&PD +.\" Has no effect. Included for compatibility. +.\" . +.\" . +.\" .Ss \&UC +.\" Has no effect. Included for compatibility. . . -.Ss \&PD -Has no effect. Included for compatibility. -. -. -.Ss \&UC -Has no effect. Included for compatibility. -. -. .Ss \&br Breaks the current line. Consecutive invocations have no further effect. .Pp @@ -893,8 +926,8 @@ End literal mode begun by . . .Ss \&i -Italicise arguments. If no arguments are specified, all subsequent text -is italicised. +Italicise arguments. Synonym for +.Sx \&I . .Pp See also .Sx \&B , @@ -934,7 +967,7 @@ Insert vertical spaces into output with the following .Op Cm height .Ed .Pp -Insert +Insert .Cm height spaces, which must conform to .Sx Scaling Widths . @@ -945,24 +978,43 @@ macro. Defaults to 1, if unspecified. See also .Sx \&br . . +.\" .Ss \&Sp +.\" A synonym for +.\" .Sx \&sp +.\" .Cm 0.5v . +.\" . +.\" .Ss \&Vb +.\" A synonym for +.\" .Sx \&nf . +.\" Accepts an argument (the height of the formatted space) which is +.\" disregarded. +.\" . +.\" .Ss \&Ve +.\" A synonym for +.\" .Sx \&fi . +.\" . . .Sh COMPATIBILITY -This section documents compatibility with other roff implementations, at -this time limited to -.Xr groff 1 . -.Bl -hyphen +This section documents areas of questionable portability between +implementations of the +.Nm +language. +.Pp +.Bl -dash -compact .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. +In quoted literals, GNU troff allowed pair-wise double-quotes to produce +a standalone double-quote in formatted output. It is not known whether +this behaviour is exhibited by other formatters. .It -The -.Sq sp -macro does not accept negative numbers. +Blocks of whitespace are stripped from macro and free-form text lines +(except when in literal mode) in mandoc. This is not the case for GNU +troff: for maximum portability, whitespace sensitive blocks should be +enclosed in literal contexts. .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. +The +.Sx \&sp +macro does not accept negative values in mandoc. In GNU troff, this +would result in strange behaviour. .El . .