=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.33 retrieving revision 1.38 diff -u -p -r1.33 -r1.38 --- mandoc/man.7 2009/08/20 13:32:09 1.33 +++ mandoc/man.7 2009/10/18 19:00:57 1.38 @@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.33 2009/08/20 13:32:09 kristaps Exp $ +.\" $Id: man.7,v 1.38 2009/10/18 19:00:57 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: August 20 2009 $ +.Dd $Mdocdate: October 18 2009 $ .Dt MAN 7 .Os . @@ -119,7 +119,74 @@ from input. These are later re-added, if applicable, utility such as .Xr mandoc 1 . . +.Ss Scaling Widths +Many macros support scaled widths for their arguments, such as +stipulating a two-inch paragraph indentation with the following: +.Bd -literal -offset indent +\&.HP 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 . +. +.Pp +If a scaling unit is not provided, the numerical value is interpreted +under the default rules of +.Sq v +for vertical spaces and +.Sq u +for horizontal ones. +.Em Note : +this differs from +.Xr mdoc 7 , +which, if a unit is not provided, will instead interpret the string as +literal text. +. +. .Sh MANUAL STRUCTURE Each .Nm @@ -205,18 +272,14 @@ foo .Pp is equivalent to .Sq \&.I foo . -.\" PARAGRAPH -Consecutive next-line scope invocations are disallowed. +If next-line macros are invoked consecutively, only the last is used. +If a next-line macro is proceded by a block macro, it is ignored. .Bd -literal -offset indent \&.YO \(lBbody...\(rB \(lBbody...\(rB .Ed . .Pp -It is considered an error when next-line scope is open at the end of -file. -. -.Pp .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" .It Em Macro Ta Em Arguments Ta Em Scope .It B Ta n Ta next-line @@ -232,6 +295,7 @@ file. .It SB Ta n Ta next-line .It SM Ta n Ta next-line .It TH Ta >1, <6 Ta current +.It UC Ta n Ta current .It br Ta 0 Ta current .It fi Ta 0 Ta current .It i Ta n Ta current @@ -245,6 +309,7 @@ file. The .Sq RS , .Sq RE , +.Sq UC , .Sq br , .Sq fi , .Sq i , @@ -253,9 +318,7 @@ The .Sq r , and .Sq sp -macros aren't historically part of -.Nm -and should not be used. They're included for compatibility. +macros should not be used. They're included for compatibility. . . .Ss Block Macros @@ -288,10 +351,6 @@ or No closure refers to an explicit block closing macro. . .Pp -It is considered an error when part or next-line scope is open at the -end of file. -. -.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 HP Ta <2 Ta current Ta paragraph @@ -301,8 +360,8 @@ end of file. .It PP Ta 0 Ta current Ta paragraph .It RE Ta 0 Ta current Ta none .It RS Ta 1 Ta current Ta part -.It SH Ta >0 Ta current Ta section -.It SS Ta >0 Ta current Ta sub-section +.It SH Ta >0 Ta next-line Ta section +.It SS Ta >0 Ta next-line Ta sub-section .It TP Ta n Ta next-line Ta paragraph .El . @@ -311,6 +370,7 @@ If a block macro is next-line scoped, it may only be f macros (excluding .Sq DT , .Sq TH , +.Sq UC , .Sq br , .Sq na , .Sq sp , @@ -324,28 +384,6 @@ This section is a canonical reference to all macros, a alphabetically. For the scoping of individual macros, see .Sx MACRO SYNTAX . . -. -.Ss Definitions -In this reference, a numerical width may be either a standalone natural -number (such as 3, 4, 10, etc.) or a natural number followed by a width -multiplier -.Qq n , -corresponding to the width of the formatted letter n, or -.Qq m , -corresponding to the width of the formatted letter m. The latter is the -default, if unspecified. Thus, -.Bd -literal -offset indent -\&.HP 12n -.Ed -. -.Pp -indicates an offset of 12 -.Qq n -.Ns -sized -letters. -. -. -.Ss Macro Reference .Bl -tag -width Ds .It B Text is rendered in bold face. @@ -365,7 +403,7 @@ render in italics. Whitespace between arguments is om Text is rendered alternately in bold face and roman (the default font). Whitespace between arguments is omitted in output. .It DT -Re-set the tab spacing to 0.5 inches. +Has no effect. Included for compatibility. .It HP Begin a paragraph whose initial output line is left-justified, but subsequent output lines are indented, with the following syntax: @@ -374,7 +412,7 @@ subsequent output lines are indented, with the followi .Ed . .Pp -If +If scaling width .Va width is specified, it's saved for later paragraph left-margins; if unspecified, the saved or default width is used. @@ -420,7 +458,7 @@ Begin a part setting the left margin. The left margin offset, following an initial indentation, to un-indented text such as that of .Sq PP . -The width may be specified as following: +A scaling width may be specified as following: .Bd -literal -offset indent \&.RS [width] .Ed @@ -471,18 +509,18 @@ followed by a newline; if not, the body follows on the buffer to the indentation width. Subsequent output lines are indented. . .Pp -The indentation width may be set as follows: +The indentation scaling width may be set as follows: .Bd -literal -offset indent \&.TP [width] .Ed . .Pp -Where +If .Va width -must be a properly-formed numeric width. If -.Va width is specified, it's saved for later paragraph left-margins; if unspecified, the saved or default width is used. +.It UC +Has no effect. Included for compatibility. .It br Breaks the current line. Consecutive invocations have no further effect. .It fi @@ -492,7 +530,7 @@ End literal mode begun by Italicise arguments. If no arguments are specified, all subsequent text is italicised. .It na -Don't alignment the right margin. +Don't align to the right margin. .It nf Begin literal mode: all subsequent free-form lines have their end of line boundaries preserved. May be ended by