[groff] 09/12: [docs]: Revise introduction to troff output.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ebec1551cfa69a4330db2510b7a1d6b425198a14
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Feb 11 07:08:52 2024 -0600

    [docs]: Revise introduction to troff output.
    
    * doc/groff.texi.in (gtroff Output): Do it.
    
    * man/groff_out.5.man (Description): Sync with the foregoing.
      (Background): Add new subsection, incorporating material from our
      Texinfo manual.
    
    Bump copyright notice in groff_out.5.man.
---
 doc/groff.texi.in   |  74 +++++++++++++++---------------
 man/groff_out.5.man | 126 ++++++++++++++++++++++++++++++----------------------
 2 files changed, 111 insertions(+), 89 deletions(-)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 90c0c4a6d..852d37102 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -17879,44 +17879,48 @@ following two sections describe their format.
 @cindex @command{gtroff}, output
 @cindex output, @command{gtroff}
 
-This section describes the @code{groff} intermediate output format
-produced by GNU @code{troff}.
-
-As @code{groff} is a wrapper program around GNU @code{troff} and
-automatically calls an output driver (or ``postprocessor''), this output
-does not show up normally.  This is why it is called
-@emph{intermediate}.  @code{groff} provides the option @option{-Z} to
-inhibit postprocessing such that the produced intermediate output is
-sent to standard output just as it is when calling GNU @code{troff}
-directly.
-
-@cindex @code{troff} output format
-@cindex output format, @code{troff}
-@cindex format, @code{troff} output
+We now describe the @code{groff} device-independent output format
+produced by GNU @command{troff}.
+
+@c BEGIN Keep parallel with subsection "Background" of groff_out(5).
+As @command{groff} is a wrapper program around GNU @command{troff} and
+automatically runs an output driver, users seldom encounter this format
+under normal circumstances.  @command{groff} offers the option
+@option{-Z} to inhibit postprocessing such that GNU @command{troff}'s
+output is sent to the standard output stream just as it is when running
+GNU @command{troff} directly.
+
+The purpose of device-independent output is to facilitate the
+development of postprocessors by providing a common programming
+interface for all devices.  It is a distinct, and much simpler, language
+from that of the formatter, @command{troff}.  The device-independent
+output can be thought of as a ``page description language''.
+
+@cindex @command{troff} output format
+@cindex output format, @command{troff}
+@cindex format, @command{troff} output
 @cindex intermediate output
 @cindex output, intermediate
-Here, the term @dfn{troff output} describes what is output by
-GNU @code{troff}, while @dfn{intermediate output} refers to the language
-that is accepted by the parser that prepares this output for the output
-drivers.  This parser handles whitespace more flexibly than
-@acronym{AT&T}'s implementation and implements obsolete elements for
+In the following discussion, the term @dfn{troff output} describes what
+is output by GNU @command{troff}, while @dfn{device-independent output}
+denotes the language accepted by the parser that interprets this output
+for the output drivers.  This parser handles whitespace more flexibly
+than @acronym{AT&T} @command{troff}'s implementation, recognizes a GNU
+extension to the language, and supports an obsolete construct for
 compatibility; otherwise, both formats are the same.@footnote{The parser
-and postprocessor for intermediate output can be found in the file@*
-@file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
-
-The main purpose of the intermediate output concept is to facilitate the
-development of postprocessors by providing a common programming
-interface for all devices.  It has a language of its own that is
-completely different from the @command{gtroff} language.  While the
-@command{gtroff} language is a high-level programming language for text
-processing, the intermediate output language is a kind of low-level
-assembler language by specifying all positions on the page for writing
-and drawing.
-
-The intermediate output produced by @command{gtroff} is fairly readable,
-while output from @acronym{AT&T} @code{troff} is rather hard to
-understand because of strange habits that are still supported, but not
-used any longer by @command{gtroff}.
+for device-independent output can be found in the file
+@file{@var{groff-source-dir}/@/src/@/libs/@/libdriver/@/input.cpp}.}
+
+When Brian Kernighan designed @acronym{AT&T} @code{troff}'s
+device-independent output format circa 1980, he had to balance
+readability and maintainability against severe constraints on file size
+and transmission speed to the output device.@footnote{See ``A
+Typesetter-independent TROFF'', Bell Labs CSTR@tie{}#97, 1982.}  A
+decade later, when James Clark wrote @code{groff}, these constraints
+were no longer as tight.  GNU @command{troff} therefore emits
+device-independent output that is more easily interpreted by humans than
+did @acronym{AT&T} @code{troff}.
+@c END Keep parallel with subsection "Background" of groff_out(5).
 
 @menu
 * Language Concepts::
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 5b26656de..1c778d9d0 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -10,7 +10,7 @@ intermediate output format
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff type-setting system.
 .\"
@@ -116,6 +116,8 @@ after these commands, otherwise the position is not changed.
 .SH Description
 .\" ====================================================================
 .
+.\" BEGIN Keep parallel with introductory paragraph of the "Language
+.\" Concepts" node in doc/groff.texi.in.
 The fundamental operation of the
 .MR @g@troff @MAN1EXT@
 formatter is the translation of the
@@ -146,74 +148,90 @@ a catch-all for other operations.
 The last includes directives to start and stop output,
 identify the intended output device,
 and embed URL hyperlinks in supported output formats.
+.\" END Keep parallel with introductory paragraph of the "Language
+.\" Concepts" node in doc/groff.texi.in.
 .
 .
-.P
-Because the front-end command
+.\" ====================================================================
+.SS Background
+.\" ====================================================================
+.
+.\" BEGIN Keep parallel with paragraphs after the first in the "gtroff
+.\" Output" node in doc/groff.texi.in.
+As
 .MR groff @MAN1EXT@
-is a wrapper that normally runs the
-.I @g@troff
-formatter to generate intermediate output
-and an output driver (\[lq]postprocessor\[rq]) to consume it,
-users normally do not encounter this language.
+is a wrapper program around GNU
+.I troff \" GNU
+and automatically calls an output driver,
+users seldom encounter this format under normal circumstances.
 .
-The
 .I groff
-program's
-.B \-Z
-option inhibits postprocessing such that this intermediate output is
-sent to the standard output stream as when
-.I @g@troff
-is run manually.
+offers the option
+.B \-z
+to inhibit postprocessing such that GNU
+.IR troff 's \" GNU
+output is sent to the standard output stream just as it is when running
+GNU
+.I troff \" GNU
+directly.
 .
 .
 .P
-.IR groff 's
-intermediate output facilitates the development of output drivers and
-other postprocessors by offering a common programming interface.
-.
-It is an extension of the page description language developed by Brian
-Kernighan for AT&T device-independent
-.I troff \" AT&T
-circa 1980.
-.
-Where a distinction is necessary,
-we will say
-.RI \[lq] @g@troff
-output\[rq] to describe the output of GNU
-.IR troff , \" GNU
-and \[lq]intermediate output\[rq] to denote the language accepted by
-the parser implemented in
-.IR groff 's
-internal C++ library used by most of its output drivers.
-.\" XXX GBR leaves off here.
+The purpose of device-independent output is to facilitate the
+development of postprocessors by providing a common programming
+interface for all devices.
 .
+It is a distinct, and much simpler, language from that of the formatter,
+.IR troff . \" generic
+The device-independent output can be thought of as a \[lq]page
+description language\[rq].
 .
-.\" ====================================================================
-.SH "Language concepts"
-.\" ====================================================================
 .
-During the run of
-.IR @g@troff ,
-the
-.I roff
-input is cracked down to the information on what has to be printed at
-what position on the intended device.
+.P
+In the following discussion,
+the term
+.I "troff output"
+describes what is output by GNU
+.IR troff , \" GNU
+while
+.I "device-independent output"
+denotes the language accepted by the parser that interprets this output
+for the output drivers.
+.
+This parser handles whitespace more flexibly than AT&T
+.IR troff 's \" AT&T
+implementation,
+recognizes a GNU extension to the language,
+and supports an obsolete construct for compatibility;
+otherwise,
+both formats are the same.
 .
-So the language of the
-.I intermediate output
-format can be quite small.
+(The parser for device-independent output can be found in the
+.I groff
+sources at
+.IR \%src/\:\%libs/\:\%libdriver/\:\%input.cpp .)
 .
-Its only elements are commands with or without arguments.
 .
-In this document, the term \[lq]command\[rq] always refers to the
-.I intermediate output
-language, never to the
-.I roff
-language used for document formatting.
+.P
+When Brian Kernighan designed AT&T
+.IR troff 's \" AT&T
+device-independent output format circa 1980,
+he had to balance
+readability and maintainability against severe constraints on file size
+and transmission speed to the output device.
+.
+A decade later,
+when James Clark wrote
+.IR groff ,
+these constraints were no longer as tight.
 .
-There are commands for positioning and text writing, for drawing, and
-for device controlling.
+GNU
+.I troff \" GNU
+therefore emits device-independent output that is more easily
+interpreted by humans than did AT&T
+.IR troff . \" AT&T
+.\" END Keep parallel with paragraphs after the first in the "gtroff
+.\" Output" node in doc/groff.texi.in.
 .
 .
 .\" ====================================================================