[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/09: documentation: Re-christen 'ESCAPE_AMPERSAND'.
From: |
G. Branden Robinson |
Subject: |
[groff] 01/09: documentation: Re-christen 'ESCAPE_AMPERSAND'. |
Date: |
Sat, 15 Aug 2020 13:15:52 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/09: documentation: Re-christen 'ESCAPE_AMPERSAND'.,
G. Branden Robinson <=