[groff] 01/09: documentation: Re-christen 'ESCAPE_AMPERSAND'.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 36b5c8852af098e6f06dbe2ab8e452a45b43d315
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 15 22:08:01 2020 +1000

    documentation: Re-christen 'ESCAPE_AMPERSAND'.
    
    Recent discussions on the groff mailing list and in the Savannah bug
    tracker have made me realize that our terminology for this escape
    sequence is poor.  Rename it consistently to give users a more precise
    idea of its function.
    
    s/zero[- ]width space character/non-printing input break/
    
    Justification:
    
    First, the case for the prosecution:
    
    * Can something that does not print have a width?  Note that elewhere,
      in documentation of \z, things that do print are also described as
      having zero width, probably for mnemonic purposes ("z").
      "Non-advancing" might be a better term there.  In any case, the
      "width" of this escape is not a salient feature.
    * It is hard to argue that it is a "space".  It differs from space
      behavior in both input and output.  A major use of it is in fact to
      _cancel_ the effect of nearby space, as in suppressing end-of-sentence
      detection, so it is more like an anti-space in that regard.  It is
      therefore not like a space on input, and not like one on output
      either; it does not change the printing position, and there is nothing
      to break or not break when filling.
    * It is also hard to argue that it is a character.  It certainly an
      escape; it produces neither a space node nor a glyph node internally.
      Do we call \R or \s "characters"?  No, they simply change the state of
      the engine in different ways, as does \&.
    
    Now, the case for the defense (of my replacement wording):
    
    * Everybody agrees that whatever this is, it doesn't print.  Say that.
    * Nothing about the harmlessness of this escape sequence to output that
      is suggestion by "zero-width" is not implied even more strongly by
      "non-printing".
    * As noted in the final point in the previous section, the purpose of
      this escape is to change the state of the parser.  It produces nothing
      on its own; it simply moves the interpreting automaton to a different
      region of its semantic space.  Like a function that takes void and
      returns void, you invoke it _only_ for its side effects.
    * Consequently it acts like a jump, branch, or "break" in the
      interpreter of input.  The first two are too comp sci for the general
      reader.  The last can be usefully understood by the reader by analogy
      to the other types of "break" in groff; the usual course of events is
      being interrupted.  To avoid confusion, I advocate being scrupulous
      about including the word "input" before "break".
    
    * doc/groff.texi (Requests): Rename.  Update conceptual index entries;
      retain old name (with an appended "[sic]") to aid readers accustomed
      to it.
      (Ligatures and kerning): Update conceptual index entries.  Supply
      context ("effect on kerning").
      (Drawing requests): Update conceptual index entries.  Supply context
      ("effect on '\l'").
    
    * man/groff.7.man (Description): Rename in macro-advice-writing
      shorthand.
      (Escape Sequences/Escape short reference): Rename.  Also hyphenate
      attribute phrase "zero-width" in descriptions of \| and \^.  Also
      update possibly miseadling source comment.
    * tmac/groff_man.7.man.in (Description/Command synopsis macros [style]:
      Rename.
      (Description/Portability) [style]: Rename.
    * tmac/groff_mdoc.7.man (TROFF IDIOSYNCRASIES/Macro Usage): Rename.
      (TROFF IDIOSYNCRASIES/Other Possible Pitfalls): Rename.
---
 ChangeLog               | 23 +++++++++++++++++++++++
 doc/groff.texi          | 31 +++++++++++++++++--------------
 man/groff.7.man         | 14 +++++++++-----
 tmac/groff_man.7.man.in |  4 ++--
 tmac/groff_mdoc.7.man   |  8 ++++----
 5 files changed, 55 insertions(+), 25 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index cafaa20..4feca13 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,26 @@
+2020-08-15  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       documentation: Re-christen 'ESCAPE_AMPERSAND'.
+
+       s/zero[- ]width space character/non-printing input break/
+
+       * doc/groff.texi (Requests): Rename.  Update conceptual index
+       entries; retain old name (with an appended "[sic]") to aid
+       readers accustomed to it.
+       (Ligatures and kerning): Update conceptual index entries.
+       Supply context ("effect on kerning").
+       (Drawing requests): Update conceptual index entries.  Supply
+       context ("effect on '\l'").
+       * man/groff.7.man (Description): Rename in macro-advice-writing
+       shorthand.
+       (Escape Sequences/Escape short reference): Rename.
+       * tmac/groff_man.7.man.in (Description/Command synopsis macros
+       [style]: Rename.
+       (Description/Portability) [style]: Rename.
+       * tmac/groff_mdoc.7.man (TROFF IDIOSYNCRASIES/Macro Usage):
+       Rename.
+       (TROFF IDIOSYNCRASIES/Other Possible Pitfalls): Rename.
+
 2020-08-14  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/groff_man.7.man.in (Description/{Document structure
diff --git a/doc/groff.texi b/doc/groff.texi
index 948658b..1cb776c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -5141,13 +5141,16 @@ assigning an empty macro to it.
 
 @xref{Blank Line Traps}.
 
-@cindex zero width space character (@code{\&})
-@cindex character, zero width space (@code{\&})
-@cindex space character, zero width (@code{\&})
+@cindex non-printing input break (@code{\&})
+@cindex input break, non-printing (@code{\&})
+@cindex break, non-printing input (@code{\&})
+@cindex zero-width space character (@emph{sic}) (@code{\&})
+@cindex character, zero-width space (@emph{sic}) (@code{\&})
+@cindex space character, zero-width (@emph{sic}) (@code{\&})
 @cindex @code{\&}, escaping control characters
 To begin a line with a control character without it being interpreted,
-precede it with @code{\&}.  This represents a zero width space, which
-means it does not affect the output.
+precede it with @code{\&}.  This represents a non-printing input break,
+which means it does not affect the output.
 
 In most cases the period is used as a control character.  Several
 requests cause a break implicitly; using the single quote control
@@ -7823,7 +7826,7 @@ set with the @code{shc} request.
 @item
 @cindex @code{\&}, and translations
 The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c}
-followed by the zero width space character) maps this character to
+followed by the non-printing input break) maps this character to
 nothing.
 
 @Example
@@ -9897,9 +9900,9 @@ enable pairwise kerning, otherwise disable it.  The 
read-only number
 register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
 0@tie{}otherwise.
 
-@cindex zero width space character (@code{\&})
-@cindex character, zero width space (@code{\&})
-@cindex space character, zero width (@code{\&})
+@cindex non-printing input break (@code{\&}), effect on kerning
+@cindex input break, non-printing (@code{\&}), effect on kerning
+@cindex break, non-printing input (@code{\&}), effect on kerning
 If the font description file contains pairwise kerning information,
 glyphs from that font are kerned.  Kerning between two glyphs can be
 inhibited by placing @code{\&} between them: @samp{V\&A}.
@@ -9995,8 +9998,8 @@ q\,\f[I]f
 @endDefesc
 
 @Defesc {\\&, , , }
-Insert a zero-width character, which is invisible.  Its intended use is
-to stop interaction of a character with its surroundings.
+Insert a non-printing input break, which is invisible.  Its intended use
+is to stop interaction of a character with its surroundings.
 
 @itemize @bullet
 @item
@@ -11930,9 +11933,9 @@ The optional second parameter@tie{}@var{g} is a glyph 
to draw the line
 with.  If this second argument is not specified, @code{gtroff} uses the
 underscore glyph, @code{\[ru]}.
 
-@cindex zero width space character (@code{\&})
-@cindex character, zero width space (@code{\&})
-@cindex space character, zero width (@code{\&})
+@cindex non-printing input break (@code{\&}), effect on @code{\l} escape
+@cindex input break, non-printing (@code{\&}), effect on @code{\l} escape
+@cindex break, non-printing input (@code{\&}), effect on @code{\l} escape
 To separate the two arguments (to prevent @code{gtroff} from
 interpreting a drawing glyph as a scaling indicator if the glyph is
 represented by a single character) use @code{\&}.
diff --git a/man/groff.7.man b/man/groff.7.man
index cb61ea8..92293d4 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -353,7 +353,7 @@ or
 .IP 2.
 Double all backslashes.
 .IP 3.
-Begin all text lines with the special non-spacing character
+Begin all text lines with the non-printing input break
 .esc & .
 .
 .
@@ -3068,7 +3068,7 @@ and
 .esc ? .
 .
 .
-.\" ========= spacing =========
+.\" ========= spacing [sic; \& and \) don't really space] =========
 .
 .TP
 .ESC \& space
@@ -3080,15 +3080,19 @@ Digit-width unbreakable space.
 .
 .TP
 .ESC |
-1/6\ em narrow unbreakable space glyph; zero width in nroff.
+1/6\ em narrow unbreakable space glyph;
+zero-width in
+.IR nroff .
 .
 .TP
 .ESC \[ha]
-1/12\ em half-narrow unbreakable space glyph; zero width in nroff.
+1/12\ em half-narrow unbreakable space glyph;
+zero-width in
+.IR nroff .
 .
 .TP
 .ESC &
-Non-printable, zero-width glyph.
+Non-printing input break.
 .
 .TP
 .ESC )
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 94a42dc..f91d600 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1066,7 +1066,7 @@ repeated arbitrarily.
 .
 .
 .IP
-Authors of man pages should note the use of the zero-width space
+Authors of man pages should note the use of the non-printing input break
 escape sequence
 .B \e&
 preceding the ellipsis,
@@ -2171,7 +2171,7 @@ CSTR\e\(ti#8 documents the B\e\(tilanguage.
 .
 .TP
 .B \e&
-Non-printing character.
+Non-printing input break.
 .
 Insert at the beginning of an input line to prevent a dot or apostrophe
 from being interpreted as the beginning of a
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 6aec5a1..e9b5d9e 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -283,8 +283,8 @@ a macro invocation, precede the
 .Ql .\&
 (dot) with the
 .Ql \e&
-escape sequence which translates literally to a zero-width space, and is
-never displayed in the output.
+escape sequence which causes a non-printing input break, and is never
+displayed in the output.
 .Pp
 In general,
 .Tn GNU
@@ -543,8 +543,8 @@ handles punctuation characters specially in macro arguments.
 This will be explained in section
 .Sx General Syntax
 below.
-In the same way, you have to protect trailing full stops of abbreviations
-with a trailing zero-width space:
+In the same way, you have to protect trailing full stops of
+abbreviations with a trailing non-printing input break:
 .Ql e.g.\e& .
 .Pp
 A comment in the source file of a man page can be either started with