[groff] 07/07: [docs]: Fix Savannah #68216.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0a90a2cef530b662b25ea5da23617380dcd3607e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Feb 12 14:10:59 2023 -0600

    [docs]: Fix Savannah #68216.
    
    [docs]: Re-re-christen 'ESCAPE_AMPERSAND' ('\&').  Now call it a
    (non-transparent) "dummy character".  Also rechristen
    'ESCAPE_RIGHT_PARENTHESIS', ('\)') as the "transparent dummy character";
    it has no impact on sentence-ending detection.
    
    * doc/groff.texi:
    * doc/meref.me.in:
    * man/groff.7.man:
    * man/groff_diff.7.man:
    * man/roff.7.man:
    * src/preproc/refer/refer.1.man:
    * tmac/groff_man.7.man.in: Do it.
    
    Fixes <https://savannah.gnu.org/bugs/?62816>.  Thanks to Dave Kemper for
    the report and to the groff mailing list for the vigorous discussion.  I
    don't expect my solution to please everyone.
    
    Also update references to the \& escape sequence in comments.
    
    ANNOUNCE: Update bug counts.
---
 ANNOUNCE                      |   6 +-
 ChangeLog                     |  28 +++++++--
 doc/groff.texi                | 135 ++++++++++++++++++++++++++++--------------
 doc/meref.me.in               |   2 +-
 man/groff.7.man               |  49 ++++++++++++++-
 man/groff_diff.7.man          |  28 ++++++---
 man/roff.7.man                |   6 +-
 src/preproc/refer/refer.1.man |   2 +-
 tmac/an.tmac                  |  10 ++--
 tmac/groff_man.7.man.in       |  17 +++---
 10 files changed, 202 insertions(+), 81 deletions(-)

diff --git a/ANNOUNCE b/ANNOUNCE
index ed6e4fe8a..92193afa5 100644
--- a/ANNOUNCE
+++ b/ANNOUNCE
@@ -58,7 +58,7 @@ release shipped with three automated unit tests; this one 
ships with
 over 160 unit and regression tests.
 
 As of this writing, per the GNU Savannah bug tracker, the groff project
-has resolved 413 problems as fixed for the 1.23.0 release.  Some of the
+has resolved 414 problems as fixed for the 1.23.0 release.  Some of the
 bugs we've corrected were over 30 years old.
 
 Classifying these issues by type and the component of the project to
@@ -66,9 +66,9 @@ which they apply, we find the following.
 
   Type                              Component
   ----                              ---------
-  Build/installation           38   Core                           94
+  Build/installation           38   Core                           95
   Crash/unresponsive           11   Driver: grohtml                 7
-  Documentation                99   Driver: gropdf                  9
+  Documentation               100   Driver: gropdf                  9
   Feature change               40   Driver: grops                   2
   Incorrect behavior          129   Driver: grotty                  4
   Lint                         15   Driver: others/general          8
diff --git a/ChangeLog b/ChangeLog
index 9ed3f2813..d1dbe2895 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,23 @@
+2023-02-12  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [docs]: Re-re-christen 'ESCAPE_AMPERSAND' ('\&').  Now call it a
+       {non-transparent} "dummy character".  Also rechristen
+       'ESCAPE_RIGHT_PARENTHESIS', ('\)') as the "transparent dummy
+       character"; it has no impact on sentence-ending detection.
+
+       * doc/groff.texi:
+       * doc/meref.me.in:
+       * man/groff.7.man:
+       * man/groff_diff.7.man:
+       * man/roff.7.man:
+       * src/preproc/refer/refer.1.man:
+       * tmac/groff_man.7.man.in: Do it.
+
+       Fixes <https://savannah.gnu.org/bugs/?62816>.  Thanks to Dave
+       Kemper to the report and to the groff mailing list for the
+       vigorous discussion.  I don't expect my solution to please
+       everyone.
+
 2023-02-11  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/an.tmac: Add internal register `an*MR-URL-format` to
@@ -13971,7 +13991,7 @@
        structural differences to the reader's burden.  Make their
        implementations rigidly parallel.  Update comments.
        (RI, IR, IB, BI, RB, BR): Always define the `an-result` string
-       as empty except for a non-printing input break for the sake of
+       as empty except for a dummy character '\&' for the sake of
        compatibility mode.
        (RI, IR, IB, BI): Defer interpolation of the first argument to
        the while loop if there are at least two (like the existing RB,
@@ -16419,9 +16439,9 @@
 
        * tmac/tty.tmac: Define fallback glyphs for Bell System logo
        {non-breaking adjustable space} and radical extension and square
-       root extension (both non-printing input breaks) to suppress
-       warnings from groff_char(7).  As none of these are encoded in
-       Unicode it seems unlikely they will become supported soon.
+       root extension (both dummy characters '\&') to suppress warnings
+       from groff_char(7).  As none of these are encoded in Unicode it
+       seems unlikely they will become supported soon.
 
 2020-08-30  G. Branden Robinson <g.branden.robinson@gmail.com>
 
diff --git a/doc/groff.texi b/doc/groff.texi
index 589bd2bd3..7640e55aa 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -468,7 +468,7 @@ developing GNU and promoting software freedom.''
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0
-@subtitle January 2023
+@subtitle February 2023
 @author Trent@tie{}A.@: Fisher
 @author Werner Lemberg
 @author G.@tie{}Branden Robinson
@@ -2604,7 +2604,7 @@ character
 Interpolate glyph of special character named @var{char}.
 
 @item \&
-non-printing, zero-width dummy character
+dummy character
 
 @item \~
 Insert an unbreakble space that is adjustable like a normal space.
@@ -5049,8 +5049,8 @@ by default, an uncommon character in natural language 
text, and is
 ``sequence''.
 
 @cindex @code{\&}, at end of sentence
-The non-printing input break escape sequence @code{\&} can be used after
-an end-of-sentence character to defeat end-of-sentence detection on a
+The dummy character escape sequence @code{\&} can be used after an
+end-of-sentence character to defeat end-of-sentence detection on a
 per-instance basis.  We can therefore rewrite our input more
 defensively.
 
@@ -5281,13 +5281,12 @@ counterpart, the @dfn{no-break control character}, a 
neutral apostrophe
 (@code{'}), suppresses the break that is implied by some requests.
 These characters were chosen because it is uncommon for lines of text in
 natural languages to begin with them.
-@cindex non-printing input break (@code{\&})
-@cindex input break, non-printing (@code{\&})
-@cindex break, non-printing input (@code{\&})
+@cindex dummy character (@code{\&}), as control character suppressor
+@cindex character, dummy (@code{\&}), as control character suppressor
 If you require a formatted period or apostrophe (closing single
 quotation mark) where GNU @code{troff} is expecting a control character,
-prefix the dot or neutral apostrophe with the non-printing input break
-escape sequence, @samp{\&}.
+prefix the dot or neutral apostrophe with the dummy character escape
+sequence, @samp{\&}.
 
 @cindex control line
 An input line beginning with a control character is called a
@@ -9356,9 +9355,8 @@ 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 non-printing input break) maps this character to
-nothing.
+The pair @samp{@var{c}\&} (an arbitrary character@tie{}@var{c} followed
+by the dummy character) maps this character to nothing.
 
 @Example
 .tr a\&
@@ -10124,6 +10122,7 @@ special symbols (Greek, mathematics).
 * Special Fonts::
 * Artificial Fonts::
 * Ligatures and Kerning::
+* Dummy Characters::
 @end menu
 
 @c ---------------------------------------------------------------------
@@ -11404,7 +11403,7 @@ an integer.
 
 @c ---------------------------------------------------------------------
 
-@node Ligatures and Kerning,  , Artificial Fonts, Fonts and Symbols
+@node Ligatures and Kerning, Dummy Characters, Artificial Fonts, Fonts and 
Symbols
 @subsection Ligatures and Kerning
 @cindex ligatures and kerning
 @cindex kerning and ligatures
@@ -11460,9 +11459,8 @@ enable pairwise kerning, otherwise disable it.  The 
read-only register
 @code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
 0@tie{}otherwise.
 
-@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
+@cindex dummy character (@code{\&}), effect on kerning
+@cindex character, dummy (@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}.
@@ -11534,14 +11532,36 @@ ugly.  Use this escape sequence whenever an upright 
glyph is followed
 immediately by an oblique glyph without any intervening space.
 @endDefesc
 
+@c TODO: Move this node earlier in the text due to dummy characters'
+@c multifarious effects.
+@node Dummy Characters,  , Ligatures and Kerning, Fonts and Symbols
+@subsection Dummy Characters
+
+As discussed in @ref{Requests and Macros}, the first character on an
+input line is treated specially.  Further, formatting a glyph has many
+consequences on formatter state (@pxref{Environments}).  Occasionally,
+we want to escape this context or embrace some of those consequences
+without actually rendering a glyph to the output.
+
 @Defesc {\\&, , , }
-Insert a non-printing input break, which is invisible.  Its intended use
-is to stop interaction of a character with its surroundings.
+@cindex dummy character (@code{\&})
+@cindex character, dummy (@code{\&})
+Interpolate a dummy character, which is constitutive of output but
+invisible.@footnote{Opinions of this escape sequence's name abound.
+``Zero-width space'' is a popular misnomer:@: @code{roff} formatters do
+not treat it like a space.  Ossanna called it a ``non-printing,
+zero-width character'', but the character causes @emph{output} even
+though it does not ``print''.  If no output line is pending, the dummy
+character starts one.  Contrast an empty input document with one
+containing only @code{\&} (and a newline).  The former produces no
+output; the latter, a blank page.}  Its presence alters the
+interpretation context of a subsequent input character, and enjoys
+several applications.
 
 @itemize @bullet
 @item
-It prevents the insertion of extra space after an end-of-sentence
-character.
+It prevents insertion of extra space after an end-of-sentence character
+(@pxref{Sentences}).
 
 @Example
 Test.
@@ -11579,34 +11599,58 @@ V\&A
 @end iftex
 
 @item
-It is needed to map an arbitrary character to nothing in the @code{tr}
-request (@pxref{Character Translations}).
+It permits the @code{tr} request to remap a character to nothing
+(@pxref{Character Translations}).
 @end itemize
-@endDefesc
-
-@Defesc {\\), , , }
-This escape is similar to @code{\&} except that it behaves like a
-character declared with the @code{cflags} request to be transparent for
-the purposes of an end-of-sentence character.
 
-Its main usage is in macro definitions to protect against arguments
-starting with a control character.
+The dummy character escape sequence sees use in macro definitions as a
+means of ensuring that arguments are treated as text even if they begin
+with spaces or control characters.
 
 @Example
-.de xxx
-\)\\$1
+.de HD \" typeset a simple bold heading
+.  sp
+.  ft B
+\&\\$1 \" exercise: remove the \&
+.  ft
+.  sp
 ..
-.de yyy
-\&\\$1
+.HD .\|.\|.\|surprised?
+@endExample
+@endDefesc
+
+One way to think about the dummy character is to imagine placing the
+symbol @samp{&} in the input at a certain location; if doing so has all
+the side effects on formatting that you desire except for sticking an
+ugly ampersand in the midst of your text, the dummy character is what
+you want in its place.
+
+@Defesc {\\), , , }
+@cindex transparent dummy character (@code{\)})
+@cindex character, transparent dummy (@code{\)})
+@cindex dummy character, transparent (@code{\)})
+Interpolate a @slanted{transparent} dummy character---one that is
+transparent to end-of-sentence detection.  It behaves as @code{\&},
+except that @code{\&} is treated as letters and numerals normally are
+after @samp{.}, @samp{?} and @samp{!}; @code{\&} cancels end-of-sentence
+detection, and @code{\)} does not.
+@c This feature seems too weak to me; see Savannah #60571.  -- GBR
+
+@Example
+.de Suffix-&
+.  nop \&\\$1
 ..
-This is a test.\c
-.xxx '
-This is a test.
-    @result{}This is a test.'  This is a test.
-This is a test.\c
-.yyy '
-This is a test.
-    @result{}This is a test.' This is a test.
+.
+.de Suffix-)
+.  nop \)\\$1
+..
+.
+Here's a sentence.\c
+.Suffix-& '
+Another one.\c
+.Suffix-) '
+And a third.
+    @result{} Here's a sentence.' Another one.'  And a third.
 @endExample
 @endDefesc
 
@@ -13870,9 +13914,8 @@ The optional second parameter@tie{}@var{c} is a glyph 
to draw the line
 with.  If this second argument is not specified, @code{gtroff} uses the
 underscore glyph, @code{\[ru]}.
 
-@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
+@cindex dummy character (@code{\&}), effect on @code{\l} escape
+@cindex character, dummy (@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{\&}.
@@ -14725,7 +14768,7 @@ and no motion is produced before calling @var{name}.
 @c the leading space macro sees only @samp{foo} without the preceding
 @c @samp{\fI}.  If the macro should see the font escape, you have to
 @c ``protect'' it with something that creates a token, like the
-@c non-printing input break; for example, @samp{\&\fIfoo}.
+@c dummy character; for example, @samp{\&\fIfoo}.
 @endDefreq
 
 @c ---------------------------------------------------------------------
diff --git a/doc/meref.me.in b/doc/meref.me.in
index bff0d964b..81cc8f978 100644
--- a/doc/meref.me.in
+++ b/doc/meref.me.in
@@ -2210,7 +2210,7 @@ and a square \(sq labels \*G extensions.
 \&.$s  M\(dd   output footnote area separator
 \e%    F\(sc   control hyphenation
 \en%   R\(sc   current page number
-\e&    F\(sc   non-printing input break
+\e&    F\(sc   dummy character
 \e(\fI\,xx\fP  F\(sc   interpolate special character \fIxx\fP
 \&.(b  M       begin block
 \&.(c  M       begin centered block
diff --git a/man/groff.7.man b/man/groff.7.man
index bfa93f94e..66ca0089a 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1860,6 +1860,49 @@ See section \[lq]Implementation differences\[rq] in
 .
 .
 .\" ====================================================================
+.SH "Dummy characters"
+.\" ====================================================================
+.
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Dummy
+.\" Characters".
+As discussed in
+.MR roff @MAN7EXT@ ,
+the first character on an input line is treated specially.
+.
+Further,
+formatting a glyph has many
+consequences on formatter state
+(see section \[lq]Environments\[rq] below).
+.
+Occasionally,
+we want to escape this context or embrace some of those consequences
+without actually rendering a glyph to the output.
+.
+.B \[rs]&
+interpolates a dummy character,
+which is constitutive of output but invisible.
+.
+Its presence alters the interpretation context of a subsequent input
+character,
+and enjoys several applications:
+preventing the insertion of extra space after an end-of-sentence
+character,
+preventing interpretation of a control character at the beginning of an
+input line,
+preventing kerning between two glyphs,
+and permitting the
+.B tr
+request to remap a character to nothing.
+.
+.B \[rs])
+works as
+.B \[rs]&
+does,
+except that it does not cancel a pending end-of-sentence state.
+.\" END Keep (roughly) parallel with groff.texi node "Dummy Characters".
+.
+.
+.\" ====================================================================
 .SH "Control structures"
 .\" ====================================================================
 .
@@ -4515,13 +4558,13 @@ Move one-twelfth em to the right on typesetters.
 .
 .TP
 .ESC &
-Non-printing input break.
+Interpolate a dummy character.
 .
 .
 .TP
 .ESC )
-Non-printing input break,
-transparent to end-of-sentence recognition.
+Interpolate a dummy character that is transparent to end-of-sentence
+recognition.
 .
 .
 .TP
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 4ba065061..6f81cd9fe 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -975,14 +975,29 @@ argument to the
 .B ds
 request.
 .
+.
 .TP
 .B \[rs])
-Like
+Interpolate a
+.I transparent
+dummy character\[em]one that is transparent to end-of-sentence
+detection.
+.
+It behaves as
+.BR \[rs]& ,
+except that
 .B \[rs]&
-except that it behaves like a character declared with the
-.B .cflags
-request to be transparent for the purposes of end-of-sentence
-recognition.
+is treated as letters and numerals normally are after
+\[lq].\[rq],
+\[lq]?\[rq],
+and
+\[lq]!\[rq];
+.B \[rs]&
+cancels end-of-sentence detection,
+and
+.B \[rs])
+does not.
+.
 .
 .TP
 .BI \[rs]*[ "xxx arg1 arg2\~"\c
@@ -4442,8 +4457,7 @@ is
 If the font description file contains pairwise kerning information,
 glyphs from that font are kerned.
 .
-Kerning between two glyphs can be inhibited by placing a non-printing
-input break
+Kerning between two glyphs can be inhibited by placing a dummy character
 .B \[rs]&
 between them.
 .
diff --git a/man/roff.7.man b/man/roff.7.man
index e55f2dcdc..80831970b 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -183,7 +183,7 @@ or one of them is followed by two spaces on the same input 
line,
 it appends an inter-word space
 followed by an inter-sentence space in the formatted output.
 .
-The non-printing input break escape sequence
+The dummy character escape sequence
 .B \[rs]&
 can be used after an end-of-sentence character to defeat end-of-sentence
 detection on a per-instance basis.
@@ -411,8 +411,8 @@ If you require a formatted period or apostrophe
 where
 .\" GNU @code{troff}
 the formatter is expecting a control character,
-prefix the dot or neutral apostrophe with the non-printing input break
-escape sequence,
+prefix the dot or neutral apostrophe with the dummy character escape
+sequence,
 .RB \[lq] \[rs]& \[rq].
 .
 .
diff --git a/src/preproc/refer/refer.1.man b/src/preproc/refer/refer.1.man
index 0b80f0a84..93f634c02 100644
--- a/src/preproc/refer/refer.1.man
+++ b/src/preproc/refer/refer.1.man
@@ -668,7 +668,7 @@ or the second citation's
 is non-empty.
 .
 (If you wish to prevent this,
-use the non-printing input break escape sequence
+use the dummy character escape sequence
 .B \[rs]&
 as the first citation's
 .IR closing-text .)
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 7ab3ccae1..d67db938e 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -819,11 +819,11 @@ contains unsupported escape sequence
 .\"
 .\" Implementation notes:
 .\"
-.\" We always emit a non-printing input break \& before the first
-.\" argument.  This is necessary only when the calling man page is in
-.\" compatibility mode; it works around the surprising AT&T semantics of
-.\" \f escapes at the beginning of an input line.  See "Implementation
-.\" differences" in groff_diff(7) or the groff Texinfo manual.
+.\" We always emit a dummy character \& before the first argument.  This
+.\" is necessary only when the calling man page is in compatibility
+.\" mode; it works around the surprising AT&T semantics of \f escapes at
+.\" the beginning of an input line.  See "Implementation differences" in
+.\" groff_diff(7) or the groff Texinfo manual.
 .\"
 .\" The italic correction escapes can be visually confusing.  We apply
 .\" the following rules, always on the same input line.
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 4b10d3282..971a1c609 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -696,7 +696,7 @@ or
 .B ?\&
 followed by multiple spaces can change.
 .
-Use the non-printing input break escape sequence
+Use the dummy character escape sequence
 .B \(rs&
 before the spaces.
 .
@@ -1222,7 +1222,7 @@ see subsection \(lqPortability\(rq below.
 .
 .
 .IP \(bu
-The non-printing input break escape sequence
+The dummy character escape sequence
 .B \e&
 follows the ellipsis when further text will follow after space on the
 output line,
@@ -2534,7 +2534,7 @@ or Documenter's Workbench
 .
 .TP
 .B \e&
-Non-printing input break.
+Dummy character.
 .
 Insert at the beginning of an input line to prevent a dot or apostrophe
 from being interpreted as the beginning of a
@@ -4055,7 +4055,7 @@ Since dots both begin control lines and are candidate 
end-of-sentence
 characters,
 however,
 it is sometimes necessary to prefix and/or suffix an ellipsis with the
-non-printing input break escape sequence
+dummy character escape sequence
 .BR \[rs]& .
 .
 That fact stands even if a string is defined to contain the sequence;
@@ -4071,9 +4071,9 @@ but not always.)
 A hypothetical string
 .B EL
 that contained an ellipsis,
-but not the trailing input break,
-would then need to be suffixed with
-.B \[rs]&
+but not the trailing dummy character
+.BR \[rs]& ,
+would then need to be suffixed with the latter
 when not ending a sentence.
 .
 .
@@ -4119,7 +4119,8 @@ In syntax synopses,
 missing ellipses can cause great confusion.
 .
 Dots and space are universally supported.
-.\" XXX: Does an unconditional _preceding_ input break cause problems?
+.\" XXX: Does an unconditional _preceding_ dummy character cause
+.\" problems?
 _endif()dnl
 .
 .