gbranden pushed a commit to branch master
in repository groff.
commit b708c1b283d9655b29c10219a7e3f20f56b68967
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Jan 25 02:04:01 2026 -0600
[doc,man]: Revise "GNU troff output" stuff (1/x).
Parallelize introductory paragraphs of "GNU troff Output" node/section
of our Texinfo manual and groff_out(5).
---
doc/groff.texi.in | 79 +++++++++++++++++++++++++++++++++++------------------
man/groff_out.5.man | 35 +++++++++++++-----------
2 files changed, 72 insertions(+), 42 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index dd4dc7bea..27ab3c611 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -23103,21 +23103,39 @@ for@tie{}@var{n}.
@cindex output, @command{@g@troff}
We now describe the @code{groff} device-independent page description
-language produced by GNU @command{troff}.
+language produced by GNU
+@command{troff}. @c GNU
@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
+As
+@command{groff}
+is a wrapper program around
+GNU
+@command{troff} @c GNU
+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 @c GNU
output is sent to the standard output stream just as it is when running
-GNU @command{troff} directly.
+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''.
+The purpose of device-independent output
+is to facilitate the development of postprocessors
+by providing a common programming interface to all devices.
+It is a distinct,
+and much simpler,
+language
+from that of the formatter,
+@command{troff}. @c generic
+The device-independent output can be thought of
+as a ``page description language''.
@cindex @command{troff} page description language
@cindex page description language, @command{troff}
@@ -23127,27 +23145,38 @@ output can be thought of as a ``page description
language''.
@cindex format, @command{troff} output
@cindex intermediate output
@cindex output, intermediate
-In the following discussion, the term @dfn{troff output} describes what
-is output by GNU @command{troff}, while @dfn{page description} denotes
-the language accepted by the parser that interprets this output for the
-output drivers.
+In the following discussion,
+the term
+@dfn{troff output}
+describes what is output by
+GNU
+@command{troff}, @c GNU
+while
+@dfn{page description}
+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;
+and supports a legacy compressed encoding of a subset of commands
+for compatibility;
otherwise,
the formats are the same.@footnote{The parser
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 page description language 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.
+When Brian Kernighan designed @acronym{AT&T}
+@command{troff}'s @c AT&T
+device-independent page description language 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.
@c END Keep parallel with subsection "Background" of groff_out(5).
@menu
@@ -23175,9 +23204,7 @@ In the following discussion,
the term
@dfn{command}
always refers to this device-independent output language,
-and never to the
-@code{groff}
-language intended for direct use by document authors.
+and never to the language intended for direct use by document authors.
Device-independent output commands comprise several categories:@:
glyph output;
font,
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 599cc0722..6499f068a 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -118,9 +118,11 @@ after these commands, otherwise the position is not
changed.
.
.\" 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
+The fundamental operation of the GNU
+.I troff \" GNU
+formatter,
+.MR @g@troff @MAN1EXT@ ,
+is the translation of the
.MR groff @MAN7EXT@
input language
into a series of instructions concerned primarily
@@ -131,9 +133,7 @@ In the following discussion,
the term
.I command
refers to this device-independent output language,
-never to the
-.MR groff @MAN7EXT@
-language intended for use by document authors.
+never to the language intended for use by document authors.
.
Device-independent output commands comprise several categories:
glyph output;
@@ -157,8 +157,8 @@ and embed URL hyperlinks in supported output formats.
.SS Background
.\" ====================================================================
.
-.\" BEGIN Keep parallel with paragraphs after the first in the "gtroff
-.\" Output" node in doc/groff.texi.in.
+.\" BEGIN Keep parallel with paragraphs after the first in the "GNU
+.\" troff Output" node in doc/groff.texi.in.
As
.MR groff @MAN1EXT@
is a wrapper program around GNU
@@ -178,14 +178,16 @@ directly.
.
.
.P
-The purpose of device-independent output is to facilitate the
-development of postprocessors by providing a common programming
-interface for all devices.
+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,
+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].
+The device-independent output can be thought of
+as a \[lq]page description language\[rq].
.
.
.P
@@ -195,7 +197,7 @@ the term
describes what is output by GNU
.IR troff , \" GNU
while
-.I "device-independent output"
+.I "page description"
denotes the language accepted by the parser that interprets this output
for the output drivers.
.
@@ -203,7 +205,8 @@ 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;
+and supports a legacy compressed encoding of a subset of commands
+for compatibility;
otherwise,
the formats are the same.
.
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
