bugGNU roff - Bugs: bug #60836, Improve documentation of...

 
 

bug #60836: Improve documentation of output-comparison operator

Submitter:  Dave <barx>
Submitted:  Sun 27 Jun 2021 12:11:43 PM UTC
   
 
Category:  Core Severity:  2 - Minor
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Thu 16 Jun 2022 03:37:44 AM UTC, comment #13: 

comment #12:

> Can you open a new ticket for this quibble?


Bug #62638

Dave <barx>
Group Member
Wed 15 Jun 2022 05:41:41 AM UTC, comment #12: 


comment #11:

> comment #10:
> > The following commit is pending; please let me know what you think.
>
> Er, I failed to do that before this went to press (as commit fbdfd927), but I think it's a great set of refinements and clarifications.


Thank you!

> If I had to quibble, I'd wonder whether, in a coding rather than a typesetting context, "neutral apostrophes" is a better descriptor than "single quotes."  Programmers are certainly more used to calling them single quotes; and even to noncoders, either term should be understandable.  Also, as delimiters for strings, they function semantically more as quotes than as apostrophes.  At this point in the manual, there shouldn't be reason to worry that users might interpret "single quotes" as U+2018 and U+2019, since it has previously established that groff code is limited to Latin-1.


Can you open a new ticket for this quibble?

One of the reasons I'm so wedded to the term "neutral apostrophe" is that I can use it unambiguously in any context.  Input, output, character, glyph, prose, program, whatever--it always means U+0027.

If I say "single quotes", I have to worry about context, because there are at least three--the ones we've identified, and possibly others.

If there is still a significant risk of confusion, I would prefer to add a statement in the "Conventions Used in This Manual" node of our Texinfo manual to rationalize this usage.

G. Branden Robinson <gbranden>
Group administrator
Sat 19 Mar 2022 05:32:42 PM UTC, comment #11: 

comment #10:

> The following commit is pending; please let me know what you think.


Er, I failed to do that before this went to press (as commit fbdfd927), but I think it's a great set of refinements and clarifications.

If I had to quibble, I'd wonder whether, in a coding rather than a typesetting context, "neutral apostrophes" is a better descriptor than "single quotes."  Programmers are certainly more used to calling them single quotes; and even to noncoders, either term should be understandable.  Also, as delimiters for strings, they function semantically more as quotes than as apostrophes.  At this point in the manual, there shouldn't be reason to worry that users might interpret "single quotes" as U+2018 and U+2019, since it has previously established that groff code is limited to Latin-1.

Dave <barx>
Group Member
Fri 14 Jan 2022 01:54:52 AM UTC, comment #10: 

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".+}
.
.
.\" ====================================================================


G. Branden Robinson <gbranden>
Group administrator
Tue 11 Jan 2022 11:36:53 AM UTC, comment #9: 


commit ed619aae324024ecbc2c2e4e05eff1f05eeb71ac
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Jan 10 03:21:32 2022 +1100

    doc/groff.texi: Update explanation of operator.

    * doc/groff.texi (Operators in Conditionals): Update explanation of
      output-comparison conditional operator.

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


G. Branden Robinson <gbranden>
Group administrator
Sun 10 Oct 2021 04:04:58 AM UTC, comment #8: 

(This bug was put into "Need info" along with the questions posed in comment #4.  These questions have been resolved, so I presume "Need info" is no longer the current status.  If info is still being awaited, feel free to overrule my status change.)

Dave <barx>
Group Member
Mon 23 Aug 2021 01:16:03 PM UTC, comment #7: 

Updating Summary to reflect that this is a problem in the documentation, not the behavior.

Dave <barx>
Group Member
Sat 10 Jul 2021 08:55:29 AM UTC, comment #6: 


comment #5:

> I think the text I added misrepresents CSTR #54 taken as a whole.  What do you think?  If a revert happens, I am unconcerned with who is credited.


Yeah, I have to agree.  I think it would be good to call out the "identical motions" requirement explicitly, possibly including examples.

I did go ahead and do the reversion, and pushed it.

G. Branden Robinson <gbranden>
Group administrator
Fri 09 Jul 2021 07:24:04 AM UTC, comment #5: 

I think the text I added misrepresents CSTR #54 taken as a whole.  What do you think?  If a revert happens, I am unconcerned with who is credited.

Dave <barx>
Group Member
Fri 09 Jul 2021 05:07:27 AM UTC, comment #4: 

Hi Dave,

Well, shoot.  I already pushed this:


commit 22538f26b866797f5d4c462286ca0d7028a019bf (origin/master, origin/HEAD)
Author: Dave Kemper <saint.snit@gmail.com>
Date:   Sun Jun 27 12:11:43 2021 +0000

    doc/groff.texi: Document CSTR #54 erratum.

    * doc/groff.texi (Operators in Conditionals): Document CSTR #54 erratum
      regarding output-equivalence conditional operator [that is:
        .if '\\$1'arg'
      "oh yeah, THAT thing" --GBR].

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

    [Formatting of submitted text altered slightly to use TeX quotation
    marks and remove a paragraph break.  You can also blame me for the use
    of the term "comparand", an irruption of my exuberance as a frustrated
    mathematician and logophiliac.  --GBR]


You want I should revert it while we continue to sort this out?  Does it make sense to credit you as "author" of the revert commit as well?

G. Branden Robinson <gbranden>
Group administrator
Thu 08 Jul 2021 09:17:38 PM UTC, comment #3: 

Apologies for the noise--this patch is invalid.  As Bjarni points out on the list (http://lists.gnu.org/archive/html/groff/2021-07/msg00035.html), CSTR #54 does in fact explain this operator further down in Section 16 (not much further from where I apparently stopped reading), where it explicitly says, "if the strings compare identically (including motions and character size and font)."

But comment #1 still does point out what seems to be a subtlety not covered by the current groff documentation.

Dave <barx>
Group Member
Mon 28 Jun 2021 04:09:30 AM UTC, comment #2: 

This bug is proposing an addition to the groff manual concerning the accuracy of CSTR #54's description of the 'xxx'yyy' operator.

Your observation that the existing groff documentation does not cover some corner cases of this operator's behavior is worthwhile, but unrelated to this bug's topic.  You should open a separate report for this.

Dave <barx>
Group Member
Sun 27 Jun 2021 04:12:05 PM UTC, comment #1: 


>  Last paragraph of original submission (same formatted output):




  This is not completly correct.

  An example:

.ds stringA ABC\h'2n'
.ds stringB ABC\h'4n'\h'-2n'
.
.ie "ABC\h'2n'"ABC\h'4n'\h'-2n'" \{\
strings are the same
.\}
.el \{\
strings are different
.br
ABC\h'2n'D
.br
ABC\h'4n'\h'-2n'D
.\}
.
.ie "\*[stringA]"\*[stringB]" \{\
strings are the same
.\}
.el \{\
strings are different
.br
\*[stringA]D
.br
\*[stringB]D
.\}
.

  The output is:

x T ps
x res 72000 1 1
x init
p1
x font 5 TR
f5
s10000
V12000
H72000
md
DFd
tstrings
wh2500
tare
wh2500
tdif
H126740
tferent
n12000 0
V24000
H72000
tABC
h10000
tD
n12000 0
V36000
H72000
tABC
h10000
tD
wh2500
tstrings
wh2500
tare
wh2500
tdif
H167020
tferent
n12000 0
V48000
H72000
tABC
h10000
tD
n12000 0
V60000
H72000
tABC
h10000
tD
n12000 0
x trailer
V792000
x stop


Bjarni Ingi Gislason <bjarniig>
Sun 27 Jun 2021 12:11:43 PM UTC, original submission:  

The Texinfo manual is pretty scrupulous about documenting errors in CSTR #54.  If it aims to encompass a complete errata sheet for CSTR #54 (and if others agree this is an error in CSTR #54, not just an ambiguity), the below item should be included.  The attached patch gives one possible solution.

This concerns the conditional operator documented as 'xxx'yyy' (though any number of characters besides ' can be used as the delimiters).  If this operator has a commonly accepted name, I'm unaware of it.  In the patch's index entry I called it the "output-equivalence conditional operator."

Section 16 of CSTR #54 described this conditional as testing "if string1 identical to string2."  This makes it sound like it is testing whether the input strings match.

As commit 356bc65d noted when it updated similar erroneous wording in groff(7), and as the Texinfo manual describes at length, the operator actually tests whether the two strings produce the same formatted output. 

(Bug #58962 mentions this in passing.)

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #51604:  cstr_erratum.patch added by barx (691B - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by bjarniig (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 12 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-01-11 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2022-01-11 gbranden StatusNone In Progress
    2021-11-27 gbranden SummaryImprove documentation of output-comparison operator better Improve documentation of output-comparison operator
    2021-10-10 barx StatusNeed Info None
    2021-08-23 barx SummaryImprove output-comparison operator better Improve documentation of output-comparison operator better
    2021-07-10 gbranden Summary[PATCH] Document erroneous CSTR #54 description of comparison conditional Improve output-comparison operator better
    2021-07-09 gbranden StatusIn Progress Need Info
    2021-07-06 gbranden StatusNone In Progress
        Assigned toNone gbranden
    2021-06-27 barx Attached File- Added cstr_erratum.patch, #51604

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code