[groff] 07/45: [docs]: Explain output comparison operator, redux.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit fbdfd92782d2a8ff7c74e624b1c3979516573fd0
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jan 14 12:44:02 2022 +1100

    [docs]: Explain output comparison operator, redux.
    
    * doc/groff.texi (Operators in Conditionals): Whack on it some more.
      - Explicitly name the output comparison operator and give it an entry
        in the concept index.
      - Tighten verbiage about delimited arguments; this is covered at
        length in an earlier node, already cross-referenced.
      - Motions do _not_ have to "exactly" match, but only insofar as the
        device is capable of distinguishing them: explain.
      - Explicitly identify "string comparison" as an application of \? with
        the output comparison operator.
      - Point out that while this sort of string comparison doesn't require
        valid groff syntax, the escape character still serves its _lexical_
        function.  (Blissfully, people looking for a string comparison
        operator are probably accustomed to the possibility of escape
        characters in comparands.)
      - Tighten wording about operator combinations, and refer to the `!`
        correctly as performing complementation, not negation.
      - Fix error: a leading complementation operator followed by spaces or
        tabs causes a condition to evaluate true, as shown in the subsequent
        example, not false.
    
    Port the foregoing discussion, minus examples, to groff(7).
---
 doc/groff.texi  | 64 +++++++++++++++++++++++-------------------
 man/groff.7.man | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 112 insertions(+), 39 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 0e7063cd..7717889a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -11833,13 +11833,13 @@ certain other @code{troff} 
implementations.@footnote{This refers to
 early-vintage @acronym{AT&T} @code{troff} to a form suitable for
 Versatec and Benson-Varian plotters.}
 
+@cindex output comparison operator
 @item @code{'}@var{xxx}@code{'}@var{yyy}@code{'}
 True if formatting the comparands @var{xxx} and @var{yyy} produces the
-same motions, glyphs, and output commands.  Other characters can be
-used in place of the single quotes; the same set of delimiters as for
-the @code{\D} escape is used (@pxref{Escape Sequences}).  GNU
-@code{troff} formats @var{xxx} and @var{yyy} in separate environments;
-after the comparison the resulting data are discarded.
+same output commands.  Other delimiters can be used in place of the
+neutral apostrophes (@pxref{Escape Sequences}).  This @dfn{output
+comparison operator} formats @var{xxx} and @var{yyy} in separate
+environments; after the comparison, the resulting data are discarded.
 
 @Example
 .ie "|"\fR|\fP" \
@@ -11856,20 +11856,23 @@ sequences used to obtain them.  In the previous 
example, @samp{|} and
 @samp{\fR|\fP} result in @samp{|} glyphs in the same typefaces at the
 same positions, so the comparands are equal.  If @samp{.ft@tie{}I} had
 been added before the @samp{.ie}, they would differ: the first @samp{|}
-would produce an italic @samp{|}, not a roman one.  By contrast, motions
-must @emph{exactly} match.  @samp{.if "\u\d""} is false even though both
-comparands result in zero net motion, because motions are not
-interpreted or optimized but sent as-is to the output.@footnote{Because
-formatting of the comparands takes place in a dummy environment,
-vertical motions within them cannot spring traps.} On the other hand,
-@samp{.if "\d"\v'0.5m'"} is true, because @code{\d} is defined as a
-downward motion of one-half em.@footnote{All of this is to say that the
-lists of output nodes created by formatting @var{xxx} and @var{yyy} must
-be identical.  @xref{Gtroff Internals}.}
+would produce an italic @samp{|}, not a roman one.  Motions must match
+in orientation and magnitude to within the applicable horizontal or
+vertical resolution of the device, after rounding.  @samp{.if
+"\u\d"\v'0'"} is false even though both comparands result in zero net
+motion, because motions are not interpreted or optimized but sent as-is
+to the output.@footnote{Because formatting of the comparands takes place
+in a dummy environment, vertical motions within them cannot spring
+traps.}  On the other hand, @samp{.if "\d"\v'0.5m'"} is true, because
+@code{\d} is defined as a downward motion of one-half em.@footnote{All
+of this is to say that the lists of output nodes created by formatting
+@var{xxx} and @var{yyy} must be identical.  @xref{Gtroff Internals}.}
 
 @cindex string comparison
 @cindex comparison of strings
-Surround the comparands with @code{\?} to avoid formatting them.
+Surround the comparands with @code{\?} to avoid formatting them; this
+causes them to be compared character by character, as with string
+comparisons in other programming languages.
 
 @Example
 .ie "\?|\?"\?\fR|\fP\?" \
@@ -11883,23 +11886,25 @@ false
 @cindex copy mode, and @code{\?}
 @cindex mode, copy, and @code{\?}
 @noindent
-Since comparands protected with @code{\?} are read in copy mode, it is
-not erroneous to use syntactically invalid input.
+Since comparands protected with @code{\?} are read in copy mode, they
+need not even be valid @code{groff} syntax.  The escape character is
+still lexically recognized, however, and consumes the next character.
 
 @Example
 .ds a \[
 .ds b \[
-.ie '\?\*a\?'\?\*b\?' \
-true
-.el \
-false
-    @result{} true
+.if '\?\*a\?'\?\*b\?' a and b true
+.if '\?\\?'\?\\?' backslash true \" doesn't work
+    @result{} a and b true
+@c slack lines for pagination control
+@c    @error{} warning: missing closing delimiter in
+@c    @error{} conditional expression (got newline)
 @endExample
 @end table
 
-The above operators can't be combined with others like @samp{:} or
-@samp{&}; only a leading @samp{!} (without spaces or tabs between the
-exclamation mark and the operator) can be used to negate the result.
+The above operators can't be combined with most others, but a leading
+@samp{!} (without spaces or tabs between the exclamation mark and the
+operator) can be used to complement the result.
 
 @Example
 .nr x 1
@@ -11909,9 +11914,10 @@ exclamation mark and the operator) can be used to 
negate the result.
 @endExample
 
 Spaces and tabs are optional immediately after the @samp{c}, @samp{d},
-@samp{F}, @samp{m}, @samp{r}, and @samp{S} operators, but immediately
-after @samp{!}, they cause the condition to evaluate false (this bizarre
-behavior maintains compatibility with @acronym{AT&T} @code{troff}).
+@samp{F}, @samp{m}, @samp{r}, and @samp{S} operators, but right after
+@samp{!}, they end the predicate and the conditional evaluates
+true.@footnote{This bizarre behavior maintains compatibility with
+@acronym{AT&T} @code{troff}.}
 
 @Example
 .nr x 1
diff --git a/man/groff.7.man b/man/groff.7.man
index e8863387..1c2e6586 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1242,6 +1242,8 @@ The truth values of other conditional expression 
operators are as shown
 below.
 .
 .
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Operators in
+.\" Conditionals".
 .P
 .ne 14v
 .TS
@@ -1326,12 +1328,74 @@ T}
 .
 .
 .P
-These operators can't be combined with others like
-.RB \[lq] : \[rq]
-or
-.RB \[lq] & \[rq];
-only a leading
-.RB \[lq] ! \[rq]\&
+The first of the above,
+the
+.I "output comparison operator,"
+interpolates a true value if formatting its comparands
+.I s1
+and
+.I s2
+produces the same output commands.
+.
+Other delimiters can be used in place of the neutral apostrophes.
+.
+.I \%@g@troff
+formats
+.I s1
+and
+.I s2
+in separate environments;
+after the comparison,
+the resulting data are discarded.
+.
+The resulting glyph properties,
+including font family,
+style,
+size,
+and
+slant,
+must match,
+but not necessarily the requests and/or escape sequences used to obtain
+them.
+.
+Motions must match in orientation and magnitude to within the applicable
+horizontal or vertical resolution of the device,
+after rounding.
+.
+.\" TODO: Uncomment and add forward reference when we add a "GNU troff
+.\" internals" subsection to this page.
+.\"(All of this is to say that the lists of output nodes created by
+.\"formatting
+.\".I s1
+.\"and
+.\".I s2
+.\"must be identical.)
+.
+.
+.P
+Surround the comparands with
+.B \[rs]?\&
+to avoid formatting them;
+this causes them to be compared character by character,
+as with string comparisons in other programming languages.
+.
+Since comparands protected with
+.B \[rs]?\&
+are read in copy mode,
+they need not even be valid
+.I groff
+syntax.
+.
+The escape character is still lexically recognized,
+however,
+and consumes the next character.
+.
+.
+.P
+The above operators can't be combined with most others,
+but a leading
+.RB \[lq] !\& \[rq]
+(without spaces or tabs between the exclamation mark and the operator)
 can be used to complement the result.
 .
 Spaces and tabs are optional immediately after the
@@ -1343,11 +1407,14 @@ Spaces and tabs are optional immediately after the
 and
 .RB \[lq] S \[rq]
 operators,
-but immediately after
+but right after
 .RB \[lq] ! \[rq],
-they cause the condition to evaluate false
-(this bizarre behavior maintains compatibility with AT&T
-.IR troff ).
+they end the predicate and the conditional evaluates true.
+.
+(This bizarre behavior maintains compatibility with AT&T
+.IR troff .)
+.\" END Keep (roughly) parallel with groff.texi node "Operators in
+.\" Conditionals".
 .
 .
 .\" ====================================================================