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

 
 

bug #60836: Improve documentation of output-comparison operator better

Submitted by:  Dave <barx>
Submitted on:  Sun 27 Jun 2021 12:11:43 PM UTC  
 
Category:  Core Severity:  2 - Minor
Item Group:  Documentation Status:  None
Privacy:  Public Assigned to:  G. Branden Robinson <gbranden>
Open/Closed:  Open Planned Release:  None

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

( Jump to the original submission)

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>
Project 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>
Project 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>
Project AdministratorIn charge of this item.
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>
Project 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>
Project AdministratorIn charge of this item.
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>
Project 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>
Project 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>
Project 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)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    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.7