===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.57
retrieving revision 1.62
diff -u -p -r1.57 -r1.62
--- mandoc/mdoc.7	2009/08/20 12:08:40	1.57
+++ mandoc/mdoc.7	2009/10/18 19:01:24	1.62
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.57 2009/08/20 12:08:40 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.62 2009/10/18 19:01:24 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 MDOC 7
 .Os
 .
@@ -67,11 +67,13 @@ Text following a
 whether in a macro or free-form text line, is ignored to the end of
 line.  A macro line with only a control character and comment escape,
 .Sq \&.\e" ,
-is also ignored.
+is also ignored.  Macro lines with only a control charater and optionally
+whitespace are stripped from input.
 .
 .
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:
+.Pp
 .Bl -tag -width Ds -offset indent -compact
 .It \&.
 .Pq period
@@ -207,7 +209,60 @@ considered literal text.  Thus, the following produces
 .Pp
 In free-form mode, quotes are regarded as opaque text.
 .
+.Ss Scaling Widths
+Many macros support scaled widths for their arguments, such as
+stipulating a two-inch list indentation with the following:
+.Bd -literal -offset indent
+\&.Bl -tag -width 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 .
+.
+.
 .Sh MANUAL STRUCTURE
 Each
 .Nm
@@ -224,9 +279,43 @@ followed by
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
 \&.Os
+\&.
 \&.Sh NAME
-\&.Nm mdoc
-\&.Nd mdoc language reference
+\&.Nm foo
+\&.Nd a description goes here
+\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q .Sh LIBRARY
+\&.
+\&.Sh SYNOPSIS
+\&.Nm foo
+\&.Op Fl options
+\&.Ar
+\&.
+\&.Sh DESCRIPTION
+The
+\&.Nm
+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 .Xr foobar 1
+\&.\e\*q .Sh STANDARDS
+\&.\e\*q .Sh HISTORY
+\&.\e\*q .Sh AUTHORS
+\&.\e\*q .Sh CAVEATS
+\&.\e\*q .Sh BUGS
+\&.\e\*q .Sh SECURITY CONSIDERATIONS
 .Ed
 .
 .Pp
@@ -262,9 +351,9 @@ The
 column indicates that the macro may be called subsequent to the initial
 line-macro.  If a macro is not callable, then its invocation after the
 initial line macro is interpreted as opaque text, such that
-.Sq \&.Fl Sh
+.Sq \&.Fl \&Sh
 produces
-.Sq Fl Sh .
+.Sq Fl \&Sh .
 .
 .Pp
 The
@@ -453,7 +542,7 @@ then the macro accepts an arbitrary number of argument
 .It \&Er     Ta    Yes      Ta    Yes      Ta    >0
 .It \&Es     Ta    \&No     Ta    \&No     Ta    0
 .It \&Ev     Ta    Yes      Ta    Yes      Ta    n
-.It \&Ex     Ta    \&No     Ta    \&No     Ta    0
+.It \&Ex     Ta    \&No     Ta    \&No     Ta    n
 .It \&Fa     Ta    Yes      Ta    Yes      Ta    n
 .It \&Fd     Ta    \&No     Ta    \&No     Ta    >0
 .It \&Fl     Ta    Yes      Ta    Yes      Ta    n
@@ -480,7 +569,7 @@ then the macro accepts an arbitrary number of argument
 .It \&Pa     Ta    Yes      Ta    Yes      Ta    n
 .It \&Pf     Ta    \&No     Ta    Yes      Ta    1
 .It \&Pp     Ta    \&No     Ta    \&No     Ta    0
-.It \&Rv     Ta    \&No     Ta    \&No     Ta    0
+.It \&Rv     Ta    \&No     Ta    \&No     Ta    n
 .It \&Sm     Ta    \&No     Ta    \&No     Ta    1
 .It \&St     Ta    \&No     Ta    Yes      Ta    1
 .It \&Sx     Ta    Yes      Ta    Yes      Ta    >0
@@ -509,6 +598,13 @@ file re-write
 .
 .Pp
 .Bl -dash -compact
+.It
+Negative scaling units are now truncated to zero instead of creating
+interesting conditions, such as with
+.Sq \&sp -1i .
+Furthermore, the
+.Sq f
+scaling unit, while accepted, is rendered as the default unit.
 .It
 The
 .Sq \-split