===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.75
retrieving revision 1.79
diff -u -p -r1.75 -r1.79
--- mandoc/mdoc.7	2009/11/06 10:31:31	1.75
+++ mandoc/mdoc.7	2010/01/01 13:35:30	1.79
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.75 2009/11/06 10:31:31 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.79 2010/01/01 13:35:30 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: November 6 2009 $
+.Dd $Mdocdate: January 1 2010 $
 .Dt MDOC 7
 .Os
 .
@@ -132,10 +132,47 @@ 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).  A numerical representation 3, 2, or 1
-(bold, italic, and Roman, respectively) may be used instead.  
+(revert to previous mode):  
 .Pp
-These form is not recommended for 
+.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 valid within
+the current font scope only:  if a macro opens a font scope alongside
+its own scope, such as
+.Sx \&Bf
+.Cm \&Sy ,
+in-scope invocations of
+.Sq \ef
+are only valid within the font scope of the macro.  If
+.Sq \ef
+is specified outside of any font scope, such as in unenclosed, free-form
+text, it will affect the remainder of the document.
+.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
+Note these forms are 
+.Em not
+recommended for 
 .Nm ,
 which encourages semantic annotation.
 .
@@ -1559,6 +1596,22 @@ is provided.
 .Ss \&Fc
 .Ss \&Fd
 .Ss \&Fl
+Command-line flag.  Used when listing arguments to command-line
+utilities.  Prints a fixed-width hyphen
+.Sq \-
+before each delimited argument.  If no arguments are provided, a hyphen
+is still printed.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fl a b c
+\&.Fl
+\&.Op Fl o Ns Ar file
+.Ed
+.Pp
+See also
+.Sx \&Cm .
+.
 .Ss \&Fn
 .Ss \&Fo
 .Ss \&Fr
@@ -1793,9 +1846,22 @@ file re-write
 .Pp
 .Bl -dash -compact
 .It
+Historic 
+.Xr groff 1
+does not print a dash for empty 
+.Sx \&Fl
+arguments.  This behaviour has been discontinued.
+.It
+.Xr groff 1
+behaves strangely (even between versions) when specifying
+.Sq \ef
+escapes within line-macro scopes.  These aberrations have been
+normalised.
+.It
 Negative scaling units are now truncated to zero instead of creating
 interesting conditions, such as with
-.Sq \&sp -1i .
+.Sx \&sp
+.Cm \-1i .
 Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.
@@ -1805,7 +1871,8 @@ standalone double-quote in formatted output.  This idi
 behaviour is no longer applicable.
 .It
 Display types
-.Sx \&Bd Fl center
+.Sx \&Bd
+.Fl center
 and
 .Fl right
 are aliases for
@@ -1835,7 +1902,8 @@ made historic groff
 .Qq go orbital
 but is a proper delimiter in this implementation.
 .It
-.Sx \&It Fl nested
+.Sx \&It
+.Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be
 nested and
 .Fl enum