* doc/groff.texinfo: Completed pass on gtroff reference.

2 files changed, 154 insertions, 50 deletions

diff --git a/ChangeLog b/ChangeLog
index 7b8d82d7..22fb8aca 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2002-04-12  Werner LEMBERG  <wl@gnu.org>
+
+	* doc/groff.texinfo: Completed pass on gtroff reference.
+
 2002-04-11  Werner LEMBERG  <wl@gnu.org>
 
 	* doc/groff.texinfo: More fixes.
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index c2f58ca9..05d5727e 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -8095,11 +8095,54 @@ only when font@w{ }@var{f} font is active.
 @cindex artificial fonts
 @cindex fonts, artificial
 
-There are a number of requests for artificially creating fonts.  These
-are largely vestiges of the days when output devices did not have a
-wide variety of fonts, and when @code{nroff} and @code{troff} were
-separate programs.  These are no longer necessary in GNU
-@code{troff}.  Nevertheless, they are supported.
+There are a number of requests and escapes for artificially creating
+fonts.  These are largely vestiges of the days when output devices
+did not have a wide variety of fonts, and when @code{nroff} and
+@code{troff} were separate programs.  Most of them are no longer
+necessary in GNU @code{troff}.  Nevertheless, they are supported.
+
+@cindex changing the font height (@code{\H})
+@cindex font height, changing (@code{\H})
+@cindex height, font, changing (@code{\H})
+@DefescList {\\H, ', height, '}
+@DefescItem {\\H, ', @t{+}@Var{height}, '}
+@DefescListEnd {\\H, ', @t{-}@Var{height}, '}
+Change (increment, decrement) the height of the current font, but not
+the width.  If @var{height} is zero, restore the original height.
+Default unit is @samp{z}.
+
+Currently, only the @option{-Tps} device supports this feature.
+
+Note that @code{\H} doesn't produce an inpt token in @code{gtroff}.
+As a consequence, it can be used in requests like @code{mc} (which
+expects a single character as an argument) to change the font on
+the fly:
+
+@Example
+.mc \H'+5z'x\H'0'
+@endExample
+@endDefesc
+
+@cindex changing the font slant (@code{\S})
+@cindex font slant, changing (@code{\S})
+@cindex slant, font, changing (@code{\S})
+@DefescList {\\S, ', slant, '}
+@DefescItem {\\S, ', @t{+}@Var{slant}, '}
+@DefescListEnd {\\S, ', @t{-}@Var{slant}, '}
+Change (increment, decrement) the slant of the current font by @var{slant}
+degrees.  Positive values slant to the right.
+
+Currently, only the @option{-Tps} device supports this feature.
+
+Note that @code{\S} doesn't produce an inpt token in @code{gtroff}.
+As a consequence, it can be used in requests like @code{mc} (which
+expects a single character as an argument) to change the font on
+the fly:
+
+@Example
+.mc \S'20'x\S'0'
+@endExample
+@endDefesc
 
 @cindex underlining (@code{ul})
 @Defreq {ul, [@Var{lines}]}
@@ -10756,7 +10799,7 @@ to @code{\O}.
 @item \O3
 Begin a nesting level.  This is really an internal mechanism for
 @code{grohtml} while producing images.  They are generated by running
-the troff source through troff to the postscript device and ghostscript
+the troff source through troff to the PostScript device and GhostScript
 to produce images in PNG format.  The @code{\O3} escape will start a new
 page if the device is not html (to reduce the possibility of images
 crossing a page boundary).
@@ -11253,18 +11296,27 @@ And here the result:
 @c XXX xref ln register
 
 @Defreq {nn, [@Var{skip}]}
-Temporarily turns off line numbering.  The argument is the number
+Temporarily turn off line numbering.  The argument is the number
 of lines not to be numbered; this defaults to@w{ }1.
 @endDefreq
 
-@cindex margin characters (@code{mc})
-@cindex characters for margins (@code{mc})
-@Defreq {mc, char dist}
-Prints margin characters to the right of the text.
+@cindex margin character (@code{mc})
+@cindex character, for margins (@code{mc})
+@Defreq {mc, char [@Var{dist}]}
+Print margin character to the right of the text.
 The first argument is the character to be
-printed, and the second argument is the distance away from the main body
-text.  With no arguments the margin characters are turned off.  If this
-occurs before a break, no margin character is printed.
+printed.  The second argument is the distance away from the right
+margin.  If missing, the previously set value is used; default is
+10@dmn{pt}).  For text lines that are too long (that is, longer than
+the text length plus @var{dist}), the margin character is directly
+appended to the lines.
+
+With no arguments the margin character is turned off.
+If this occurs before a break, no margin character is printed.
+
+@cindex @code{tl} request, and @code{mc}
+For empty lines and lines produced by the @code{tl} request no margin
+character is emitted.
 
 The margin character is associated with the current environment
 (@pxref{Environments}).
@@ -11292,7 +11344,7 @@ there are programs available for doing this (they are called
 @DefregItem {lly}
 @DefregItem {urx}
 @DefregListEnd {ury}
-Retrieves the bounding box of the PostScript image
+Retrieve the bounding box of the PostScript image
 found in @var{filename}.
 The file must conform to
 Adobe's @dfn{Document Structuring Conventions} (DSC);
@@ -11400,11 +11452,15 @@ and strategies for debugging.
 @cindex input line number, setting (@code{lf})
 @cindex number, input line, setting (@code{lf})
 @Defreq {lf, line filename}
-A debugging aid for documents which are split into many files,
-then put together with @code{soelim} and other preprocessors.
-The second argument is the name of the file and the first argument
-is the input line number in that file.  This way @code{gtroff} can
-produce error messages which are intelligible to the user.
+Change the line number and the file name @code{gtroff} shall use for
+error and warning messages.  @var{line} is the input line number of the
+@emph{next} line.
+
+Without argument, the request is ignored.
+
+This is a debugging aid for documents which are split into many files,
+then put together with @code{soelim} and other preprocessors.  Usually,
+it isn't invoked manually.
 
 @c XXX example
 
@@ -11420,8 +11476,8 @@ produce error messages which are intelligible to the user.
 @DefreqList {tm, string}
 @DefreqItem {tm1, string}
 @DefreqListEnd {tmc, string}
-Sends @var{string} to the standard error stream;
-this is very useful for printing debugging output among other things.
+Send @var{string} to the standard error output;
+this is very useful for printing debugging messages among other things.
 
 @var{string} is read in copy mode.
 
@@ -11437,14 +11493,14 @@ not append a newline (as is done in @code{tm} and @code{tm1}).
 @Defreq {ab, [@Var{string}]}
 Similar to the @code{tm} request, except that
 it causes @code{gtroff} to stop processing.  With no argument it
-prints @samp{User Abort}.
+prints @samp{User Abort.} to standard error.
 @endDefreq
 
 @cindex @code{ex} request, use in debugging
 @cindex exiting (@code{ex})
 @Defreq {ex, }
-The @code{ex} request also causes @code{gtroff} to stop processing
-if encountered at the topmost level; see also @ref{I/O}.
+The @code{ex} request also causes @code{gtroff} to stop processing;
+see also @ref{I/O}.
 @endDefreq
 
 When doing something involved it is useful to leave the debugging
@@ -11468,20 +11524,28 @@ the @option{-z} flag.
 @cindex dumping symbol table (@code{pm})
 @cindex symbol table, dumping (@code{pm})
 @Defreq {pm, }
-The @code{pm} request prints out the entire symbol table on @code{stderr}.
+Print the entire symbol table on @code{stderr}.  Names of all defined
+macros, strings, and diversions are print together with their size in
+bytes.  Since @code{gtroff} sometimes adds nodes by itself, the
+returned size can be larger than expected.
+
+This request differs from @acronym{UNIX} @code{troff}: @code{gtroff}
+reports the sizes of diversions, ignores an additional argument to
+print only the total of the sizes, and the size isn't returned in
+blocks of 128 characters.
 @endDefreq
 
 @cindex dumping number registers (@code{pnr})
 @cindex number registers, dumping (@code{pnr})
 @Defreq {pnr, }
-Prints the names and contents of all
+Print the names and contents of all
 currently defined number registers on @code{stderr}.
 @endDefreq
 
 @cindex dumping traps (@code{ptr})
 @cindex traps, dumping (@code{ptr})
 @Defreq {ptr, }
-Prints the names and positions of all traps
+Print the names and positions of all traps
 (not including input line traps and diversion traps) on @code{stderr}.
 Empty slots in the page trap list are printed as well, because they can
 affect the priority of subsequently planted traps.
@@ -11492,17 +11556,44 @@ affect the priority of subsequently planted traps.
 @cindex interactive use of @code{gtroff}
 @cindex @code{gtroff}, interactive use
 @Defreq {fl, }
-Instructs @code{gtroff} to flush its output
-immediately.  The intent is for interactive use.
-@code{gtroff}; there is little other use for it.  This
-request causes a line break.
+Instruct @code{gtroff} to flush its output immediately.  The intent
+is for interactive use, but this behaviour is currently not
+implemented in @code{gtroff}.  Contrary to @acronym{UNIX} @code{troff},
+TTY output is sent to a device driver also (@code{grotty}), making it
+non-trivial to communicate interactively.
+
+This request causes a line break.
 @endDefreq
 
 @cindex backtrace of input stack (@code{backtrace})
 @cindex input stack, backtrace (@code{backtrace})
 @Defreq {backtrace, }
-The @code{backtrace} request prints a backtrace of the input stack
-to the standard error stream.
+Print a backtrace of the input stack to the standard error stream.
+
+Consider the following in file @file{test}:
+
+@Example
+.de xxx
+.  backtrace
+..
+.de yyy
+.  xxx
+..
+.
+.yyy
+@endExample
+
+@noindent
+On execution, @code{gtroff} prints the following:
+
+@Example
+test:2: backtrace: macro `xxx'
+test:5: backtrace: macro `yyy'
+test:8: backtrace: file `test'
+@endExample
+
+The option @option{-b} of @code{gtroff} internally calls a variant of
+this request on each error and warning.
 @endDefreq
 
 @cindex input stack, setting limit
@@ -11523,12 +11614,12 @@ or an error occurs.  The most verbose level of warnings is @option{-ww}.
 @cindex warnings, level (@code{warn})
 @DefreqList {warn, [@Var{flags}]}
 @DefregListEnd {.warn}
-Controls the level of warnings checked for.  The @var{flags} are the sum
+Control the level of warnings checked for.  The @var{flags} are the sum
 of the numbers associated with each warning that is to be enabled; all
 other warnings are disabled.  The number associated with each warning is
 listed below.  For example, @w{@code{.warn 0}} disables all warnings,
 and @w{@code{.warn 1}} disables all warnings except that about missing
-characters.  If an argument is not given, all warnings are enabled.
+characters.  If no argument is given, all warnings are enabled.
 
 The read-only number register @code{.warn} contains the current warning
 level.
@@ -11601,42 +11692,42 @@ current diversion.
 @cindex @code{de} request, and warnings
 @c XXX more index entries
 Use of undefined strings, macros and diversions.  When an undefined
-string, macro or diversion is used, that string is automatically defined
-as empty.  So, in most cases, at most one warning is given for each
-name.
+string, macro, or diversion is used, that string is automatically
+defined as empty.  So, in most cases, at most one warning is given
+for each name.
 
-@item  reg
+@item reg
 @itemx 1024
 @cindex @code{nr} request, and warnings
 @c XXX more index entries
 Use of undefined number registers.  When an undefined number register is
 used, that register is automatically defined to have a value of@w{ }0.
-A definition is automatically made with a value of@w{ }0.  So, in most
-cases, at most one warning is given for use of a particular name.
+So, in most cases, at most one warning is given for use of a particular
+name.
 
-@item  tab
+@item tab
 @itemx 2048
 Use of a tab character where a number was expected.
 
-@item  right-brace
+@item right-brace
 @itemx 4096
 @cindex @code{\@}}, debugging
 Use of @code{\@}} where a number was expected.
 
-@item  missing
+@item missing
 @itemx 8192
 Requests that are missing non-optional arguments.
 
-@item  input
+@item input
 @itemx 16384
 Invalid input characters.
 
-@item  escape
+@item escape
 @itemx 32768
 Unrecognized escape sequences.  When an unrecognized escape sequence is
 encountered, the escape character is ignored.
 
-@item  space
+@item space
 @itemx 65536
 @cindex compatibility mode
 Missing space between a request or macro and its argument.  This warning
@@ -11646,10 +11737,19 @@ name.  The request or macro is not invoked.  When this warning is
 given, no macro is automatically defined.  This is enabled by default.
 This warning never occurs in compatibility mode.
 
-@item  font
+@item font
 @itemx 131072
 Non-existent fonts.  This is enabled by default.
 
+@item ig
+@itemx 262144
+Invalid escapes in text ignored with the @code{ig} request.  These are
+conditions that are errors when they do not occur in ignored text.
+
+@item color
+@itemx 524288
+Color related warnings.
+
 @item all
 All warnings except @samp{di}, @samp{mac} and @samp{reg}.  It is
 intended that this covers all warnings that are useful with traditional
@@ -11694,7 +11794,7 @@ interpreted as the start of a long name.  In compatibility mode GNU
 @code{troff} interprets long names in the traditional way
 (which means that they are not recognized as names).
 
-@DefreqList {cp, n}
+@DefreqList {cp, [@Var{n}]}
 @DefreqItem {do, cmd}
 @DefregListEnd {.C}
 If @var{n} is missing or non-zero, turn on compatibility mode;