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 <[email protected]> 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/
