* doc/groff.texinfo: More info on conditionals.groff-1_17

2 files changed, 703 insertions, 579 deletions

diff --git a/ChangeLog b/ChangeLog
index 3a7885d6..1433547f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2001-04-16  Werner LEMBERG  <wl@gnu.org>
+
+	* doc/groff.texinfo: More info on conditionals.
+
 2001-04-15  Werner LEMBERG  <wl@gnu.org>
 
 	* doc/groff.texinfo: Added some info about groff internals.
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index e164928e..b537d1ac 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -312,26 +312,26 @@ contributions are welcome.  Send them to bug-groff@@gnu.org.
 @end ifinfo
 
 @menu
-* Copying::                     
-* Introduction::                
-* Invoking groff::              
-* Tutorial for Macro Users::    
-* Macro Packages::              
-* gtroff Reference::            
-* Preprocessors::               
-* Output Devices::              
-* File formats::                
-* Installation::                
-* Request Index::               
-* Escape Index::                
-* Operator Index::              
-* Register Index::              
-* Macro Index::                 
-* String Index::                
-* Glyph Name Index::            
-* Font File Keyword Index::     
-* Program and File Index::      
-* Concept Index::               
+* Copying::
+* Introduction::
+* Invoking groff::
+* Tutorial for Macro Users::
+* Macro Packages::
+* gtroff Reference::
+* Preprocessors::
+* Output Devices::
+* File formats::
+* Installation::
+* Request Index::
+* Escape Index::
+* Operator Index::
+* Register Index::
+* Macro Index::
+* String Index::
+* Glyph Name Index::
+* Font File Keyword Index::
+* Program and File Index::
+* Concept Index::
 @end menu
 
 
@@ -745,13 +745,13 @@ use) for about 3@w{ }decades.  It is quite widespread and firmly
 entrenched in the @acronym{UNIX} community.
 
 @menu
-* What Is groff?::              
-* History::                     
-* groff Capabilities::          
-* Macro Package Intro::         
-* Preprocessor Intro::          
-* Output device intro::         
-* Credits::                     
+* What Is groff?::
+* History::
+* groff Capabilities::
+* Macro Package Intro::
+* Preprocessor Intro::
+* Output device intro::
+* Credits::
 @end menu
 
 
@@ -1103,9 +1103,9 @@ prefix is omitted since GNU @code{troff} is the only used incarnation of
 @code{troff}.  Exception: @code{groff} is never replaced by @code{roff}.
 
 @menu
-* Groff Options::               
-* Environment::                 
-* Invocation Examples::         
+* Groff Options::
+* Environment::
+* Invocation Examples::
 @end menu
 
 
@@ -1534,12 +1534,12 @@ groff -man -rD1 -z file
 Check @file{file} with the @file{man} macro package, forcing
 double-sided printing -- don't produce any output.
 
-@c ---------------------------------------------------------------------
-
 @menu
-* grog::                        
+* grog::
 @end menu
 
+@c ---------------------------------------------------------------------
+
 @node grog,  , Invocation Examples, Invocation Examples
 @subsection @code{grog}
 
@@ -1598,8 +1598,8 @@ people.  This chapter covers the material needed to efficiently use a
 macro package.
 
 @menu
-* Basics::                      
-* Common Features::             
+* Basics::
+* Common Features::
 @end menu
 
 
@@ -1783,25 +1783,25 @@ and collected into a @dfn{macro package}.
 All macro packages provide certain common capabilities which fall into
 the following categories.
 
-@c ---------------------------------------------------------------------
-
 @menu
-* Paragraphs::                  
-* Sections and Chapters::       
-* Headers and Footers::         
-* Page Layout Adjustment::      
-* Displays::                    
-* Footnotes and Annotations::   
-* Table of Contents::           
-* Indices::                     
-* Paper Formats::               
-* Multiple Columns::            
-* Font and Size Changes::       
-* Predefined Strings::          
-* Preprocessor Support::        
-* Configuration and Customization::  
+* Paragraphs::
+* Sections and Chapters::
+* Headers and Footers::
+* Page Layout Adjustment::
+* Displays::
+* Footnotes and Annotations::
+* Table of Contents::
+* Indices::
+* Paper Formats::
+* Multiple Columns::
+* Font and Size Changes::
+* Predefined Strings::
+* Preprocessor Support::
+* Configuration and Customization::
 @end menu
 
+@c ---------------------------------------------------------------------
+
 @node Paragraphs, Sections and Chapters, Common Features, Common Features
 @subsection Paragraphs
 @cindex paragraphs
@@ -2027,11 +2027,11 @@ This chapter documents the main macro packages that come with
 @code{groff}.
 
 @menu
-* man::                         
-* mdoc::                        
-* ms::                          
-* me::                          
-* mm::                          
+* man::
+* mdoc::
+* ms::
+* me::
+* mm::
 @end menu
 
 
@@ -2050,12 +2050,12 @@ of @code{groff}.  It is easy to use, and a vast majority of manual pages
 are based on it.
 
 @menu
-* Man options::                 
-* Man usage::                   
-* Man font macros::             
-* Miscellaneous man macros::    
-* Predefined man strings::      
-* Preprocessors in man pages::  
+* Man options::
+* Man usage::
+* Man font macros::
+* Miscellaneous man macros::
+* Predefined man strings::
+* Preprocessors in man pages::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -2115,10 +2115,10 @@ further customization, put additional macros and requests into the file
 package.
 
 @Defmac {TH, title section [@Var{extra1}] [@Var{extra2}] [@Var{extra3}]}
-Sets the title of the man page to @var{title} and the section to
+Set the title of the man page to @var{title} and the section to
 @var{section}, which must have a value between 1 and@w{ }8.  The value
-of @var{section} may also have a string appended, e.g.@: @samp{.pm}, to
-indicate a specific subsection of the man pages.
+of @var{section} may also have a string appended, e.g.@: @samp{.pm},
+to indicate a specific subsection of the man pages.
 
 Both @var{title} and @var{section} are positioned at the left and right
 in the header line (with @var{section} in parentheses immediately
@@ -2138,7 +2138,7 @@ beginning of the file.
 @endDefmac
 
 @Defmac {SH, [@Var{heading}]}
-Sets up an unnumbered section heading sticking out to the left.  Prints
+Set up an unnumbered section heading sticking out to the left.  Prints
 out all the text following @code{SH} up to the end of the line (or the
 text in the next line if there is no argument to @code{SH}) in bold
 face, one size larger than the base document size.  Additionally, the
@@ -2146,7 +2146,7 @@ left margin for the following text is reset to its default value.
 @endDefmac
 
 @Defmac {SS, [@Var{heading}]}
-Sets up an unnumbered (sub)section heading.  Prints out all the text
+Set up an unnumbered (sub)section heading.  Prints out all the text
 following @code{SS} up to the end of the line (or the text in the next
 line if there is no argument to @code{SS}) in bold face, at the same
 size as the base document size.  Additionally, the left margin for the
@@ -2154,41 +2154,42 @@ following text is reset to its default value.
 @endDefmac
 
 @Defmac {TP, [@Var{nnn}]}
-Sets up an indented paragraph with label.  The indentation is set to
-@var{nnn} if that argument is supplied (the default unit is @samp{n} if
-omitted), otherwise it is set to the default indentation value.
+Set up an indented paragraph with label.  The indentation is set to
+@var{nnn} if that argument is supplied (the default unit is @samp{n}
+if omitted), otherwise it is set to the default indentation value.
 
 The first line of text following this macro is interpreted as a string
 to be printed flush-left, as it is appropriate for a label.  It is not
 interpreted as part of a paragraph, so there is no attempt to fill the
 first line with text from the following input lines.  Nevertheless, if
 the label is not as wide as the indentation, then the paragraph starts
-at the same line (but indented), continuing on the following lines.  If
-the label is wider than the indentation, then the descriptive part of
-the paragraph begins on the line following the label, entirely indented.
-Note that neither font shape nor font size of the label is set to a
-default value; on the other hand, the rest of the text has default font
-settings.
+at the same line (but indented), continuing on the following lines.
+If the label is wider than the indentation, then the descriptive part
+of the paragraph begins on the line following the label, entirely
+indented.  Note that neither font shape nor font size of the label is
+set to a default value; on the other hand, the rest of the text has
+default font settings.
 @endDefmac
 
 @Defmac {LP}
 @Defmacx {PP}
 @Defmacx {P}
-These macros are mutual aliases.  Any of them causes a line break at the
-current position, followed by a vertical space downwards by the amount
-specified by the @code{PD} macro.  The font size and shape are reset to
-the default value (10@dmn{pt} roman).  Finally, the current left margin
-is restored.
+These macros are mutual aliases.  Any of them causes a line break at
+the current position, followed by a vertical space downwards by the
+amount specified by the @code{PD} macro.  The font size and shape are
+reset to the default value (10@dmn{pt} roman).  Finally, the current
+left margin is restored.
 @endDefmac
 
 @Defmac {IP, [@Var{designator}] [@Var{nnn}]}
-Sets up an indented paragraph, using @var{designator} as a tag to mark
-its beginning.  The indentation is set to @var{nnn} if that argument is
-supplied (default unit is @samp{n}), otherwise the default indentation
-value is used.  Font size and face of the paragraph (but not the
-designator) are reset to their default values.  To start an indented
-paragraph with a particular indentation but without a designator, use
-@samp{""} (two double quotes) as the first argument of @code{IP}.
+Set up an indented paragraph, using @var{designator} as a tag to mark
+its beginning.  The indentation is set to @var{nnn} if that argument
+is supplied (default unit is @samp{n}), otherwise the default
+indentation value is used.  Font size and face of the paragraph (but
+not the designator) are reset to their default values.  To start an
+indented paragraph with a particular indentation but without a
+designator, use @samp{""} (two double quotes) as the first argument of
+@code{IP}.
 
 For example, to start a paragraph with bullets as the designator and
 4@dmn{en} indentation, write
@@ -2200,7 +2201,7 @@ For example, to start a paragraph with bullets as the designator and
 
 @cindex hanging indentation, in manual pages
 @Defmac {HP, [@Var{nnn}]}
-Sets up a paragraph with hanging left indentation.  The indentation is
+Set up a paragraph with hanging left indentation.  The indentation is
 set to @var{nnn} if that argument is supplied (default unit is
 @samp{n}), otherwise the default indentation value is used.  Font size
 and face are reset to their default values.
@@ -2208,16 +2209,16 @@ and face are reset to their default values.
 
 @cindex left margin, how to move, in manual pages
 @Defmac {RS, [@Var{nnn}]}
-This macro moves the left margin to the right by the value @var{nnn} if
-specified (default unit is @samp{n}); otherwise the default indentation
-value is used.  Calls to the @code{RS} macro can be nested.
+Move the left margin to the right by the value @var{nnn} if specified
+(default unit is @samp{n}); otherwise the default indentation value is
+used.  Calls to the @code{RS} macro can be nested.
 @endDefmac
 
 @Defmac {RE, [@Var{nnn}]}
-This macro moves the left margin back to level @var{nnn}; if no argument
-is given, it moves one level back.  The first level (i.e., no call to
-@code{RS} yet) has number@w{ }1, and each call to @code{RS} increases
-the level by@w{ }1.
+Move the left margin back to level @var{nnn}; if no argument is given,
+it moves one level back.  The first level (i.e., no call to @code{RS}
+yet) has number@w{ }1, and each call to @code{RS} increases the level
+by@w{ }1.
 @endDefmac
 
 @maindex SH
@@ -2248,18 +2249,18 @@ vertical space.
 The standard font is roman; the default text size is 10@w{ }point.
 
 @Defmac {SM, [@Var{text}]}
-Sets the text on the same line or the text on the next line in a font
+Set the text on the same line or the text on the next line in a font
 that is one point size smaller than the default font.
 @endDefmac
 
 @cindex boldface, in manual pages
 @Defmac {SB, [@Var{text}]}
-Sets the text on the same line or the text on the next line in boldface
+Set the text on the same line or the text on the next line in boldface
 font, one point size smaller than the default font.
 @endDefmac
 
 @Defmac {BI, text}
-Sets its arguments alternately in bold face and italic.  Thus,
+Set its arguments alternately in bold face and italic.  Thus,
 
 @Example
 .BI this "word and" that
@@ -2271,41 +2272,41 @@ italics.
 @endDefmac
 
 @Defmac {IB, text}
-Sets its arguments alternately in italic and bold face.
+Set its arguments alternately in italic and bold face.
 @endDefmac
 
 @Defmac {RI, text}
-Sets its arguments alternately in roman and italic.
+Set its arguments alternately in roman and italic.
 @endDefmac
 
 @Defmac {IR, text}
-Sets its arguments alternately in italic and roman.
+Set its arguments alternately in italic and roman.
 @endDefmac
 
 @Defmac {BR, text}
-Sets its arguments alternately in bold face and roman.
+Set its arguments alternately in bold face and roman.
 @endDefmac
 
 @Defmac {RB, text}
-Sets its arguments alternately in roman and bold face.
+Set its arguments alternately in roman and bold face.
 @endDefmac
 
 @Defmac {R, [@Var{text}]}
-Sets @var{text} in roman font.  If no text is present on the line where
+Set @var{text} in roman font.  If no text is present on the line where
 the macro is called, then the text of the next line appears in roman.
 This is the default font to which text is returned at the end of
 processing of the other macros.
 @endDefmac
 
 @Defmac {B, [@Var{text}]}
-Sets @var{text} in bold face.  If no text is present on the line where
+Set @var{text} in bold face.  If no text is present on the line where
 the macro is called, then the text of the next line appears in bold
 face.
 @endDefmac
 
 @cindex italic, in manual pages
 @Defmac {I, [@Var{text}]}
-Sets @var{text} in italic.  If no text is present on the line where the
+Set @var{text} in italic.  If no text is present on the line where the
 macro is called, then the text of the next line appears in italic.
 @endDefmac
 
@@ -2323,17 +2324,17 @@ The default indentation is 7.2@dmn{n} for all output devices except for
 @maindex TH
 @cindex tab stops, in manual pages
 @Defmac {DT}
-Sets tabs every 0.5@w{ }inches.  Since this macro is always called
+Set tabs every 0.5@w{ }inches.  Since this macro is always called
 during a @code{TH} request, it makes sense to call it only if the tab
 positions have been changed.
 @endDefmac
 
 @cindex empty space before a paragraph, in manual pages
 @Defmac {PD, [@Var{nnn}]}
-Adjusts the empty space before a new paragraph (or section).  The
-optional argument gives the amount of space (default unit is @samp{v});
-without parameter, the value is reset to its default value (1@w{ }line
-for tty devices, 0.4@dmn{v}@w{ }otherwise).
+Adjust the empty space before a new paragraph (or section).  The
+optional argument gives the amount of space (default unit is
+@samp{v}); without parameter, the value is reset to its default value
+(1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise).
 @endDefmac
 
 @maindex SH
@@ -2451,40 +2452,40 @@ Users of macro packages may skip it if not interested in details.
 
 
 @menu
-* Text::                        
-* Input Conventions::           
-* Measurements::                
-* Expressions::                 
-* Identifiers::                 
-* Embedded Commands::           
-* Registers::                   
-* Manipulating Filling and Adjusting::  
-* Manipulating Hyphenation::    
-* Manipulating Spacing::        
-* Tabs and Fields::             
-* Character Translations::      
-* Troff and Nroff Mode::        
-* Line Layout::                 
-* Page Layout::                 
-* Page Control::                
-* Fonts::                       
-* Sizes::                       
-* Strings::                     
-* Conditionals and Loops::      
-* Writing Macros::              
-* Page Motions::                
-* Drawing Requests::            
-* Traps::                       
-* Diversions::                  
-* Environments::                
-* Suppressing output::          
-* I/O::                         
-* Postprocessor Access::        
-* Miscellaneous::               
-* Groff Internals::             
-* Debugging::                   
-* Implementation Differences::  
-* Summary::                     
+* Text::
+* Input Conventions::
+* Measurements::
+* Expressions::
+* Identifiers::
+* Embedded Commands::
+* Registers::
+* Manipulating Filling and Adjusting::
+* Manipulating Hyphenation::
+* Manipulating Spacing::
+* Tabs and Fields::
+* Character Translations::
+* Troff and Nroff Mode::
+* Line Layout::
+* Page Layout::
+* Page Control::
+* Fonts::
+* Sizes::
+* Strings::
+* Conditionals and Loops::
+* Writing Macros::
+* Page Motions::
+* Drawing Requests::
+* Traps::
+* Diversions::
+* Environments::
+* Suppressing output::
+* I/O::
+* Postprocessor Access::
+* Miscellaneous::
+* Gtroff Internals::
+* Debugging::
+* Implementation Differences::
+* Summary::
 @end menu
 
 
@@ -2513,11 +2514,11 @@ inserting implicit line breaks
 @end itemize
 
 @menu
-* Filling and Adjusting::       
-* Hyphenation::                 
-* Sentences::                   
-* Tab Stops::                   
-* Implicit Line Breaks::        
+* Filling and Adjusting::
+* Hyphenation::
+* Sentences::
+* Tab Stops::
+* Implicit Line Breaks::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -2814,7 +2815,7 @@ Vertical space.  This is equivalent to the current line spacing.
 @end table
 
 @menu
-* Default Units::               
+* Default Units::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -3041,14 +3042,12 @@ accesses the glyph @samp{foo}, followed by @samp{]}, whereas
 @c XXX xref
 
 @Defesc {\\A, ', ident, '}
-Use the @code{\A} escape to test
-whether an identifier @var{ident} is valid in @code{gtroff}.
-It expands to the character@w{ }1
-or@w{ }0 according to whether its argument (usually delimited by quotes)
-is or is not acceptable as the name of a string, macro, diversion,
-number register, environment, or font.  It returns@w{ }0 if no
-argument is given.  This is useful for looking up user input in some
-sort of associative table.
+Test whether an identifier @var{ident} is valid in @code{gtroff}.  It
+expands to the character@w{ }1 or@w{ }0 according to whether its
+argument (usually delimited by quotes) is or is not acceptable as the
+name of a string, macro, diversion, number register, environment, or
+font.  It returns@w{ }0 if no argument is given.  This is useful for
+looking up user input in some sort of associative table.
 
 @Example
 \A'end-list'
@@ -3125,9 +3124,9 @@ Escapes generally do more minor operations like sub- and superscripts,
 print a symbol, etc.
 
 @menu
-* Requests::                    
-* Macros::                      
-* Escapes::                     
+* Requests::
+* Macros::
+* Escapes::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -3208,7 +3207,7 @@ requests cause a break implicitly; using the single quote control
 character prevents this.
 
 @menu
-* Request Arguments::           
+* Request Arguments::
 @end menu
 
 @node Request Arguments,  , Requests, Requests
@@ -3471,7 +3470,7 @@ more information.
 @xref{Identifiers}, and @ref{Character Translations}.
 
 @menu
-* Comments::                    
+* Comments::
 @end menu
 
 @node Comments,  , Escapes, Escapes
@@ -3489,10 +3488,11 @@ This may sound simple, but it can be tricky to keep the comments from
 interfering with the appearance of the final output.
 
 @rqindex ds
-If the escape is to the right of some text or a request, that portion of
-the line is ignored, but the space leading up to it is noticed
-by @code{gtroff}.  This only affects the @code{.ds} request.
-@c XXX (any others?)
+@rqindex as
+If the escape is to the right of some text or a request, that portion
+of the line is ignored, but the space leading up to it is noticed by
+@code{gtroff}.  This only affects the @code{.ds} and @code{.as}
+request.
 
 @cindex tabs before comments
 @cindex comments, lining up with tabs
@@ -3532,9 +3532,9 @@ quotes (@code{'''}) at the beginning of a line.  This works, but
 @endDefesc
 
 @Defesc {\\#, , , }
-To avoid all this, @code{gtroff} has a new comment mechanism using
-the @code{\#} escape.  This escape works the same as @code{\"} except
-that the newline is also ignored:
+To avoid all this, @code{gtroff} has a new comment mechanism using the
+@code{\#} escape.  This escape works the same as @code{\"} except that
+the newline is also ignored:
 
 @Example
 Test
@@ -3554,10 +3554,9 @@ as expected.
 @endDefesc
 
 @Defreq {ig, yy}
-Ignores all input until @code{gtroff} encounters the macro named
-@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy}
-is not specified).  This is useful for commenting out large
-blocks of text:
+Ignore all input until @code{gtroff} encounters the macro named
+@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not
+specified).  This is useful for commenting out large blocks of text:
 
 @Example
 text text text...
@@ -3602,11 +3601,11 @@ details of formatting parameters.
 @xref{Identifiers}, for details on register identifiers.
 
 @menu
-* Setting Registers::           
-* Interpolating Registers::     
-* Auto-increment::              
-* Assigning Formats::           
-* Built-in Registers::          
+* Setting Registers::
+* Interpolating Registers::
+* Auto-increment::
+* Assigning Formats::
+* Built-in Registers::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -3621,8 +3620,8 @@ Define or set registers using the @code{nr} request or the
 
 @Defreq {nr, ident value}
 @Defescx {\\R, ', ident value, '}
-Set number register @var{ident} to @var{value}.  If @var{ident} doesn't
-exist, @code{gtroff} creates it.
+Set number register @var{ident} to @var{value}.  If @var{ident}
+doesn't exist, @code{gtroff} creates it.
 
 The argument to @code{\R} usually has to be enclosed in quotes.
 @xref{Escapes}, for details on parameter delimiting characters.
@@ -3694,11 +3693,10 @@ Rename number register @var{ident1} to @var{ident2}.  If either
 @endDefreq
 
 @Defreq {aln, ident1 ident2}
-This request creates an alias @var{ident1} for a number register
-@var{ident2}.  The new name and the old name are exactly equivalent.
-If @var{ident1} is undefined, a warning of type @samp{reg} is
-generated, and the request is ignored.  @xref{Debugging}, for
-information about warnings.
+Create an alias @var{ident1} for a number register @var{ident2}.  The
+new name and the old name are exactly equivalent.  If @var{ident1} is
+undefined, a warning of type @samp{reg} is generated, and the request
+is ignored.  @xref{Debugging}, for information about warnings.
 @endDefreq
 
 @c ---------------------------------------------------------------------
@@ -3710,14 +3708,18 @@ information about warnings.
 
 Numeric registers can be accessed via the @code{\n} escape.
 
+@cindex nested assignments
+@cindex assignments, nested
+@cindex indirect assignments
+@cindex assignments, indirect
 @Defesc {\\n, , i, }
 @Defescx {\\n, @lparen{}, id, }
 @Defescx {\\n, @lbrack{}, ident, @rbrack}
-@c XXX is the following correct?
 Interpolate number register with name @var{ident} (one-character name
-@var{i}, two-character name @var{id}).  This means that the value of the
-register is expanded in-place while @code{gtroff} is parsing the input
-line.
+@var{i}, two-character name @var{id}).  This means that the value of
+the register is expanded in-place while @code{gtroff} is parsing the
+input line.  Nested assignments (also called indirect assignments) are
+possible.
 
 @Example
 .nr a 5
@@ -3725,6 +3727,17 @@ line.
 \n(as
     @result{} 10
 @endExample
+
+@Example
+.nr a1 5
+.nr ab 6
+.ds str b
+.ds num 1
+\n[a\n[num]]
+    @result{} 5
+\n[a\*[str]]
+    @result{} 6
+@endExample
 @endDefesc
 
 @c ---------------------------------------------------------------------
@@ -3734,19 +3747,19 @@ line.
 @cindex auto-increment
 @cindex increment, automatic
 
-Number registers can also be auto-incremented and auto-decremented.  The
-increment or decrement value can be specified with a third argument to
-the @code{nr} request or @code{\R} escape.
+Number registers can also be auto-incremented and auto-decremented.
+The increment or decrement value can be specified with a third
+argument to the @code{nr} request or @code{\R} escape.
 
 @esindex \R
 @Defreq {nr, ident value incr}
 Set number register @var{ident} to @var{value}; the increment for
-auto-incrementing is set to @var{incr}.  Note that the @code{\R} escape
-doesn't support this notation.
+auto-incrementing is set to @var{incr}.  Note that the @code{\R}
+escape doesn't support this notation.
 @endDefreq
 
-To activate auto-incrementing, the escape @code{\n} has a special syntax
-form.
+To activate auto-incrementing, the escape @code{\n} has a special
+syntax form.
 
 @Defesc {\\n, +, i, }
 @Defescx {\\n, -, i, }
@@ -3758,11 +3771,11 @@ form.
 @Defescx {\\n, @lbrack{}-, ident, @rbrack{}}
 @Defescx {\\n, +@lbrack{}, ident, @rbrack{}}
 @Defescx {\\n, -@lbrack{}, ident, @rbrack{}}
-Before interpolating, increment or decrement @var{ident} (one-character
-name @var{i}, two-character name @var{id}) by the auto-increment value
-as specified with the @code{nr} request (or the @code{\R} escape).  If
-no auto-increment value has been specified, these syntax forms are
-identical to @code{\n}.
+Before interpolating, increment or decrement @var{ident}
+(one-character name @var{i}, two-character name @var{id}) by the
+auto-increment value as specified with the @code{nr} request (or the
+@code{\R} escape).  If no auto-increment value has been specified,
+these syntax forms are identical to @code{\n}.
 @endDefesc
 
 For example,
@@ -3802,17 +3815,17 @@ To change the increment value without changing the value of a register
 @cindex assigning formats
 @cindex formats, assigning
 
-When a register is used in the text of an input file (as opposed to part
-of an expression), it is textually replaced (or interpolated) with a
-representation of that number.  This output format can be changed to a
-variety of formats (numbers, Roman numerals, etc.).  This is done using
-the @code{af} request.
+When a register is used in the text of an input file (as opposed to
+part of an expression), it is textually replaced (or interpolated)
+with a representation of that number.  This output format can be
+changed to a variety of formats (numbers, Roman numerals, etc.).  This
+is done using the @code{af} request.
 
 @Defreq {af, ident format}
 Change the output format of a number register.  The first argument
 @var{ident} is the name of the number register to be changed, and the
-second argument @var{format} is the output format.  The following output
-formats are available:
+second argument @var{format} is the output format.  The following
+output formats are available:
 
 @table @code
 @item 1
@@ -3886,10 +3899,10 @@ then apply the @code{af} request to this other register.
 @Defescx {\\g, @lparen{}, id, }
 @Defescx {\\g, @lbrack{}, ident, @rbrack{}}
 Return the current format of the specified register @var{ident}
-(one-character name @var{i}, two-character name @var{id}).  For example,
-@samp{\ga} after the previous example would produce the string
-@samp{000}.  If the register hasn't been defined yet, nothing is
-returned.
+(one-character name @var{i}, two-character name @var{id}).  For
+example, @samp{\ga} after the previous example would produce the
+string @samp{000}.  If the register hasn't been defined yet, nothing
+is returned.
 @endDefesc
 
 @c ---------------------------------------------------------------------
@@ -4213,23 +4226,24 @@ is formatted as
 @Defregx {.ss}
 @Defregx {.sss}
 Change the minimum size of a space between filled words.  It takes its
-units as one twelfth of the space width parameter for the current font.
-Initially both the @var{word_space_size} and @var{sentence_space_size}
-are@w{ }12.
+units as one twelfth of the space width parameter for the current
+font.  Initially both the @var{word_space_size} and
+@var{sentence_space_size} are@w{ }12.
 
 @cindex fill mode
 @cindex mode, fill
-If two arguments are given to the @code{ss} request, the second argument
-sets the sentence space size.  If the second argument is not given,
-sentence space size is set to @var{word_space_size}.  The sentence space
-size is used in two circumstances: If the end of a sentence occurs at
-the end of a line in fill mode, then both an inter-word space and a
-sentence space are added; if two spaces follow the end of a sentence in
-the middle of a line, then the second space is a sentence space.  If a
-second argument is never given to the @code{ss} request, the behaviour
-of @acronym{UNIX} @code{troff} is the same as that exhibited by GNU
-@code{troff}.  In GNU @code{troff}, as in @acronym{UNIX} @code{troff}, a
-sentence should always be followed by either a newline or two spaces.
+If two arguments are given to the @code{ss} request, the second
+argument sets the sentence space size.  If the second argument is not
+given, sentence space size is set to @var{word_space_size}.  The
+sentence space size is used in two circumstances: If the end of a
+sentence occurs at the end of a line in fill mode, then both an
+inter-word space and a sentence space are added; if two spaces follow
+the end of a sentence in the middle of a line, then the second space
+is a sentence space.  If a second argument is never given to the
+@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
+same as that exhibited by GNU @code{troff}.  In GNU @code{troff}, as
+in @acronym{UNIX} @code{troff}, a sentence should always be followed
+by either a newline or two spaces.
 
 The read-only number registers @code{.ss} and @code{.sss} hold the
 values of the parameters set by the first and second arguments of the
@@ -4294,10 +4308,10 @@ The basic length for centering text is the line length (as set with the
 @code{ll} request) minus the indentation (as set with the @code{in}
 request).  Temporary indentation is ignored.
 
-As can be seen in the previous example, it is a common idiom to turn on
-centering for a large number of lines, and to turn off centering after
-text to be centered.  This is useful for any request which takes a
-number of lines as an argument.
+As can be seen in the previous example, it is a common idiom to turn
+on centering for a large number of lines, and to turn off centering
+after text to be centered.  This is useful for any request which takes
+a number of lines as an argument.
 
 The @code{.ce} read-only number register contains the number of lines
 remaining to be centered, as set by the @code{ce} request.
@@ -4309,9 +4323,9 @@ remaining to be centered, as set by the @code{ce} request.
 @Defreq {rj, [@Var{nnn}]}
 @Defregx {.rj}
 Justify unfilled text to the right margin.  Arguments are identical to
-the @code{ce} request.  The @code{.rj} read-only number register is the
-number of lines to be right-justified as set by the @code{rj} request.
-This request causes a break.
+the @code{ce} request.  The @code{.rj} read-only number register is
+the number of lines to be right-justified as set by the @code{rj}
+request.  This request causes a break.
 @endDefreq
 
 
@@ -4358,8 +4372,9 @@ The hyphenation mode is associated with the current environment
 @endDefreq
 
 @Defreq {nh, }
-Disable hyphenation (i.e., set the hyphenation mode to zero).  Note that
-the hyphenation mode of the last call to @code{hy} is not remembered.
+Disable hyphenation (i.e., set the hyphenation mode to zero).  Note
+that the hyphenation mode of the last call to @code{hy} is not
+remembered.
 
 The hyphenation mode is associated with the current environment
 (@pxref{Environments}).
@@ -4374,13 +4389,13 @@ The hyphenation mode is associated with the current environment
 @Defreq {hlm, [@Var{nnn}]}
 @Defregx {.hlm}
 @Defregx {.hlc}
-Set the maximum number of consecutive hyphenated lines to @var{nnn}.  If
-this number is negative, there is no maximum.  The default value is@w{
-}@minus{}1 if @var{nnn} is omitted.  This value is associated with the
-current environment (@pxref{Environments}).  Only lines output from a
-given environment count towards the maximum associated with that
-environment.  Hyphens resulting from @code{\%} are counted; explicit
-hyphens are not.
+Set the maximum number of consecutive hyphenated lines to @var{nnn}.
+If this number is negative, there is no maximum.  The default value
+is@w{ }@minus{}1 if @var{nnn} is omitted.  This value is associated
+with the current environment (@pxref{Environments}).  Only lines
+output from a given environment count towards the maximum associated
+with that environment.  Hyphens resulting from @code{\%} are counted;
+explicit hyphens are not.
 
 The current setting of @code{hlm} is available in the @code{.hlm}
 read-only number register.  Also the number of immediately preceding
@@ -4419,20 +4434,21 @@ longer a restriction.
 @cindex disabling hyphenation
 @cindex hyphenation, disabling
 @Defesc {\\%, , , }
-To tell @code{gtroff} how to hyphenate words on the fly, use the @code{\%}
-escape, also known as the @dfn{hyphenation character}.
+To tell @code{gtroff} how to hyphenate words on the fly, use the
+@code{\%} escape, also known as the @dfn{hyphenation character}.
 Preceding a word with this character prevents it from being
-hyphenated; putting it inside a word indicates to @code{gtroff} that the
-word may be hyphenated at that point.  Note that this mechanism
-only affects that one occurrence of the word; to change the hyphenation
-of a word for the entire document, use the @code{hw} request.
+hyphenated; putting it inside a word indicates to @code{gtroff} that
+the word may be hyphenated at that point.  Note that this mechanism
+only affects that one occurrence of the word; to change the
+hyphenation of a word for the entire document, use the @code{hw}
+request.
 @endDefesc
 
 @Defreq {hc, [@Var{char}]}
-Change the hyphenation character to @var{char}.  This character
-then works the same as the @code{\%} escape, and thus, no longer appears
-in the output.  Without an argument, @code{hc} resets the
-hyphenation character to be @code{\%} (the default) only.
+Change the hyphenation character to @var{char}.  This character then
+works the same as the @code{\%} escape, and thus, no longer appears in
+the output.  Without an argument, @code{hc} resets the hyphenation
+character to be @code{\%} (the default) only.
 
 The hyphenation character is associated with the current environment
 (@pxref{Environments}).
@@ -4441,10 +4457,9 @@ The hyphenation character is associated with the current environment
 @cindex hyphenation patterns
 @cindex patterns for hyphenation
 @Defreq {hpf, pattern_file}
-Read in a file of hyphenation patterns.  This file is searched for
-in the same way as @file{@var{name}.tmac} (or
-@file{tmac.@var{name}}) is searched for if the @option{-m@var{name}}
-option is specified.
+Read in a file of hyphenation patterns.  This file is searched for in
+the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
+searched for if the @option{-m@var{name}} option is specified.
 
 It should have the same format as the argument to the @code{\patterns}
 primitive in @TeX{} (without using @TeX{}'s macro expansion); the
@@ -4472,12 +4487,13 @@ language.
 @cindex hyphenation code
 @cindex code, hyphenation
 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
-Sets the hyphenation code of character @var{c1} to @var{code1}, that of
-@var{c2} to @var{code2}, etc.  A hyphenation code must be a single input
-character (not a special character) other than a digit or a space.
-Initially each lower-case letter (@samp{a}-@samp{z}) has its hyphenation
-set to itself, and each upper-case letter (@samp{A}-@samp{Z}) has a
-hyphenation code which is the lower-case version of itself.
+Set the hyphenation code of character @var{c1} to @var{code1}, that of
+@var{c2} to @var{code2}, etc.  A hyphenation code must be a single
+input character (not a special character) other than a digit or a
+space.  Initially each lower-case letter (@samp{a}-@samp{z}) has its
+hyphenation set to itself, and each upper-case letter
+(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
+version of itself.
 
 This request is ignored if it has no parameter.
 @endDefreq
@@ -4489,9 +4505,9 @@ This request is ignored if it has no parameter.
 @Defregx {.hym}
 Set the (right) hyphenation margin to @var{length}.  If the current
 adjustment mode is not @samp{b} or@w{ }@samp{n}, the line is not
-hyphenated if it is shorter than @var{length}.  Without an argument, the
-hyphenation margin is reset to its default value, which is@w{ }0.  The
-default scaling indicator for this request is@w{ }@code{m}.  The
+hyphenated if it is shorter than @var{length}.  Without an argument,
+the hyphenation margin is reset to its default value, which is@w{ }0.
+The default scaling indicator for this request is@w{ }@code{m}.  The
 hyphenation margin is associated with the current environment
 (@pxref{Environments}).
 
@@ -4508,12 +4524,13 @@ number register.
 @Defreq {hys, [@Var{hyphenation_space}]}
 @Defregx {.hys}
 Set the hyphenation space to @var{hyphenation_space}.  If the current
-adjustment mode is @samp{b} or@w{ }@samp{n}, don't hyphenate the line if
-it can be justified by adding no more than @var{hyphenation_space} extra
-space to each word space.  Without argument, the hyphenation space is
-set to its default value, which is@w{ }0.  The default scaling indicator
-for this request is@w{ }@code{m}.  The hyphenation space is associated
-with the current environment (@pxref{Environments}).
+adjustment mode is @samp{b} or@w{ }@samp{n}, don't hyphenate the line
+if it can be justified by adding no more than @var{hyphenation_space}
+extra space to each word space.  Without argument, the hyphenation
+space is set to its default value, which is@w{ }0.  The default
+scaling indicator for this request is@w{ }@code{m}.  The hyphenation
+space is associated with the current environment
+(@pxref{Environments}).
 
 A negative argument resets the hyphenation space to zero, emitting a
 warning of type @samp{range}.
@@ -4532,9 +4549,9 @@ number register.
 Set the soft hyphen character to @var{char}.  If the argument is
 omitted, the soft hyphen character is set to the default character
 @code{\(hy} (this is the start-up value of @code{gtroff} also).  The
-soft hyphen character is the character that is inserted when a
-word is hyphenated at a line break.  If the soft hyphen character does
-not exist in the font of the character immediately preceding a potential
+soft hyphen character is the character that is inserted when a word is
+hyphenated at a line break.  If the soft hyphen character does not
+exist in the font of the character immediately preceding a potential
 break point, then the line is not broken at that point.  Neither
 definitions (specified with the @code{char} request) nor translations
 (specified with the @code{tr} request) are considered when finding the
@@ -4586,9 +4603,9 @@ request causes a line break.  The default scaling indicator is@w{
 @cindex double-spacing
 @Defreq {ls, [@Var{nnn}]}
 @Defregx {.L}
-Output @w{@var{nnn}@minus{}1} blank lines after each line of text.  With
-no argument, @code{gtroff} uses the previous value before the last
-@code{ls} call.
+Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
+With no argument, @code{gtroff} uses the previous value before the
+last @code{ls} call.
 
 @Example
 .ls 2    \" This causes double-spaced output
@@ -4609,14 +4626,14 @@ spacing setting.
 
 @Defesc {\\x, ', spacing, '}
 @Defregx {.a}
-Sometimes, extra vertical spacing is only needed occasionally, e.g.@: to
-allow space for a tall construct (like an equation).  The @code{\x}
+Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
+to allow space for a tall construct (like an equation).  The @code{\x}
 escape does this.  The escape is given a numerical argument, usually
 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
 is@w{ }@code{v}.  If this number is positive extra vertical space is
-inserted below the current line.  A negative number adds space
-above.  If this escape is used multiple times on the same line, the
-maximum of the values is used.
+inserted below the current line.  A negative number adds space above.
+If this escape is used multiple times on the same line, the maximum of
+the values is used.
 
 @xref{Escapes}, for details on parameter delimiting characters.
 
@@ -4638,11 +4655,12 @@ The @code{.a} read-only number register contains the most recent
 @cindex blank lines, disabling
 @cindex lines, blank, disabling
 @Defreq {ns, }
-Enable @dfn{no-space mode}.  In this mode, spacing (either via @code{sp}
-or via blank lines) is disabled.  The @code{bp} request to advance to
-the next page is also disabled, except if it is accompanied by a page
-number (see @ref{Page Control}, for more information).  This mode
-ends when actual text is output or the @code{rs} request is encountered.
+Enable @dfn{no-space mode}.  In this mode, spacing (either via
+@code{sp} or via blank lines) is disabled.  The @code{bp} request to
+advance to the next page is also disabled, except if it is accompanied
+by a page number (see @ref{Page Control}, for more information).  This
+mode ends when actual text is output or the @code{rs} request is
+encountered.
 
 @cindex top-level diversion
 @cindex diversion, top-level
@@ -4686,8 +4704,8 @@ This escape is a non-interpreted tab character.  In copy mode
 @Defregx {.tabs}
 Change tab stop positions.  This request takes a series of tab
 specifiers as arguments (optionally divided into two groups with the
-letter @samp{T}) which indicate where each tab stop is to be (overriding
-any previous settings).
+letter @samp{T}) which indicate where each tab stop is to be
+(overriding any previous settings).
 
 Tab stops can be specified absolutely, i.e., as the distance from the
 left margin.  For example, the following sets 6@w{ }tab stops every
@@ -4834,14 +4852,14 @@ argument to the @code{ta} request.
 @Defreq {tc, [@Var{fill-char}]}
 Normally @code{gtroff} fills the space to the next tab stop with
 whitespace.  This can be changed with the @code{tc} request.  With no
-argument @code{gtroff} reverts to using whitespace, which is the default.
-The value of this @dfn{tab repetition} character is associated with the
-current environment (@pxref{Environments}).
+argument @code{gtroff} reverts to using whitespace, which is the
+default.  The value of this @dfn{tab repetition} character is
+associated with the current environment (@pxref{Environments}).
 @endDefreq
 
 @menu
-* Leaders::                     
-* Fields::                      
+* Leaders::
+* Fields::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -4871,11 +4889,11 @@ character.
 @cindex leader repetition character
 @cindex character, leader repetition
 @Defreq {lc, [@Var{fill-char}]}
-Declares the leader character.
-Without an argument, leaders act the same as tabs (i.e.,
-using whitespace for filling).  @code{gtroff}'s start-up value is @samp{.}.
-The value of this @dfn{leader repetition} character is associated with
-the current environment (@pxref{Environments}).
+Declare the leader character.  Without an argument, leaders act the
+same as tabs (i.e., using whitespace for filling).  @code{gtroff}'s
+start-up value is @samp{.}.  The value of this @dfn{leader repetition}
+character is associated with the current environment
+(@pxref{Environments}).
 @endDefreq
 
 @cindex table of contents
@@ -4984,8 +5002,9 @@ no-break control character is associated with the current environment
 
 @esindex \\
 @Defreq {eo, }
-Disable the escape mechanism completely.  After executing this request,
-the backslash character @samp{\} no longer starts an escape sequence.
+Disable the escape mechanism completely.  After executing this
+request, the backslash character @samp{\} no longer starts an escape
+sequence.
 
 This request can be very helpful in writing macros since it is not
 necessary then to double the escape character.  Here an example:
@@ -5012,14 +5031,14 @@ necessary then to double the escape character.  Here an example:
 @cindex character, escape
 @Defreq {ec, [@Var{c}]}
 Set the escape character to @var{c}.  With no argument the default
-escape character @samp{\} is restored.  It can be also used to re-enable
-the escape mechanism after an @code{eo} request.
-
-Note that changing the escape character globally will likely break macro
-packages since @code{gtroff} has no mechanism (like @TeX{}) to `intern'
-macros, i.e., to convert a macro definition into an internal form which
-is independent of its representation.  If a macro is called, it is
-executed literally.
+escape character @samp{\} is restored.  It can be also used to
+re-enable the escape mechanism after an @code{eo} request.
+
+Note that changing the escape character globally will likely break
+macro packages since @code{gtroff} has no mechanism (like @TeX{}) to
+`intern' macros, i.e., to convert a macro definition into an internal
+form which is independent of its representation.  If a macro is
+called, it is executed literally.
 @endDefreq
 
 @Defesc {\\e, , , }
@@ -5139,8 +5158,9 @@ Without an argument, the @code{tr} request is ignored.
 @cindex @code{\!}, and @code{trnt}
 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
 @code{trnt} is the same as the @code{tr} request except that the
-translations do not apply to text that is transparently throughput into
-a diversion with @code{\!}.  @xref{Diversions}, for more information.
+translations do not apply to text that is transparently throughput
+into a diversion with @code{\!}.  @xref{Diversions}, for more
+information.
 
 For example,
 
@@ -5153,8 +5173,8 @@ For example,
 @endExample
 
 @noindent
-prints @samp{b}; if @code{trnt} is used instead of @code{tr} it
-prints @samp{a}.
+prints @samp{b} to the standard error stream; if @code{trnt} is used
+instead of @code{tr} it prints @samp{a}.
 @endDefreq
 
 
@@ -5354,8 +5374,8 @@ increment or decrement value is specified, adjust the temporary
 indentation relative to the value set by the @code{in} request.
 
 This request causes a break; its value is associated with the current
-environment.  The default scaling indicator is@w{ }@code{m}.  A call of
-@code{ti} without an argument is ignored.
+environment.  The default scaling indicator is@w{ }@code{m}.  A call
+of @code{ti} without an argument is ignored.
 
 If the total indentation value is negative (which is not allowed),
 @code{gtroff} emits a warning of type @samp{range} and sets the
@@ -5382,8 +5402,8 @@ indentation value or a temporary indentation value is active.
 Set the line length to @var{length} (or increment or decrement the
 current value by @var{length}).  Initially, the line length is set to
 6.5@dmn{i}.  The effect of @code{ll} is delayed until a partially
-collected line (if it exists) is output.  The default scaling indicator
-is@w{ }@code{m}.
+collected line (if it exists) is output.  The default scaling
+indicator is@w{ }@code{m}.
 
 If @code{ll} is called without an argument, the line length is reset to
 the previous value before the last call to @code{ll}.  If a negative
@@ -5419,9 +5439,9 @@ page layout.
 @Defreqx {pl, @t{+}@Var{length}}
 @Defreqx {pl, @t{-}@Var{length}}
 @Defregx {.p}
-Set the @dfn{page length} to @var{length} (or increment or decrement the
-current value by @var{length}).  This is the length of the physical
-output page.  The default scaling indicator is@w{ }@code{v}.
+Set the @dfn{page length} to @var{length} (or increment or decrement
+the current value by @var{length}).  This is the length of the
+physical output page.  The default scaling indicator is@w{ }@code{v}.
 
 @cindex current page length register
 The current setting can be found in the read-only number register
@@ -5453,12 +5473,12 @@ and bottom titles (or headers and footers).
 @cindex three-part title
 @cindex page number character
 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
-The @code{tl} request prints a @dfn{title line}, which consists of three
-parts: a left justified portion, a centered portion, and a right
-justified portion.  The argument separator @samp{'} can be replaced with
-any character not occurring in the title line.  The @samp{%} character
-is replaced with the current page number.  This character can be changed
-with the @code{pc} request (see below).
+Print a @dfn{title line}.  It consists of three parts: a left
+justified portion, a centered portion, and a right justified portion.
+The argument separator @samp{'} can be replaced with any character not
+occurring in the title line.  The @samp{%} character is replaced with
+the current page number.  This character can be changed with the
+@code{pc} request (see below).
 
 Without argument, @code{tl} is ignored.
 
@@ -5495,14 +5515,14 @@ changing the font or font size) are undone after processing @code{tl}.
 @Defreqx {lt, @t{+}@Var{length}}
 @Defreqx {lt, @t{-}@Var{length}}
 @Defregx {.lt}
-The title line is printed using its own line length, which is specified
-(or incremented or decremented) with the @code{lt} request.  Initially,
-the title line length is set to 6.5@dmn{i}.  If a negative line length
-is specified (which is not allowed), @code{gtroff} emits a warning of
-type @samp{range} and sets the title line length to zero.  The default
-scaling indicator is@w{ }@code{m}.  If @code{lt} is called without an
-argument, the title length is reset to the previous value before the
-last call to @code{lt}.
+The title line is printed using its own line length, which is
+specified (or incremented or decremented) with the @code{lt} request.
+Initially, the title line length is set to 6.5@dmn{i}.  If a negative
+line length is specified (which is not allowed), @code{gtroff} emits a
+warning of type @samp{range} and sets the title line length to zero.
+The default scaling indicator is@w{ }@code{m}.  If @code{lt} is called
+without an argument, the title length is reset to the previous value
+before the last call to @code{lt}.
 
 The current setting of this is available in the @code{.lt} read-only
 number register; it is associated with the current environment
@@ -5516,9 +5536,9 @@ number register; it is associated with the current environment
 @Defreqx {pn, @t{+}@Var{page}}
 @Defreqx {pn, @t{-}@Var{page}}
 @Defregx {.pn}
-The @code{pn} request changes (increases or decreases) the page number
-of the @emph{next} page.  The only argument is the page number; the
-request is ignored without a parameter.
+Change (increase or decrease) the page number of the @emph{next} page.
+The only argument is the page number; the request is ignored without a
+parameter.
 
 The read-only number register @code{.pn} contains the number of the next
 page: either the value set by a @code{pn} request, or the number of the
@@ -5534,10 +5554,9 @@ A read-write register holding the current page number.
 @cindex page number character, changing
 @vindex %
 @Defreq {pc, [@Var{char}]}
-The @code{pc} request changes the page number character (used by the
-@code{tl} request) to a different character.  With no argument, this
-mechanism is disabled.  Note that this doesn't affect the number
-register @code{%}.
+Change the page number character (used by the @code{tl} request) to a
+different character.  With no argument, this mechanism is disabled.
+Note that this doesn't affect the number register @code{%}.
 @endDefreq
 
 @xref{Traps}.
@@ -5555,11 +5574,11 @@ register @code{%}.
 @Defreq {bp, [@Var{page}]}
 @Defreqx {bp, @t{+}@Var{page}}
 @Defreqx {bp, @t{-}@Var{page}}
-To stop processing the current page, and move to the next page, invoke
-@code{bp}.  This request causes a break.  It can also take an argument
-to set (increase, decrease) the page number of the next page.  The
-only difference between @code{bp} and @code{pn} is that @code{pn} does
-not cause a break or actually eject a page.
+Stop processing the current page and move to the next page.  This
+request causes a break.  It can also take an argument to set
+(increase, decrease) the page number of the next page.  The only
+difference between @code{bp} and @code{pn} is that @code{pn} does not
+cause a break or actually eject a page.
 
 @Example
 .de newpage                         \" define macro
@@ -5581,10 +5600,11 @@ not cause a break or actually eject a page.
 It is often necessary to force a certain amount of space before a new
 page occurs.  This is most useful to make sure that there is not a
 single @dfn{orphan} line left at the bottom of a page.  The @code{ne}
-request ensures that there is a certain distance, specified by the first
-argument, before the next page is triggered (see @ref{Traps}, for
-further information).  The default unit for @code{ne} is @samp{v}; the
-default value of @var{space} is@w{ }1@dmn{v} if no argument is given.
+request ensures that there is a certain distance, specified by the
+first argument, before the next page is triggered (see @ref{Traps},
+for further information).  The default unit for @code{ne} is @samp{v};
+the default value of @var{space} is@w{ }1@dmn{v} if no argument is
+given.
 
 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
 do the following before each paragraph:
@@ -5598,13 +5618,13 @@ text text text
 @rqindex os
 @rqindex ne
 @Defreq {sv, [@Var{space}]}
-@code{sv} is similar to the @code{ne} request; it reserves the specified
-amount of vertical space.  If the desired amount of space exists before
-the next trap (bottom page boundary), the space is output immediately
-(ignoring a partial filled line which stays untouched).  If there is not
-enough space, it is stored for later output via the @code{os} request.
-The default value is@w{ }1@dmn{v} if no argument is given; the default
-unit is @samp{v}.
+@code{sv} is similar to the @code{ne} request; it reserves the
+specified amount of vertical space.  If the desired amount of space
+exists before the next trap (bottom page boundary), the space is
+output immediately (ignoring a partial filled line which stays
+untouched).  If there is not enough space, it is stored for later
+output via the @code{os} request.  The default value is@w{ }1@dmn{v}
+if no argument is given; the default unit is @samp{v}.
 @endDefreq
 
 
@@ -5622,13 +5642,13 @@ devices, there is also at least one symbol font which contains various
 special symbols (Greek, mathematics).
 
 @menu
-* Changing Fonts::              
-* Font Families::               
-* Font Positions::              
-* Using Symbols::               
-* Special Fonts::               
-* Artificial Fonts::            
-* Ligatures and Kerning::       
+* Changing Fonts::
+* Font Families::
+* Font Positions::
+* Using Symbols::
+* Special Fonts::
+* Artificial Fonts::
+* Ligatures and Kerning::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -5648,12 +5668,13 @@ special symbols (Greek, mathematics).
 @Defescx {\\f, @lparen{}, fn, }
 @Defescx {\\f, @lbrack{}, font, @rbrack}
 The @code{ft} request and the @code{\f} escape change the current font
-to @var{font} (one-character name @var{f}, two-character name @var{fn}).
+to @var{font} (one-character name @var{f}, two-character name
+@var{fn}).
 
 If @var{font} is a style name (as set with the @code{sty} request or
 with the @code{styles} command in the @file{DESC} file), use it within
-the current font family (as set with the @code{fam} request or with the
-@code{family} command in the @file{DESC} file).
+the current font family (as set with the @code{fam} request or with
+the @code{family} command in the @file{DESC} file).
 
 @cindex previous font
 @cindex font, previous
@@ -5691,12 +5712,12 @@ eggs, bacon, \fBspam\fP and sausage.
 @rqindex fp
 @rqindex code
 @Defreq {ftr, f [@Var{g}]}
-This request translates font@w{ }@var{f} to font@w{ }@var{g}.  Whenever
-a font named @var{f} is referred to in a @code{\f} escape sequence, or
-in the @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
+Translate font@w{ }@var{f} to font@w{ }@var{g}.  Whenever a font named
+@var{f} is referred to in a @code{\f} escape sequence, or in the
+@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
 @code{special}, @code{fspecial}, @code{fp}, or @code{code} requests,
-font@w{ }@var{g} is used.  If @var{g} is missing or equal to @var{f} the
-translation is undone.
+font@w{ }@var{g} is used.  If @var{g} is missing or equal to @var{f}
+the translation is undone.
 @endDefreq
 
 @c ---------------------------------------------------------------------
@@ -5752,17 +5773,18 @@ and spam.
 @rqindex fspecial
 @Defreq {sty, n style}
 Associate @var{style} with font position@w{ }@var{n}.  A font position
-can be associated either with a font or with a style.  The current font
-is the index of a font position and so is also either a font or a style.
-When it is a style, the font that is actually used is the font the name
-of which is the concatenation of the name of the current family and the
-name of the current style.  For example, if the current font is@w{ }1
-and font position@w{ }1 is associated with style@w{ }@samp{R} and the
-current font family is@w{ }@samp{T}, then font @samp{TR} will be used.
-If the current font is not a style, then the current family is ignored.
-When the requests @code{cs}, @code{bd}, @code{tkf}, @code{uf}, or
-@code{fspecial} are applied to a style, then they will instead be
-applied to the member of the current family corresponding to that style.
+can be associated either with a font or with a style.  The current
+font is the index of a font position and so is also either a font or a
+style.  When it is a style, the font that is actually used is the font
+the name of which is the concatenation of the name of the current
+family and the name of the current style.  For example, if the current
+font is@w{ }1 and font position@w{ }1 is associated with style@w{
+}@samp{R} and the current font family is@w{ }@samp{T}, then font
+@samp{TR} will be used.  If the current font is not a style, then the
+current family is ignored.  When the requests @code{cs}, @code{bd},
+@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, then
+they will instead be applied to the member of the current family
+corresponding to that style.
 
 @var{n} must be a non-negative integer value.
 
@@ -5962,8 +5984,8 @@ special fonts locally (i.e.@: for a particular font), use the
 @Defesc {\\, @lparen{}, nm, }
 @Defescx {\\, @lbrack{}, name, @rbrack}
 Insert a symbol @var{name} (two-character name @var{nm}).  There is no
-special syntax for one-character names -- the natural form @samp{\@var{n}}
-would collide with escapes.
+special syntax for one-character names -- the natural form
+@samp{\@var{n}} would collide with escapes.
 
 If @var{name} is undefined, a warning of type @samp{char} is generated,
 and the escape is ignored.  @xref{Debugging}, for information about
@@ -5985,7 +6007,7 @@ compatibility mode.
 @rqindex char
 @cindex unicode
 @Defesc {\\N, ', n, '}
-Typesets the character with code@w{ }@var{n} in the current font (this
+Typeset the character with code@w{ }@var{n} in the current font (this
 is @strong{not} the input character code).  @var{n} can be any
 integer.  Most devices only have characters with codes between 0
 and@w{ }255; the Unicode output device uses codes in the range
@@ -6184,10 +6206,9 @@ well (if a tty output device is used).
 @rqindex ul
 @rqindex cu
 @Defreq {uf, font}
-The @code{uf} request globally sets the underline font used by
-@code{ul} and @code{cu}.  By default, this is the font at position@w{
-}2.  @var{font} can be either a non-negative font position or the name
-of a font.
+Set the underline font (globally) used by @code{ul} and @code{cu}.  By
+default, this is the font at position@w{ }2.  @var{font} can be either
+a non-negative font position or the name of a font.
 @endDefreq
 
 @cindex imitating bold face
@@ -6195,8 +6216,8 @@ of a font.
 @Defreq {bd, font [@Var{offset}]}
 @Defreqx {bd, font1 font2 [@Var{offset}]}
 @Defregx {.b}
-The @code{bd} request artificially creates a bold font by printing
-each character twice, slightly offset.
+Artificially create a bold font by printing each character twice,
+slightly offset.
 
 Two syntax forms are available.
 
@@ -6386,8 +6407,8 @@ q\,\f[I]f
 @endDefesc
 
 @Defesc {\\&, , , }
-This inserts a zero-width character, which is invisible.  Its intended
-use is to stop interaction of a character with its surrounding.
+Insert a zero-width character, which is invisible.  Its intended use
+is to stop interaction of a character with its surrounding.
 
 @itemize @bullet
 @item
@@ -6467,8 +6488,8 @@ The difference between type size and vertical spacing is known, by
 typesetters, as @dfn{leading}.
 
 @menu
-* Changing Type Sizes::         
-* Fractional Type Sizes::       
+* Changing Type Sizes::
+* Fractional Type Sizes::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -6553,7 +6574,7 @@ If @code{vs} is called without an argument, the vertical spacing is
 reset to the previous value before the last call to @code{vs}.
 
 @vindex .V
-@code{gtroff} creates a warning of type @code{range} if @var{space} is
+@code{gtroff} creates a warning of type @samp{range} if @var{space} is
 zero or negative; the vertical spacing is then set to the vertical
 resolution (as given in the @code{.V} register).
 
@@ -6690,7 +6711,8 @@ even this is a read-write string variable).
 @Defescx {\\*, @lparen{}, nm, }
 @Defescx {\\*, @lbrack{}, name, @rbrack{}}
 Define and access a string variable @var{name} (one-character name
-@var{n}, two-character name @var{nm}).
+@var{n}, two-character name @var{nm}).  If @var{name} already exists,
+@code{ds} overwrites the previous definition.
 
 Example:
 
@@ -6842,82 +6864,86 @@ This is \*[xxx].
     @result{} This is a funny test.
 @endExample
 
-@xref{Groff Internals}, for more informations.
+@xref{Gtroff Internals}, for more information.
 @endDefreq
 
 @cindex appending to strings
 @cindex strings, appending
-@Defreq {as, name string}
-The @code{as} request appends a string to another string.  It is
-similar to the @code{ds} request except that it appends the second
-argument onto the string named by the first argument.
+@Defreq {as, name [@Var{string}]}
+The @code{as} request is similar to @code{ds} but appends @var{string}
+to the string stored as @var{name} instead of redefining it.  If
+@var{name} doesn't exist yet, it is created.
 
 @Example
 .as sign " with shallots, onions and garlic,
 @endExample
 @endDefreq
 
-@cindex substrings
-@Defreq {substring, xx n1 [@Var{n2}]}
-@Defreqx {length, xx string}
-Rudimentary string manipulation routines are given with the
-@code{substring} and @code{length} requests.
-
-The @code{substring} request replaces the string in register@w{
-}@var{xx} with the substring defined by the indices @var{n1} and@w{
-}@var{n2}.  The first character in the string has index one.  If
-@var{n2} is omitted, it is taken to be equal to the string's length.  If
-the index value @var{n1} or @var{n2} is negative or zero, it is counted
-from the end of the string, going backwards: The last character has
-index@w{ }0, the character before the last character has index@w{
-}@minus{}1, etc.
+Rudimentary string manipulation routines are given with the next two
+requests.
+
+@cindex substring
+@Defreq {substring, str n1 [@Var{n2}]}
+Replace the string in register@w{ }@var{str} with the substring
+defined by the indices @var{n1} and@w{ }@var{n2}.  The first character
+in the string has index one.  If @var{n2} is omitted, it is taken to
+be equal to the string's length.  If the index value @var{n1} or
+@var{n2} is negative or zero, it is counted from the end of the
+string, going backwards: The last character has index@w{ }0, the
+character before the last character has index@w{ }@minus{}1, etc.
+
+@Example
+.ds xxx abcdefgh
+.substring xxx 2 -3
+\*[xxx]
+    @result{} bcde
+@endExample
+@endDefreq
 
 @cindex length of a string
 @cindex string, length of
-Here the syntax of the @code{length} request:
+@Defreq {length, reg str}
+Compute the length of @var{str} and returns it in the number
+register@w{ }@var{reg}.  If @var{reg} doesn't exist, it is created.
 
-The @code{length} request
-computes the length of @var{string} and returns it in the number
-register@w{ }@var{xx} (which is not necessarily defined before).
+@Example
+.ds xxx abcdefgh
+.length yyy xxx
+\n[yyy]
+    @result{} 8
+@endExample
 @endDefreq
 
 @cindex rename request
 @cindex rename macro
 @cindex rename string
 @Defreq {rn, xx yy}
-Renames the request, macro, or string @var{xx} to @var{yy}.
+Rename the request, macro, or string @var{xx} to @var{yy}.
 @endDefreq
 
 @cindex remove request
 @cindex remove macro
 @cindex remove string
 @Defreq {rm, xx}
-Removes the request, macro, or string @var{xx}.
-@code{gtroff} treats subsequent invocations as if the
-object had never been defined.
+Remove the request, macro, or string @var{xx}.  @code{gtroff} treats
+subsequent invocations as if the object had never been defined.
 @endDefreq
 
 @cindex alias
 @Defreq {als, new old}
-Create an alias named @var{new} for the request, string,
-macro, or diversion object named @var{old}.  The new name and
-the old name are exactly equivalent (it is similar to a hard
-rather than a soft link). If @var{old} is undefined,
-@code{gtroff} generates a warning of type @b{mac} and ignores
-the request.
-
-The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds},
-and @code{as} requests only create a new object if the name
-of the macro, diversion or string diversion is currently
-undefined or if it is defined to be a request; normally
-they modify the value of an existing object.
+Create an alias named @var{new} for the request, string, macro, or
+diversion object named @var{old}.  The new name and the old name are
+exactly equivalent (it is similar to a hard rather than a soft
+link). If @var{old} is undefined, @code{gtroff} generates a warning of
+type @samp{mac} and ignores the request.
 @endDefreq
 
 @Defreq {chop, xx}
-Remove (chop) the last character from the macro, string,
-or diversion named @var{xx}. This is useful for removing
-the newline from the end of diversions that are to be
-interpolated as strings.
+Remove (chop) the last character from the macro, string, or diversion
+named @var{xx}. This is useful for removing the newline from the end
+of diversions that are to be interpolated as strings.  This command
+can be used repeatedly; see @ref{Gtroff Internals}, for details on
+nodes inserted by @code{gtroff} automatically.
 @endDefreq
 
 @xref{Identifiers}, and @ref{Comments}.
@@ -6930,12 +6956,23 @@ interpolated as strings.
 @cindex conditionals and loops
 @cindex loops and conditionals
 
+@menu
+* Operators in Conditionals::
+* if-else::
+* while::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
+@subsection Operators in Conditionals
+
 @rqindex if
 @rqindex while
 @cindex @code{if}, operators to use with it
 @cindex @code{while}, operators to use with it
-In @code{if} and @code{while} requests, there are several more operators
-available:
+In @code{if} and @code{while} requests, there are several more
+operators available:
 
 @table @code
 @item e
@@ -6952,52 +6989,82 @@ True if the document is being processed in nroff mode (i.e., the
 True if the document is being processed in troff mode (i.e., the
 @code{.troff} command has been issued).
 
-@item "@var{xxx}"@var{yyy}"
+@item v
+Always false.
+
+@item '@var{xxx}'@var{yyy}'
 True if the string @var{xxx} is equal to the string @var{yyy}.  Other
-characters can be used in place of the double quotes.
-@c XXX which characters?
-@code{gtroff} formats the strings before being compared; for example,
+characters can be used in place of the single quotes; the same set of
+delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
+@code{gtroff} formats the strings before being compared:
 
 @Example
 .ie "|"\fR|\fP" \
-.  tm true
+true
 .el \
-.  tm false
+false
+    @result{} true
 @endExample
 
 @noindent
-yields ``true''.  The resulting motions, character sizes, and fonts
-have to match, and not the individual motion, size, and font requests.
-Here, @samp{|} and @samp{\fR|\fP} both result in a roman @samp{|}
-character with the same point size and at the same location on the
-page, so the strings are equal.  If @samp{.ft@w{ }I} had been added
-before the @samp{.ie}, then the result would be ``false'' because
-@samp{|} produces an italic @samp{|} rather than a roman one.
-
-@item r@var{xxx}
+The resulting motions, character sizes, and fonts have to
+match,@footnote{The created output nodes must be identical.
+@xref{Gtroff Internals}.} and not the individual motion, size, and
+font requests.  In the previous example, @samp{|} and @samp{\fR|\fP}
+both result in a roman @samp{|} character with the same point size and
+at the same location on the page, so the strings are equal.  If
+@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result
+would be ``false'' because (the first) @samp{|} produces an italic
+@samp{|} rather than a roman one.
+
+@item r @var{xxx}
 True if there is a number register named @var{xxx}.
 
-@item d@var{xxx}
+@item d @var{xxx}
 True if there is a string, macro, diversion, or request named @var{xxx}.
 
-@item c@var{ch}
+@item c @var{ch}
 @rqindex char
 True if there is a character @var{ch} available; @var{ch} is either an
 @acronym{ASCII} character or a special character (@code{\(@var{ch}} or
-@code{\[@var{ch}]}); the condition is also true if @var{ch} has
-been defined by the @code{char} request.
+@code{\[@var{ch}]}); the condition is also true if @var{ch} has been
+defined by the @code{char} request.
 @end table
 
-@xref{Expressions}.
+Note that these operators can't be combined with other operators like
+@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
+between the exclamation mark and the operator) can be used to negate
+the result.
 
-@menu
-* if-else::                     
-* while::                       
-@end menu
+@Example
+.nr xxx 1
+.ie !r xxx \
+true
+.el \
+false
+    @result{} false
+@endExample
+
+A whitespace after @samp{!} always evaluates to zero (this bizarre
+behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
+
+@Example
+.nr xxx 1
+.ie ! r xxx \
+true
+.el \
+false
+    @result{} r xxx true
+@endExample
+
+It is possible to omit the whitespace before the argument to the
+@samp{r}, @samp{d}, and @samp{c} operators.
+
+@xref{Expressions}.
 
 @c ---------------------------------------------------------------------
 
-@node if-else, while, Conditionals and Loops, Conditionals and Loops
+@node if-else, while, Operators in Conditionals, Conditionals and Loops
 @subsection if-else
 @cindex if-else
 
@@ -7005,16 +7072,17 @@ been defined by the @code{char} request.
 the formatting can be painful.
 
 @Defreq {if, expr anything}
-Evaluates the expression @var{expr}, and executes @var{anything} (the
-remainder of the line) if @var{expr} evaluates to
-non-zero (true).  @var{anything} is interpreted as though it was on
-a line by itself.  @xref{Expressions}, for more info.
-
-Here are some examples:
+Evaluate the expression @var{expr}, and executes @var{anything} (the
+remainder of the line) if @var{expr} evaluates to non-zero (true).
+@var{anything} is interpreted as though it was on a line by itself
+(except that leading spaces are swallowed).  @xref{Expressions}, for
+more info.
 
 @Example
-.if t .ls 2				\" double spacing in troff
-.if 0 .ab how'd this happen?
+.nr xxx 1
+.nr yyy 2
+.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
+    @result{} true
 @endExample
 @endDefreq
 
@@ -7027,20 +7095,19 @@ The first request is the `if' part and the latter is the `else' part.
 
 @Example
 .ie n .ls 2 \" double spacing in nroff
-.el .ls 1 \" single spacing in troff
+.el   .ls 1 \" single spacing in troff
 @endExample
 @endDefreq
 
-@c this looks like a bug in makeinfo: you can't have `@{' as an argument
+@c this is a bug in makeinfo: you can't have `@{' as an argument
 @c to deffn
 
 @esindex \@{
 @esindex \@}
-@c @Defesc {\\@@@ {, , , }
+@c @Defesc {\\@@@{, , , }
 @c @Defescx {\\@@@}, , , }
-In many cases, an if (or if-else) construct needs to execute
-more than one request.
-This can be done using the @code{\@{} and @code{\@}}
+In many cases, an if (or if-else) construct needs to execute more than
+one request.  This can be done using the @code{\@{} and @code{\@}}
 escapes.  The following example shows the possible ways to use these
 escapes (note the position of the opening and closing braces).
 
@@ -7053,7 +7120,6 @@ escapes (note the position of the opening and closing braces).
 .\@{\
 .    ds lq "
 .    ds rq "\@}
-.ds qq "
 @endExample
 @c @endDefesc
 
@@ -7069,43 +7135,92 @@ escapes (note the position of the opening and closing braces).
 request, which is used much like the @code{if} (and related) requests.
 
 @Defreq {while, expr anything}
-Evaluates the expression @var{expr}, and repeatedly executes
-@var{anything} (the remainder of the line) until @var{expr}
-evaluates to 0 or false.
+Evaluate the expression @var{expr}, and repeatedly execute
+@var{anything} (the remainder of the line) until @var{expr} evaluates
+to@w{ }0.
 
 @Example
 .nr a 0 1
-.while (\na<9) \&\n+a,
-\&\n+a
+.while (\na < 9) \@{\
+\n+a,
+.\@}
+\n+a
+    @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
 @endExample
 
+Some remarks.
+
+@rqindex de
+@itemize @bullet
+@item
+The body of a @code{while} request is treated like the body of a
+@code{de} request: @code{gtroff} temporarily stores it in a macro
+which is deleted after the loop has been exited.  It can considerably
+slow down a macro if the body of the @code{while} request (within the
+macro) is large.  Each time the macro is executed, the @code{while}
+body is parsed and stored again as a temporary macro.
+
+@Example
+.de xxx
+.  nr num 10
+.  while (\\n[num] > 0) \@{\
+.    \" many lines of code
+.    nr num -1
+.  \@}
+..
+@endExample
+
+@cindex recursive macros
+@cindex macros, recursive
 @noindent
-The preceding example produces:
+The traditional and ofter better solution (@acronym{UNIX} @code{troff}
+doesn't have the @code{while} request) is to use a recursive macro
+instead which is parsed only once during its definition.
 
 @Example
-1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+.de yyy
+.  if (\\n[num] > 0) \@{\
+.    \" many lines of code
+.    nr num -1
+.    yyy
+.  \@}
+..
+.
+.de xxx
+.  nr num 10
+.  yyy
+..
 @endExample
 
-@cindex zero width space character
-@cindex character, zero width space
-@cindex space character, zero width
-@esindex \&
 @noindent
-Note the usage of the @code{\&} escape to avoid a control character at
-the beginning of a line.
+Note that the number of available recursion levels is set to@w{ }1000
+(this is a compile-time constant value of @code{gtroff}).
+
+@item
+The closing brace of a @code{while} body must end a line.
+
+@Example
+.if 1 \@{\
+.  nr a 0 1
+.  while (\n[a] < 10) \@{\
+.    nop \n+[a]
+.\@}\@}
+    @result{} unbalanced \@{ \@}
+@endExample
+@end itemize
 @endDefreq
 
 @rqindex while
 @cindex @code{break}, in a @code{while} loop
 @cindex @code{continue}, in a @code{while} loop
 @Defreq {break, }
-@dfn{break} out of a while loop.  Be sure
-not to confuse this with the @code{br} request (causing a line break).
+Break out of a @code{while} loop.  Be sure not to confuse this with
+the @code{br} request (causing a line break).
 @endDefreq
 
 @Defreq {continue, }
-Finishes the current iteration of a while
-loop, immediately restarting the next iteration.
+Finishes the current iteration of a @code{while} loop, immediately
+restarting the next iteration.
 @endDefreq
 
 @xref{Expressions}.
@@ -7118,45 +7233,51 @@ loop, immediately restarting the next iteration.
 @cindex writing macros
 @cindex macros, writing
 
-A @dfn{macro} is a collection of text and embedded commands which can be
-invoked multiple times.  Use macros to define common operations.
+A @dfn{macro} is a collection of text and embedded commands which can
+be invoked multiple times.  Use macros to define common operations.
 
 @Defreq {de, name [@Var{end}]}
-Defines a new macro named @var{name}.  @code{gtroff} copies
-subsequent lines into an internal buffer until it encounters
-the line @code{..} (two dots).  The
-optional second argument to @code{de} changes this ending token.
+Define a new macro named @var{name}.  @code{gtroff} copies subsequent
+lines (starting with the next one) into an internal buffer until it
+encounters the line @samp{..} (two dots).  The optional second
+argument to @code{de} changes this to a macro to @samp{.@var{end}}.
+
+Note that no leading whitespace is allowed in the line containing the
+ending token (either @samp{..} or the macro @samp{.@var{end}}).
 
 Here a small example macro called @samp{P} which causes a break and
-inserts some vertical space.  It could be used to separate
-paragraphs.
+inserts some vertical space.  It could be used to separate paragraphs.
 
 @Example
 .de P
-.br
-.sp .8v
+.  br
+.  sp .8v
 ..
 @endExample
 
+@c XXX add info about macro definitions in macros.
+
+@c XXX give example for end macro.
+
 @c XXX add info about indirect macro calls:
 @c
 @c .de xxx
-@c from xxx\c
+@c from yyy\c
 @c ..
 @c
 @c test \*[xxx] test
-@c   => test from xxx test
+@c   => test from yyy test
 
-@c XXX info about common identifier pool for strings and macros.
+@c XXX info about common identifier pool for strings, macros, and
+@c     diversions.
 @endDefreq
 
 @cindex appending, to a macro
 @Defreq {am, xx}
-Works similarly to @code{de} except it appends
-onto the macro named @var{xx}.  So, to make the previously
-defined @samp{P} macro actually do indented instead of block paragraphs,
-add the necessary code to the existing macro like
-this:
+Works similarly to @code{de} except it appends onto the macro named
+@var{xx}.  So, to make the previously defined @samp{P} macro actually
+do indented instead of block paragraphs, add the necessary code to the
+existing macro like this:
 
 @Example
 .am P
@@ -7167,12 +7288,11 @@ this:
 
 @cindex alias
 @Defreq {als, new old}
-Create an alias named @var{new} for the request, string,
-macro, or diversion object named @var{old}.  The new name and
-the old name are exactly equivalent (it is similar to a hard
-rather than a soft link). If @var{old} is undefined,
-@code{gtroff} generates a warning of type @b{mac} and ignores
-the request.
+Create an alias named @var{new} for the request, string, macro, or
+diversion object named @var{old}.  The new name and the old name are
+exactly equivalent (it is similar to a hard rather than a soft
+link). If @var{old} is undefined, @code{gtroff} generates a warning of
+type @samp{mac} and ignores the request.
 
 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds},
 and @code{as} requests only create a new object if the name
@@ -7182,8 +7302,8 @@ they modify the value of an existing object.
 @endDefreq
 
 @menu
-* Copy-in Mode::                
-* Parameters::                  
+* Copy-in Mode::
+* Parameters::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -7289,7 +7409,7 @@ The @code{als} request can make a macro have more than one name.
 This would be called as
 
 @Example
-.vl $Id: groff.texinfo,v 1.73 2001/04/15 04:28:06 wlemb Exp $
+.vl $Id: groff.texinfo,v 1.74 2001/04/16 14:47:18 wlemb Exp $
 @endExample
 @endDefesc
 
@@ -7699,10 +7819,10 @@ given location in the current diversion, after a certain number of input
 lines or at the end of input.
 
 @menu
-* Page Location Traps::         
-* Diversion Traps::             
-* Input Line Traps::            
-* End-of-input Traps::          
+* Page Location Traps::
+* Diversion Traps::
+* Input Line Traps::
+* End-of-input Traps::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -8410,7 +8530,7 @@ that do not know about this extension.
 
 @c =====================================================================
 
-@node Miscellaneous, Groff Internals, Postprocessor Access, gtroff Reference
+@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
 @section Miscellaneous
 @cindex miscellaneous
 
@@ -8496,8 +8616,8 @@ intelligible to the user.
 
 @c =====================================================================
 
-@node Groff Internals, Debugging, Miscellaneous, gtroff Reference
-@section Groff Internals
+@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
+@section @code{gtroff} Internals
 
 @cindex input token
 @cindex token, input
@@ -8532,7 +8652,7 @@ c
 .di
 @endExample
 
-@noindent  
+@noindent
 It contains these elements.
 
 @multitable {@i{vertical size node}} {token list} {element number}
@@ -8567,7 +8687,7 @@ empty); diversions and strings can contain elements in both lists.
 
 @c =====================================================================
 
-@node Debugging, Implementation Differences, Groff Internals, gtroff Reference
+@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
 @section Debugging
 @cindex debugging
 
@@ -8673,12 +8793,12 @@ The read-only number register @code{.warn} contains the current warning
 level.
 @endDefreq
 
-@c ---------------------------------------------------------------------
-
 @menu
-* Warnings::                    
+* Warnings::
 @end menu
 
+@c ---------------------------------------------------------------------
+
 @node Warnings,  , Debugging, Debugging
 @subsection Warnings
 @cindex warnings
@@ -8969,13 +9089,13 @@ This chapter describes all preprocessors that come with @code{groff} or
 which are freely available.
 
 @menu
-* geqn::                        
-* gtbl::                        
-* gpic::                        
-* ggrn::                        
-* grap::                        
-* grefer::                      
-* gsoelim::                     
+* geqn::
+* gtbl::
+* gpic::
+* ggrn::
+* grap::
+* grefer::
+* gsoelim::
 @end menu
 
 
@@ -8989,7 +9109,7 @@ which are freely available.
 @c XXX
 
 @menu
-* Invoking geqn::               
+* Invoking geqn::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9012,7 +9132,7 @@ which are freely available.
 @c XXX
 
 @menu
-* Invoking gtbl::               
+* Invoking gtbl::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9035,7 +9155,7 @@ which are freely available.
 @c XXX
 
 @menu
-* Invoking gpic::               
+* Invoking gpic::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9058,7 +9178,7 @@ which are freely available.
 @c XXX
 
 @menu
-* Invoking ggrn::               
+* Invoking ggrn::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9095,7 +9215,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking grefer::             
+* Invoking grefer::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9118,7 +9238,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking gsoelim::            
+* Invoking gsoelim::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9143,14 +9263,14 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Special Characters::          
-* grotty::                      
-* grops::                       
-* grodvi::                      
-* grolj4::                      
-* grolbp::                      
-* grohtml::                     
-* gxditview::                   
+* Special Characters::
+* grotty::
+* grops::
+* grodvi::
+* grolj4::
+* grolbp::
+* grohtml::
+* gxditview::
 @end menu
 
 
@@ -9175,7 +9295,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking grotty::             
+* Invoking grotty::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9197,8 +9317,8 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking grops::              
-* Embedding PostScript::        
+* Invoking grops::
+* Embedding PostScript::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9229,7 +9349,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking grodvi::             
+* Invoking grodvi::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9251,7 +9371,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking grolj4::             
+* Invoking grolj4::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9273,7 +9393,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking grolbp::             
+* Invoking grolbp::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9295,7 +9415,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking grohtml::            
+* Invoking grohtml::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9317,7 +9437,7 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* Invoking gxditview::          
+* Invoking gxditview::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9343,8 +9463,8 @@ is available as an extra package from the following address:
 @c XXX
 
 @menu
-* gtroff Output::               
-* Font Files::                  
+* gtroff Output::
+* Font Files::
 @end menu
 
 
@@ -9361,10 +9481,10 @@ not identical -- to that used by
 @acronym{UNIX} device-independent @code{troff} (@code{ditroff}).
 
 @menu
-* Output Format::               
-* Device Control::              
-* Drawing Functions::           
-* Line Continuation::           
+* Output Format::
+* Device Control::
+* Drawing Functions::
+* Line Continuation::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -9644,8 +9764,8 @@ file called @file{DESC} and for each font@w{ }@var{f} a font file
 called@w{ }@file{@var{f}}.
 
 @menu
-* DESC File Format::            
-* Font File Format::            
+* DESC File Format::
+* Font File Format::
 @end menu
 
 @c ---------------------------------------------------------------------