=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.52 retrieving revision 1.57 diff -u -p -r1.52 -r1.57 --- mandoc/man.7 2009/11/12 08:21:05 1.52 +++ mandoc/man.7 2010/03/23 11:30:48 1.57 @@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.52 2009/11/12 08:21:05 kristaps Exp $ +.\" $Id: man.7,v 1.57 2010/03/23 11:30:48 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 12 2009 $ +.Dd $Mdocdate: March 23 2010 $ .Dt MAN 7 .Os . @@ -102,7 +102,7 @@ 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 @@ -110,6 +110,9 @@ A numerical representation 3, 2, or 1 (bold, italic, a 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 @@ -136,8 +139,7 @@ Both .Sq \es and .Sq \ef -attributes are forgotten when exiting a subsequent (or current) macro -invocation. +attributes are forgotten when entering or exiting a macro block. . . .Ss Whitespace @@ -293,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: @@ -308,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). @@ -359,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 @@ -421,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 @@ -431,63 +433,67 @@ 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 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 @@ -502,7 +508,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 , @@ -513,33 +519,29 @@ 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 +.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 @@ -561,13 +563,13 @@ 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 @@ -817,7 +819,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 @@ -958,7 +960,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 . @@ -968,6 +970,21 @@ macro. Defaults to 1, if unspecified. .Pp 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