[groff] 03/03: [docs]: Document groff/troff -a option.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 534680662889eb74dac3e100bcadf97e5962f027
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Nov 30 05:23:53 2020 +1100

    [docs]: Document groff/troff -a option.
    
    As far as I can tell, I'm the first person ever to document what this
    option does in anything but the vaguest terms.  :-/  I checked DWB 3.3
    troff, Solaris troff, Plan 9 troff, Heirloom Doctools troff, and
    neatroff (the last of which doesn't implement it).
    
    Thanks to Dave Kemper for the discussion in Savannah #55278.
---
 doc/groff.texi             | 40 ++++++++++++++++++++++----------
 src/roff/groff/groff.1.man |  5 ++--
 src/roff/troff/troff.1.man | 58 ++++++++++++++++++++++++++++++++++------------
 3 files changed, 73 insertions(+), 30 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b161df8..28d56d5 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1041,20 +1041,36 @@ Here's the description of the command-line options:
 @cindex command-line options
 @table @samp
 @item -a
-@cindex @acronym{ASCII} approximation output register (@code{.A})
-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
+@cindex plain text approximation output register (@code{.A})
+Generate a plain text approximation of the typeset output.  The
+read-only register @code{.A} is set to@tie{}1.  @xref{Built-in
+Registers}.  This option produces a sort of abstract preview of the
+formatted output.
 
-@Example
-zcat $(man -w troff) | groff -a -t -man -Tdvi \
-| less
-@endExample
+@itemize @bullet
+@item
+Page breaks are marked by a phrase in angle brackets; for example,
+@samp{<beginning of page>}.
 
-@noindent
-to observe how lines are broken for the DVI device.
+@item
+Lines are broken where they would be in the formatted output.
+
+@item
+A horizontal motion of any size is represented as one space.  Adjacent
+horizontal motions are not combined.  Inter-sentence space nodes (those
+arising from the second argument to the @code{ss} request) are not
+represented.
+
+@item
+Vertical motions are not represented.
+
+@item
+Special characters are rendered in angle brackets; for example, the
+default soft hyphen character appears as @samp{<hy>}.
+@end itemize
+
+The above description should not be considered a specification; the
+details of @option{-a} output are subject to change.
 
 @item -b
 Print a backtrace with each warning or error message.  This backtrace
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index dd47a5a..3758141 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -621,11 +621,10 @@ subsequently.
 These options are described in more detail in
 .IR \%@g@troff (@MAN1EXT@).
 .
+.
 .TP
 .B \-a
-Generate an ASCII
-(Unicode basic Latin)
-approximation of the typeset output.
+Generate a plain text approximation of the typeset output.
 .
 .
 .TP
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index db28cf7..4596756 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -89,37 +89,65 @@ appropriate order and with the appropriate options.
 .
 .TP
 .B \-a
-Generate an ASCII
-(Unicode basic Latin)
-approximation of the typeset output.
+Generate a plain text 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
+This option produces a sort of abstract preview of the formatted output.
+.
 .
 .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.
+.IP \[bu]
+Page breaks are marked by a phrase in angle brackets;
+for example,
+\[lq]<beginning of page>\[rq].
+.
+.
+.IP \[bu]
+Lines are broken where they would be in the formatted output.
+.
+.
+.IP \[bu]
+A horizontal motion of any size is represented as one space.
+.
+Adjacent horizontal motions are not combined.
+.
+Inter-sentence space nodes
+(those arising from the second argument to the
+.B .ss
+request)
+are not represented.
+.
+.
+.IP \[bu]
+Vertical motions are not represented.
+.
+.
+.IP \[bu]
+Special characters are rendered in angle brackets;
+for example,
+the default soft hyphen character appears as
+\[lq]<hy>\[rq].
 .RE
 .
 .
+.IP
+The above description should not be considered a specification;
+the details of
+.B \-a
+output are subject to change.
+.
+.
 .TP
 .B \-b
 Print a backtrace with each warning or error message.
 .
 This backtrace should help track down the cause of the error.
 .
-The line numbers given in the backtrace may not always be correct, for
+The line numbers given in the backtrace may not always be correct,
+for
 .IR \%@g@troff 's
 idea of line numbers gets confused by
 .B .as