[bug #60836] Improve documentation of output-comparison operator

[G. Branden Robinson]

Follow-up Comment #10, bug #60836 (project groff):

Hi Dave,

I still wasn't happy with this.  The following commit is pending; please
let me know what you think.


$ git show --word-diff
commit 274038e9955a88a2e595c7133a050b99ef901a36 (HEAD -> master)
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Jan 14 12:44:02 2022 +1100

    [docs]: Explain output comparison operator, pt. 2.
    
    Whack on it some more.
    
    * 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.
    
    Port the foregoing discussion, minus examples, to groff(7).

diff --git a/doc/groff.texi b/doc/groff.texi
index 0e7063cde..9ec847d0a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -11835,11 +11835,10 @@ Versatec and Benson-Varian plotters.}

@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-]{+delimiters+} can be used in place of the
[-single quotes; the same set of delimiters as for-]
[-the @code{\D} escape is used-]{+neutral apostrophes+} (@pxref{Escape
Sequences}).  GNU @code{troff}
formats @var{xxx} and @var{yyy} in separate environments; after the
[-comparison-]{+comparison,+} the resulting data are discarded.

@Example
.ie "|"\fR|\fP" \
@@ -11856,20 +11855,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-]{+Motions+} must [-@emph{exactly} match.-]{+match+}
{+in orientation and magnitude to within the applicable horizontal or+}
{+vertical resolution of the device, after rounding.+}  @samp{.if
[-"\u\d""}-]{+"\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.-]{+them;
this+}
{+causes them to be compared character by character, as with string+}
{+comparisons in other programming languages.+}

@Example
.ie "\?|\?"\?\fR|\fP\?" \
@@ -11883,23 +11885,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-]{+they+}
{+need+} not [-erroneous to use syntactically invalid input.-]{+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-]{+.if+} '\?\*a\?'\?\*b\?' [-\-]{+a and b+} true
[-.el \-]
[-false-]{+.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-]{+most others, but+} a leading
@samp{!} (without spaces or tabs between the exclamation mark and the
operator) can be used to [-negate-]{+complement+} the result.

@Example
.nr x 1
diff --git a/man/groff.7.man b/man/groff.7.man
index e88633873..e11c2570e 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-]{+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 [-others like-]
[-.RB \[lq] : \[rq]-]
[-or-]
[-.RB \[lq] & \[rq];-]
[-only-]{+most others,+}
{+but+} a leading
.RB \[lq] [-! \[rq]\&-]{+!\& \[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
@@ -1348,6 +1412,8 @@ but immediately after
they cause the condition to evaluate false
(this bizarre behavior maintains compatibility with AT&T
.IR troff ).
{+.\" END Keep (roughly) parallel with groff.texi node "Operators in+}
{+.\" Conditionals".+}
.
.
.\" ====================================================================



    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?60836>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/