===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.73
retrieving revision 1.77
diff -u -p -r1.73 -r1.77
--- mandoc/mdoc.7	2009/11/02 11:39:40	1.73
+++ mandoc/mdoc.7	2009/11/12 05:50:12	1.77
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.73 2009/11/02 11:39:40 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.77 2009/11/12 05:50:12 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 2 2009 $
+.Dd $Mdocdate: November 12 2009 $
 .Dt MDOC 7
 .Os
 .
@@ -131,10 +131,50 @@ and
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
-escape followed by an indicator: B (bold), I, (italic), or P and R
-(Roman, or reset).  This form is not recommended for 
+escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+(revert to previous mode):  
+.Pp
+.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, not presentation, annotation.
+which encourages semantic annotation.
 .
 .
 .Ss Predefined Strings
@@ -1790,9 +1830,16 @@ file re-write
 .Pp
 .Bl -dash -compact
 .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.
@@ -1802,7 +1849,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
@@ -1832,7 +1880,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