[groff] 02/02: Update descriptions of groff -a and grotty -c.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 69c400e082f2b11c8b79a4a6224f174ee8a28d53
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jun 12 18:27:39 2020 +1000

    Update descriptions of groff -a and grotty -c.
    
    * doc/groff.texi (Groff Options): Remove editorial comment about '-a'
      option being "useless".  It isn't.  Update example for contemporary
      systems (like Debian) and to reflect the fact that the GNU troff(1)
      man page needs to be preprocessed with tbl(1).
    
      (Invoking grotty): Recast discussion of -c option, importing much
      language from grotty(1) page rewrite from a year ago.  Add program
      index entries for col, more, and ul.  Fix transposition error in ISO
      document number.
    
    * src/devices/grotty/grotty.1.man (Description/Legacy output format):
      Make slight wording changes prompted by content of parallel section in
      Texinfo manual.
    
    * src/roff/groff/groff.1.man (Options/-a): Parallelize with first
      sentence of corresponding material in Texinfo manual.
    
    * src/roff/troff/troff.1.man (Options/-a): Parallelize with Texinfo
      manual.
    
    Fixes the rest of <https://savannah.gnu.org/bugs/index.php?55278>.
---
 ChangeLog                       | 31 ++++++++++++++++++++++
 doc/groff.texi                  | 58 ++++++++++++++++++++++++++++-------------
 src/devices/grotty/grotty.1.man | 11 +++++---
 src/roff/groff/groff.1.man      |  5 +++-
 src/roff/troff/troff.1.man      | 24 ++++++++++++++++-
 5 files changed, 106 insertions(+), 23 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e99cc0c..a8268d2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,29 @@
 2020-06-12  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       * doc/groff.texi (Groff Options): Remove editorial comment about
+       '-a' option being "useless".  It isn't.  Update example for
+       contemporary systems (like Debian) and to reflect the fact that
+       the GNU troff(1) man page needs to be preprocessed with tbl(1).
+       (Invoking grotty): Recast discussion of -c option, importing
+       much language from grotty(1) page rewrite from a year ago.  Add
+       program index entries for col, more, and ul.  Fix transposition
+       error in ISO document number.
+
+       * src/devices/grotty/grotty.1.man (Description/Legacy output
+       format): Make slight wording changes prompted by content of
+       parallel section in Texinfo manual.
+
+       * src/roff/groff/groff.1.man (Options/-a): Parallelize with
+       first sentence of corresponding material in Texinfo manual.
+
+       * src/roff/troff/troff.1.man (Options/-a): Parallelize with
+       Texinfo manual.
+
+       Fixes the rest of
+       <https://savannah.gnu.org/bugs/index.php?55278>.
+
+2020-06-12  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        * man/groff_diff.7.man (Language/Long names): Fix error; groff
        adds three new requests with short names, not two.  List them in
        an adjacent comment.
@@ -981,6 +1005,13 @@
        * src/roff/groff/tests/string_case_xform_requests.sh: New test.
        * src/roff/groff/groff.am: Run the tests.
 
+2019-06-30  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * src/devices/grotty/grotty.1.man (Options/-i): Note support of
+       recent versions of xterm for italic (oblique) styles.
+
+       Fixes part of <https://savannah.gnu.org/bugs/index.php?55278>.
+
 2019-06-28  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        devlatin1: Map \(oq to ' on output.
diff --git a/doc/groff.texi b/doc/groff.texi
index bc8e3fd..ceaa9d0 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1031,18 +1031,19 @@ Here's the description of the command-line options:
 @table @samp
 @item -a
 @cindex @acronym{ASCII} approximation output register (@code{.A})
-Generate an @acronym{ASCII} approximation of the typeset output.  The
-read-only register @code{.A} is then set to@tie{}1.  @xref{Built-in
-Registers}.  A typical example is
+Generate an @acronym{ASCII} (Unicode basic Latin) approximation of the
+typeset output.  The read-only register @code{.A} is set to@tie{}1.
+@xref{Built-in Registers}.  On a system using the @code{man-db} manual
+page formatter and that installs man pages compressed with @code{gzip},
+one might use the shell command
 
 @Example
-groff -a -man -Tdvi troff.man | less
+zcat $(man -w troff) | groff -a -t -man -Tdvi \
+| less
 @endExample
 
 @noindent
-which shows how lines are broken for the DVI device.  Note that this
-option is rather useless today since graphic output devices are
-available virtually everywhere.
+to observe how lines are broken for the DVI device.
 
 @item -b
 Print a backtrace with each warning or error message.  This backtrace
@@ -14939,21 +14940,42 @@ used.
 Print the version number.
 @end table
 
+@pindex col
 @pindex less
+@pindex more
+@pindex ul
 @cindex Teletype
-@cindex ISO 6249 SGR
+@cindex ISO 6429 SGR
 @cindex terminal control sequences
 @cindex control sequences, for terminals
-The @option{-c} mode for TTY output devices means that underlining is
-done by emitting sequences of @samp{_} and @samp{^H} (the backspace
-character) before the actual character.  Literally, this is printing
-an underline character, then moving the caret back one character
-position, and printing the actual character at the same position as
-the underline character (similar to a typewriter).  Usually, a modern
-terminal can't interpret this (and the original Teletype machines for
-which this sequence was appropriate are no longer in use).  You need
-a pager program like @code{less} that translates this into
-ISO@tie{}6429 SGR sequences to control terminals.
+The @option{-c} option tells @code{grotty} to use an output format
+compatible with paper terminals, like the Teletype machines for which
+@code{roff} and @code{nroff} were first developed but which are no
+longer in wide use.  SGR escape sequences (from ISO@tie{}6429) are not
+emitted.  Instead, @code{grotty} overstrikes, representing a bold
+character @var{c} with the sequence @samp{@var{c} BACKSPACE @var{c}} and
+an italic character @var{c} with the sequence @samp{_ BACKSPACE
+@var{c}}.  Furthermore, color output is disabled.  The same effect can
+be achieved either by setting the @env{GROFF_NO_SGR} environment
+variable or by using a @code{groff} escape sequence within the document;
+see the subsection ``Device control commands'' of the @cite{grotty(1)}
+man page for details.
+
+The legacy output format can be rendered on a video terminal (or
+emulator) by piping @code{grotty}'s output through @code{ul},
+@c from bsdmainutils 11.1.2+b1 (on Debian Buster)
+which may render bold italics as reverse video.
+@c 'more' from util-linux 2.33.1 (on Debian Buster) neither renders
+@c double-struck characters as bold nor supports -b, but does render
+@c SGR sequences (including color) with no flags required.
+Some implementations of @code{more} are also able to display these
+sequences; you may wish to experiment with that command's @option{-b}
+option.
+@c Version 487 of...
+@code{less} renders legacy bold and italics without requiring options.
+In contrast to the teletype output drivers of some other @code{roff}
+implementations, @code{grotty} never outputs reverse line feeds.  There
+is therefore no need to filter its output through @code{col}.
 
 
 @c =====================================================================
diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index 792a098..eb8a357 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -173,9 +173,14 @@ The
 .B \-c
 option tells
 .I grotty
-to use an output format compatible with paper teletypes.
+to use an output format compatible with paper terminals,
+like the Teletype machines for which
+.I roff
+and
+.I nroff
+were first developed but which are no longer in wide use.
 .
-SGR escape sequences are not used.
+SGR escape sequences are not emitted.
 .
 Instead,
 .I grotty
@@ -205,7 +210,7 @@ below.
 .
 .
 .LP
-The legacy output format can be rendered on a terminal
+The legacy output format can be rendered on a video terminal
 (or emulator)
 by piping
 .IR grotty 's
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 811979b..88e6667 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -654,7 +654,10 @@ These options are described in more detail in
 .
 .TP
 .B \-a
-\f[CR]ASCII\f[] approximation of output.
+Generate an ASCII
+(Unicode basic Latin)
+approximation of the typeset output.
+.
 .
 .TP
 .B \-b
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index 3ce761f..c49c64a 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -78,7 +78,29 @@ Whitespace is permitted between a command-line option and 
its argument.
 .
 .TP
 .B \-a
-Generate an ASCII approximation of the typeset output.
+Generate an ASCII
+(Unicode basic Latin)
+approximation of the typeset output.
+.
+The read-only register
+.B .A
+is set to\~1.
+.
+On a system using the
+.I man\-db
+manual page formatter and that installs man pages compressed with
+.IR gzip (1),
+one might use the shell command
+.
+.RS
+.RS
+.EX
+zcat $(man \-w troff) | groff \-a -t \-man \-Tdvi | less
+.EE
+.RE
+to observe how lines are broken for the DVI device.
+.RE
+.
 .
 .TP
 .B \-b