[groff] 24/28: doc/groff.texi: Reduce mentions of "ditroff".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 54351381bce1fb035e310598f259db3b75990290
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 29 05:17:52 2020 +1000

    doc/groff.texi: Reduce mentions of "ditroff".
    
    I read somewhere that I cannot now locate that Kernighan personally does
    not prefer the term "ditroff", and in any event I want to get rid of
    groff's ditroff(7) page some day.  It's old, outmoded jargon anyway, so
    confine it to the History node where it belongs.
    
    * doc/groff.texi (History): Relegate "ditroff" to a mention that it is
      "used by some".  Elaborate what the new drawing functions were.  Dodge
      explaining B-splines.
    
      (History):
      (Font files):
      (Font file format):
      Say "[AT&T] device-independent troff" instead of "ditroff".
    
    * man/groff_out.5.man (Authors): Replace and...
    * man/roff.7.man (History/The classical nroff/troff system): ...reduce
      usage of "ditroff" in favor of "[AT&T] device-independent troff".
    
    * doc/groff.texi (History):
      (Output device intro):
      Hyphenate "device-independent" because it is an attributive phrase.
    
      (Output device intro):
      Drop Denglish actually [recte currently].  Not necessary in either
      sense.
    
      (Output language compatibility):
      Follow "quasi-" with a hyphen, since it cannot stand alone in English,
      but it certainly does look a bit odd when it needs to modify a noun
      phrase for which grammar rules militate against hyphenation.
      Consider: in "I consider gelato to be at best a sort of quasi-ice
      cream.", "quasi-ice-cream" would be incorrect.
    
      (Font files):
      Say "GNU troff" instead of "gtroff".
    
      (History):
      (Font files):
      Tighten wording.  Use more idiomatic English.
    
    * man/groff_font.5.man: Sync wording with groff.texi changes.
    
    * doc/groff.texi (Font Files):
    * man/groff_font.5.man: Add comments for parallel maintenance.
    
    * man/groff_diff.7.man (Escape sequences) <\O0>: Drop qualification
      of "any ditroff" glyphs having their output disabled.  Per
      src/roff/troff/input.cpp::do_suppress(), it's all glyphs.  There
      don't seem to be any subclasses of glyph_node anyway.
    
    Incidentally, it seems Wikipedia borrowed portions of its troff article
    from our Texinfo manual.  I infer that to be the case because much of
    the language in our manual's History node hasn't been changed since
    1999-2002, and Wikipedia added the familiar language from 2003 on.
    Wikipedia can't, of course, incorporate our updates due to license
    incompatibility.  Hooray FDL.
---
 doc/groff.texi       | 102 ++++++++++++++++++++++++++-------------------------
 man/groff_diff.7.man |  19 +++++-----
 man/groff_font.5.man |  16 +++++++-
 man/groff_out.5.man  |   7 ++--
 man/roff.7.man       |  25 ++++++-------
 5 files changed, 94 insertions(+), 75 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 034d29b..c134c9a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -703,20 +703,22 @@ according to a bibliographic database.
 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
 language and produced output specifically for the CAT phototypesetter.
 He rewrote it in C, although it was now 7000@tie{}lines of uncommented
-code and still dependent on the CAT@.  As the CAT became less common, and
-was no longer supported by the manufacturer, the need to make it support
-other devices became a priority.  However, before this could be done,
-Ossanna died by a severe heart attack in a hospital while recovering
-from a previous one.
+code and still dependent on the CAT@.  As the CAT became less common,
+and was no longer supported by the manufacturer, the need to make it
+support other devices became a priority.  However, before this could be
+done, Ossanna died from a severe heart attack in a hospital while
+recovering from a previous one.
 
 @pindex ditroff
 @cindex @code{ditroff}, the program
-So, Brian Kernighan took on the task of rewriting @code{troff}.  The
-newly rewritten version produced device independent code that was very
-easy for postprocessors to read and translate to the appropriate printer
-codes.  Also, this new version of @code{troff} (called @code{ditroff}
-for ``device independent @code{troff}'') had several extensions, which
-included drawing functions.
+Brian Kernighan took on the task of rewriting @code{troff}.  The result
+produced device-independent code that was easy for postprocessors to
+read and translate to appropriate printer commands.  This new
+``device-independent @code{troff}'', called @code{ditroff} by some, had
+several extensions, including drawing commands for lines, circles,
+ellipses, arcs, and B-splines@footnote{Short for ``basis splines''; ask
+your local numerical analyst.  The rest of us can just think of them as
+``curves''.}.
 
 Due to the additional abilities of the new version of @code{troff},
 several new preprocessors appeared.  The @code{pic} preprocessor
@@ -725,13 +727,15 @@ preprocessor did the same, although via a much different 
paradigm.  The
 @code{grap} preprocessor took specifications for graphs, but, unlike
 other preprocessors, produced @code{pic} code.
 
-James Clark began work on a GNU implementation of @code{ditroff} in
-early@tie{}1989.  The first version, @code{groff}@tie{}0.3.1, was
-released June@tie{}1990.  @code{groff} included:
+James Clark began work on a GNU implementation of device-independent
+@code{troff} in early@tie{}1989.  The first version,
+@code{groff}@tie{}0.3.1, was released June@tie{}1990.  @code{groff}
+included:
 
 @itemize @bullet
 @item
-A replacement for @code{ditroff} with many extensions.
+A replacement for AT&T device-independent @code{troff} with many
+extensions.
 
 @item
 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
@@ -900,11 +904,11 @@ mathematical pictures (@code{ideal}).
 @cindex output devices
 @cindex devices for output
 
-@code{groff} actually produces device independent code that may be fed
-into a postprocessor to produce output for a particular device.
-Currently, @code{groff} has postprocessors for @sc{PostScript} devices,
-character terminals, X@tie{}Windows (for previewing), @TeX{} DVI format,
-HP LaserJet@tie{}4 and Canon LBP printers (which use @acronym{CAPSL}),
+@code{groff} produces device-independent code that may be fed into a
+postprocessor to produce output for a particular device.  Currently,
+@code{groff} has postprocessors for @sc{PostScript} devices, character
+terminals, X@tie{}Windows (for previewing), @TeX{} DVI format, HP
+LaserJet@tie{}4 and Canon LBP printers (which use @acronym{CAPSL}),
 @acronym{HTML}, @acronym{XHTML}, and @acronym{PDF}.
 
 
@@ -16542,7 +16546,7 @@ specification except for the following features.
 
 @itemize @bullet
 @item
-The classical quasi device independence is not yet implemented.
+The classical quasi-device independence is not yet implemented.
 
 @item
 The old hardware was very different from what we use today.  So the
@@ -16552,7 +16556,7 @@ in @acronym{AT&T} @code{troff}.  For example, the 
@acronym{AT&T}
 only 720 units per inch, suitable for printers 20 years ago, while
 @code{groff}'s @code{ps} device has a resolution of 72000 units per
 inch.  Maybe, by implementing some rescaling mechanism similar to the
-classical quasi device independence, @code{groff} could emulate
+classical quasi-device independence, @code{groff} could emulate
 @acronym{AT&T}'s @code{post} device.
 
 @item
@@ -16598,20 +16602,20 @@ follow quite naturally.
 
 @c =====================================================================
 
+@c BEGIN Keep parallel with groff_font(7).
 @node Font Files,  , gtroff Output, File formats
 @section Font Files
 @cindex font files
 @cindex files, font
 
-The @code{gtroff} font format is roughly a superset of the
-@code{ditroff} font format (as used in later versions of @acronym{AT&T}
-@code{troff} and its descendants).  Unlike the @code{ditroff} font
-format, there is no associated binary format; all files are text
-files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
-format.}  The font files for device @var{name} are stored in a directory
-@file{dev@var{name}}.  There are two types of file: a device description
-file called @file{DESC} and for each font@tie{}@var{f} a font file
-called@tie{}@file{@var{f}}.
+The GNU @code{troff} font format is a rough superset of the AT&T
+device-independent @code{troff} font format.  In distinction to the AT&T
+implementation, GNU @code{troff} lacks a binary format; all files are
+text files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the
+binary format.}  The font files for device @var{name} are stored in a
+directory @file{dev@var{name}}.  There are two types of file: a device
+description file called @file{DESC} and for each font@tie{}@var{f} a
+font file called@tie{}@file{@var{f}}.
 
 @menu
 * DESC File Format::
@@ -16962,23 +16966,23 @@ There must not be any spaces between these subfields 
(it has been split
 here into two lines for better legibility only).  Missing subfields are
 assumed to be@tie{}0.  The subfields are all decimal integers.  Since
 there is no associated binary format, these values are not required to
-fit into a variable of type @samp{char} as they are in @code{ditroff}.
-The @var{width} subfield gives the width of the glyph.  The @var{height}
-subfield gives the height of the glyph (upwards is positive); if a glyph
-does not extend above the baseline, it should be given a zero height,
-rather than a negative height.  The @var{depth} subfield gives the depth
-of the glyph, that is, the distance from the baseline to the lowest
-point below the baseline to which the glyph extends (downwards is
-positive); if a glyph does not extend below the baseline, it should be
-given a zero depth, rather than a negative depth.  The
-@var{italic-correction} subfield gives the amount of space that should
-be added after the glyph when it is immediately to be followed by a
-glyph from a roman font.  The @var{left-italic-correction} subfield
-gives the amount of space that should be added before the glyph when it
-is immediately to be preceded by a glyph from a roman font.  The
-@var{subscript-correction} gives the amount of space that should be
-added after a glyph before adding a subscript.  This should be less than
-the italic correction.
+fit into a variable of type @samp{char} as they are in AT&T
+device-independent @code{troff}.  The @var{width} subfield gives the
+width of the glyph.  The @var{height} subfield gives the height of the
+glyph (upwards is positive); if a glyph does not extend above the
+baseline, it should be given a zero height, rather than a negative
+height.  The @var{depth} subfield gives the depth of the glyph, that is,
+the distance from the baseline to the lowest point below the baseline to
+which the glyph extends (downwards is positive); if a glyph does not
+extend below the baseline, it should be given a zero depth, rather than
+a negative depth.  The @var{italic-correction} subfield gives the amount
+of space that should be added after the glyph when it is immediately to
+be followed by a glyph from a roman font.  The
+@var{left-italic-correction} subfield gives the amount of space that
+should be added before the glyph when it is immediately to be preceded
+by a glyph from a roman font.  The @var{subscript-correction} gives the
+amount of space that should be added after a glyph before adding a
+subscript.  This should be less than the italic correction.
 
 A line in the @code{charset} section can also have the format
 
@@ -17002,7 +17006,7 @@ sequence of lines of the form:
 This means that when glyph @var{c1} appears next to glyph @var{c2} the
 space between them should be increased by@tie{}@var{n}.  Most entries in
 the kernpairs section have a negative value for@tie{}@var{n}.
-
+@c END Keep parallel with groff_font(7).
 
 
 @c =====================================================================
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 36c9e26..10f994e 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -555,8 +555,9 @@ are intended for internal use by
 .RS
 .TP
 .B \[rs]O0
-Disable any ditroff glyphs from being emitted to the device driver,
-provided that the escape occurs at the outer level (see
+Disable glyphs from being emitted to the device driver,
+provided that the escape occurs at the outer level
+(see
 .B \[rs]O3
 and
 .BR \[rs]O4 ).
@@ -1047,21 +1048,21 @@ string is later interpolated.
 To be more precise,
 a \[lq]compatibility save\[rq] token is inserted at the beginning of the
 appended string
-.IR string,
+.IR string ,
 and a \[lq]compatibility restore\[rq] token at the end.
 .
 As a consequence,
 the requests
-.BR as ,
-.BR as1 ,
-.BR ds ,
+.BR .as ,
+.BR .as1 ,
+.BR .ds ,
 and
-.B ds1
+.B .ds1
 can be intermixed freely since the compatibility save/\:restore tokens
 only affect the (sub)strings defined by
-.B as1
+.B .as1
 and
-.BR ds1 .
+.BR .ds1 .
 .
 .
 .TP
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index ebdf223..c0ebcb5 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -31,9 +31,22 @@ groff_font \- format of groff device and font description 
files
 .SH Description
 .\" ====================================================================
 .
-The groff font format is roughly a superset of the ditroff
+.\" BEGIN Keep parallel with groff.texi node "Font Files".
+The
+.I groff
+font format is a rough superset of the AT&T
+device-independent
+.I troff
 font format.
 .
+In distinction to the AT&T implementation,
+.I groff
+lacks a binary format;
+all files are text files.
+(Plan\~9
+.I troff
+has also abandoned the binary format.}
+.
 The font files for device
 .I name
 are stored in a directory
@@ -660,6 +673,7 @@ the space between them should be increased by\~\c
 .
 Most entries in kernpairs section have a negative value for\~\c
 .IR n .
+.\" END Keep parallel with groff.texi node "Font Files".
 .
 .
 .\" ====================================================================
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 654de82..46d6bde 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -1844,9 +1844,10 @@ format.
 .SH Authors
 .\" ====================================================================
 .
-James Clark wrote an early version of this document, which described
-only the differences between
-.BR ditroff (@MAN7EXT@)'s
+James Clark wrote an early version of this document,
+which described only the differences between AT&T
+device-independent
+.IR troff 's
 output format and that of GNU
 .IR roff .
 .
diff --git a/man/roff.7.man b/man/roff.7.man
index 286805b..044986c 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -34,11 +34,11 @@ roff \- concepts and history of roff typesetting
 .I roff
 is the general name for a set of text formatting programs, known under
 names like
-.BR troff ,
-.BR nroff ,
-.BR ditroff ,
-.BR groff ,
-etc.
+.IR troff ,
+.IR nroff ,
+.IR ditroff ,
+.IR groff ,
+and so on.
 .
 A
 .I roff
@@ -321,16 +321,15 @@ This new
 version is the basis for all existing newer troff systems, including
 .IR groff .
 .
-On some systems, this
-.I device independent troff
-got a binary of its own, called
-.BR ditroff (@MAN7EXT@).
+On some systems,
+this device-independent
+.I troff
+got a binary of its own called
+.IR ditroff (@MAN7EXT@).
 .
 All modern
-.B troff
-programs already provide the full
-.B ditroff
-capabilities automatically.
+.I troff
+implementations provide device-indepenent functionality.
 .
 .
 .\" ====================================================================