===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.32
retrieving revision 1.38
diff -u -p -r1.32 -r1.38
--- mandoc/man.7	2009/08/20 12:08:40	1.32
+++ mandoc/man.7	2009/10/18 19:00:57	1.38
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.32 2009/08/20 12:08:40 kristaps Exp $
+.\"	$Id: man.7,v 1.38 2009/10/18 19:00:57 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -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
@@ -139,18 +206,27 @@ are generally structured as follows:
 \&.
 \&.SH NAME
 \efBfoo\efR \e(en a description goes here
+\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q .SH LIBRARY
 \&.
 \&.SH SYNOPSIS
 \efBfoo\efR [\efB\e-options\efR] arguments...
 \&.
 \&.SH DESCRIPTION
-The \efBfoo\efR utility does...
+The \efBfoo\efR utility processes files...
 \&.
+\&.\e\*q .SH IMPLEMENTATION NOTES
+\&.\e\*q The next is for sections 1 & 8 only.
+\&.\e\*q .SH EXIT STATUS
+\&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .SH RETURN VALUES
+\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
 \&.\e\*q .SH ENVIRONMENT
 \&.\e\*q .SH FILES
 \&.\e\*q .SH EXAMPLES
+\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .SH DIAGNOSTICS
+\&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .SH ERRORS
 \&.\e\*q .SH SEE ALSO
 \&.\e\*q \efBbar\efR(1)
@@ -159,6 +235,7 @@ The \efBfoo\efR utility does...
 \&.\e\*q .SH AUTHORS
 \&.\e\*q .SH CAVEATS
 \&.\e\*q .SH BUGS
+\&.\e\*q .SH SECURITY CONSIDERATIONS
 .Ed
 .
 .
@@ -195,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
@@ -222,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
@@ -235,6 +309,7 @@ file.
 The
 .Sq RS ,
 .Sq RE ,
+.Sq UC ,
 .Sq br ,
 .Sq fi ,
 .Sq i ,
@@ -243,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
@@ -278,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
@@ -291,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
 .
@@ -301,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 ,
@@ -314,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.
@@ -355,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:
@@ -364,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.
@@ -410,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
@@ -461,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
@@ -482,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