gbranden pushed a commit to branch master
in repository groff.
commit 133c42e2ac418050279c4aba9df2010f31c7b733
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Sep 14 13:13:39 2024 -0500
[doc,man]: Reform terminology.
"Output format" tells the reader little; they can tell it's output, and
casual inspection reveals that it's a format of some sort.
Call it what it is: a page description (language).
At last I sink my sword to the quillons into the breast of the wretched
monster "intermediate output format", one of the worst selections of
terminology I've seen in my entire life. Die, foul beast!
Will someone offer us a special transparent intermediate output format?
---
NEWS | 4 ++--
doc/groff.texi.in | 34 +++++++++++++++++++---------------
man/groff.7.man | 12 ++++++------
man/groff_diff.7.man | 9 +++++----
man/groff_font.5.man | 4 ++--
man/groff_out.5.man | 10 +++++-----
6 files changed, 39 insertions(+), 34 deletions(-)
diff --git a/NEWS b/NEWS
index ce82dee69..c78a1b57b 100644
--- a/NEWS
+++ b/NEWS
@@ -70,8 +70,8 @@ o In nroff mode (in other words, when producing output for
devices that
inches (or the unit configured with the `warnscale` request) to
describe the vertical drawing position where the problem occurred.
-o The device-independent output now reports unbreakable spaces (those
- produced with the `\~` escape sequence) as word breaks with the
+o The device-independent page description now reports unbreakable spaces
+ (those produced with the `\~` escape sequence) as word breaks with the
documentary 'w' command, just as it does for regular breakable spaces.
o A new request, `hydefault`, and read-only register, `.hydefault`,
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 2346e0de5..715781cc3 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16685,9 +16685,9 @@ construction in that the contents of the string or
macro @var{name} are
not interpreted; further, @var{name} may be a macro and thus contain
newlines. (There is no way to embed a newline in the arguments to
@code{device} or @code{\X}.) The inclusion of newlines requires an
-extension to the @acronym{AT&T} @command{troff} output format; their
-presence confuses drivers that do not know about it (@pxref{Device
-Control Commands}).
+extension to the @acronym{AT&T} @command{troff} device-independen page
+description language; their presence confuses drivers that do not know
+about it (@pxref{Device Control Commands}).
@endDefesc
@DefreqList {tag, name}
@@ -18007,8 +18007,8 @@ following two sections describe their format.
@cindex @command{gtroff}, output
@cindex output, @command{gtroff}
-We now describe the @code{groff} device-independent output format
-produced by GNU @command{troff}.
+We now describe the @code{groff} device-independent page description
+language 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
@@ -18024,25 +18024,28 @@ 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} page description language
+@cindex page description language, @command{troff}
+@cindex language, @command{troff} page description
@cindex @command{troff} output format
@cindex output format, @command{troff}
@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{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
+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. 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
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
+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. GNU @command{troff} therefore emits
@@ -18168,8 +18171,9 @@ x init
@noindent
with the arguments set as outlined in @ref{Device Control Commands}.
-The parser for the intermediate output format is able to interpret
-additional whitespace and comments as well even in the prologue.
+The parser for the device-independent page description language format
+is able to interpret additional whitespace and comments as well even in
+the prologue.
The body is the main section for processing the document data.
Syntactically, it is a sequence of any commands different from the ones
@@ -18829,7 +18833,7 @@ first documented in @cite{A Typesetter-independent
TROFF}, by Brian
Kernighan, and by 1992 the @acronym{AT&T} @code{troff} manual was
updated to incorporate a description of it.
-The GNU @code{troff} intermediate output format is compatible with this
+GNU @code{troff}'s page description language is compatible with this
specification except for the following features.
@itemize @bullet
diff --git a/man/groff.7.man b/man/groff.7.man
index 0fec2729f..3a1559540 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -317,7 +317,7 @@ a program that reads device and font descriptions
interprets the
.I groff
language expressed in input text,
-translating it to a device-independent output format
+translating it to a device-independent page description language
(\c
.MR groff_out @MAN5EXT@ )
that is usually then post-processed by an output driver to produce
@@ -8231,7 +8231,7 @@ or
.
The inclusion of newlines requires an extension to the AT&T
.I troff \" AT&T
-output format;
+device-independent page description language;
their presence confuses drivers that do not know about it
(see subsection \[lq]Device control commands\[rq] of
.MR groff_out @MAN5EXT@ ).
@@ -8448,7 +8448,7 @@ and that of AT&T
.IR troff , \" AT&T
as well as the device,
font,
-and device-independent intermediate output formats described by
+and device-independent page description formats described by
CSTR\~#54 are documented in
.MR groff_diff @MAN7EXT@ .
.
@@ -8581,7 +8581,7 @@ AT&T Bell Laboratories Computing Science Technical Report
No.\& 54,
widely called simply \[lq]CSTR\~#54\[rq],
documents the language,
device and font description file formats,
-and device-independent output format
+and device-independent page description language
referred to collectively in
.I groff
documentation as
@@ -8598,7 +8598,7 @@ AT&T Bell Laboratories Computing Science Technical Report
No.\& 97
(CSTR\~#97),
provides additional insights into the
device and font description file formats
-and device-independent output format.
+and device-independent page description language.
.
.
.TP
@@ -8634,7 +8634,7 @@ GNU
.I troff \" GNU
formatter,
its device and font description file formats,
-its device-independent output format,
+its device-independent page description language,
and those of AT&T
.IR troff ,\" AT&T
whose design it reimplements.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 6af9357cc..385b1d883 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1195,7 +1195,7 @@ cannot.
.
This inclusion of newlines requires an extension to the AT&T
.I troff \" AT&T
-output format,
+page description language,
and confuses postprocessors that do not know about it.
.
.
@@ -6147,7 +6147,8 @@ will not.
Its extensions notwithstanding,
GNU
.IR troff 's \" GNU
-output format has some incompatibilities with that of AT&T
+page description language
+has some incompatibilities with that of AT&T
.IR troff , \" AT&T
but better compatibility is sought;
problem reports and patches are welcome.
@@ -6216,7 +6217,7 @@ AT&T Bell Laboratories Computing Science Technical Report
No.\& 54,
widely called simply \[lq]CSTR\~#54\[rq],
documents the language,
device and font description file formats,
-and output format
+and page description language
referred to collectively in
.I groff
documentation as AT&T
@@ -6230,7 +6231,7 @@ by Brian W.\& Kernighan,
AT&T Bell Laboratories Computing Science Technical Report No.\& 97,
provides additional insights into the
device and font description file formats
-and output format.
+and page description language.
.
.
.P
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 4275881f4..d12f46187 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -1076,7 +1076,7 @@ AT&T Bell Laboratories Computing Science Technical Report
No.\& 54,
widely called simply \[lq]CSTR\~#54\[rq],
documents the language,
device and font description file formats,
-and device-independent output format
+and device-independent page description language
referred to collectively in
.I groff
documentation as
@@ -1090,7 +1090,7 @@ by Brian W.\& Kernighan,
AT&T Bell Laboratories Computing Science Technical Report No.\& 97,
provides additional insights into the
device and font description file formats
-and device-independent output format.
+and device-independent page description language.
.
.
.P
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 3ae3bb50a..447713267 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -2,7 +2,7 @@
.SH Name
groff_out \- GNU
.I roff
-device-independent output format
+device-independent page description language
.
.
.\" XXX: This page needs review and editing.
@@ -215,7 +215,7 @@ sources at
.P
When Brian Kernighan designed AT&T
.IR troff 's \" AT&T
-device-independent output format circa 1980,
+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.
@@ -1850,7 +1850,7 @@ James Clark wrote an early version of this document,
which described only the differences between AT&T
device-independent
.IR troff 's \" AT&T
-output format and that of GNU
+page description language and that of GNU
.IR troff . \" GNU
.
It has since been expanded and revised by
@@ -1889,7 +1889,7 @@ AT&T Bell Laboratories Computing Science Technical Report
No.\& 54,
widely called simply \[lq]CSTR\~#54\[rq],
documents the language,
device and font description file formats,
-and device-independent output format
+and device-independent page description language
referred to collectively in
.I groff
documentation as
@@ -1904,7 +1904,7 @@ AT&T Bell Laboratories Computing Science Technical Report
No.\& 97,
(CSTR\~#97),
provides additional insights into the
device and font description file formats
-and device-independent output format.
+and device-independent page description language.
.
.
.TP
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
