bugGNU roff - Bugs: bug #58035, clarify page offset and spreadwarn...

 
 

bug #58035: clarify page offset and spreadwarn behavior in doc/groff.texi

Submitter:  Dave <barx>
Submitted:  Tue 24 Mar 2020 08:11:40 AM UTC
   
 
Category:  Core Severity:  3 - Normal
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

Wed 03 May 2023 09:33:59 PM UTC, comment #8: 

Though the page offset was the only remaining problem for the last two years of this bug's existence, it did result in fixes to two problems altogether, so I'm re-expanding the scope of the Summary to make it more findable to those (e.g., me) later searching for it.

Dave <barx>
Group Member
Tue 15 Mar 2022 02:01:38 AM UTC, comment #7: 

Looks great, thanks!  Hope closing this bug again was as satisfying as you'd imagined.

Dave <barx>
Group Member
Mon 14 Mar 2022 06:00:43 AM UTC, comment #6: 


commit 6cdb2a543810a2bb2eca2d9c60e03b84d20e8649
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Mar 7 13:35:47 2022 +1100

    doc/groff.texi: Finish(?) fixing Savannah #58035.

    * doc/groff.texi (Manipulating Filling and Adjustment): Explicitly
      identify the page offset as an output line property that is not
      determined until a break occurs.

      (Line Layout) <po>: Correct error; the page offset for terminal
      devices is set by "tty.tmac", not "troffrc".  (The manual has been
      wrong for a long time; we've had it in tty.tmac since James Clark put
      it there in 1992.)  Recast and tighten wording.  Drop the word
      "horizontal"; there is no vertical page offset (as such) in *roff.
      Drop hand-waving about unexpected results with a description of the
      formatter's behavior.  Dcoument request behavior without an argument
      before getting into the weeds (and CSTR #54 errata).  Migrate
      terminology from "scaling indicator" to "scaling unit".

    Fixes <https://savannah.gnu.org/bugs/?58035> [with crossed fingers].


G. Branden Robinson <gbranden>
Group administrator
Sun 06 Mar 2022 02:57:26 PM UTC, comment #5: 


comment #4:

> The foregoing addition is fantastic and I have no quarrel with it.


Thanks!  >blush<

> The ambiguous .po sentence reported in comment #0 remains in place (substantively unchanged from its commit af2d6f8e debut in 1999), so this bug could be reopened on those grounds.


You're right--I added material earlier in the manual that makes it easier to interpret correctly, but I didn't really fix the spot in question.

> On the other hand, this passage of the manual has yet to be Brandenified, and the ambiguity here is no worse than the hundreds of others you've caught and corrected as you work your way through the Texinfo manual, so perhaps it's best to trust that the ambiguous sentence will meet its inevitable fate when its time naturally comes, without needing any prodding from savannah.


Well, how about I keep cracking at it (I have further changes in progress), and then I can get the satisfaction of closing the ticket again?  ;-)

G. Branden Robinson <gbranden>
Group administrator
Fri 04 Mar 2022 09:32:44 PM UTC, comment #4: 

comment #3:

> Any problems with the foregoing can be reported in future tickets


The foregoing addition is fantastic and I have no quarrel with it.

The ambiguous .po sentence reported in comment #0 remains in place (substantively unchanged from its commit af2d6f8e debut in 1999), so this bug could be reopened on those grounds.

On the other hand, this passage of the manual has yet to be Brandenified, and the ambiguity here is no worse than the hundreds of others you've caught and corrected as you work your way through the Texinfo manual, so perhaps it's best to trust that the ambiguous sentence will meet its inevitable fate when its time naturally comes, without needing any prodding from savannah.

Dave <barx>
Group Member
Thu 03 Mar 2022 09:34:55 PM UTC, comment #3: 

Wait, no, son of a gun.  This is no longer in progress, but not because I quit working on it.  Instead, I pushed material discussing it.


commit 1228acc430b2b9638c598a223496ceebfed778af
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Feb 3 04:05:14 2022 +1100

    [docs]: Present several fundamental concepts.

    * doc/groff.texi (Page Geometry):
    * man/roff.7.man (Concepts): Add new node/section defining concepts.
      - device resolution
      - basic units
      - drawing position
      - text baseline
      - page offset
      - vertical spacing
      - vee
      - page break

    Also:
    * doc/groff.texi: Bump date.  Add an authorship credit for myself.

    $ git diff --stat 1.22.4 HEAD doc/groff.texi
     doc/groff.texi | 13649 ++++++++++++++++++++++++++---------------------
     1 file changed, 7578 insertions(+), 6071 deletions(-)

    * doc/groff.texi:
    * man/roff.7.man: Bump copyright notice.


Any problems with the foregoing can be reported in future tickets, if not already covered by, say, bug #60820.

Also here's the commit message for the spreadwarn stuff.


commit faf49609f480bcae418a1173fe89fa7c6d981aeb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Apr 11 17:50:57 2020 +1000

    Rework documentation of .spreadwarn.

    * doc/groff.texi (.spreadwarn):
    * man/groff.7.man (.spreadwarn):
    * man/groff_diff.7.man (.spreadwarn):
      Recast a lot of wording, some based on suggestions from Dave Kemper.
      Make more prominent the fact that spreading only applies to adjustment
      mode 'b'.  Document warning type used.

    Fixes half of Savannah #58035.


G. Branden Robinson <gbranden>
Group administrator
Wed 02 Mar 2022 07:38:50 PM UTC, comment #2: 

It's a fib to say this is still in progress.  Stopping.

G. Branden Robinson <gbranden>
Group administrator
Sat 11 Apr 2020 08:50:22 AM UTC, comment #1: 

The spreadwarn part of this is done in faf49609f480bcae418a1173fe89fa7c6d981aeb.

G. Branden Robinson <gbranden>
Group administrator
Tue 24 Mar 2020 08:11:40 AM UTC, original submission:  

doc/groff.texi has a couple of curious sentences that could be clarified with small rewrites.

.po


.po "does not cause a break, so changing the page offset in the middle of text being filled may not yield the expected result."  This fails to say what the actual result is, just that it "may not yield" some other result that is also unspecified.

If the behavior is intentionally undefined, the documentation should explicitly state this.  CSTR #54 (section 3) does not define this behavior, so perhaps the behavior is by definition undefined (if one defines back compatibility as complying with historical documentation rather than a particular historical implementation).  If it is well defined but nonintuitive, the details should be explained.

.spreadwarn


The documentation states, "This request is active only if text is justified to both margins (using '.ad b')."  The condition that .spreadwarn warns about only occurs when spaces are stretched, and spaces are stretched only in fully justified text.  Whether the request "is active" in other modes seems less material than the fact that, even if active in all modes (which I presume is the actual case in the groff code), it can only ever be triggered in mode ".ad b".

But rather than trying to reword this sentence, it might make more sense to make the request's scope clear in its initial description; that is, where the first sentence says "emit a warning if the additional space inserted for each space between words in an output line", I would change the end of this to say "...in an output line that is justified to both margins."  (I would ideally prefer to phrase it more concisely, as "...in a fully justified output line," but the term "fully justified" is used nowhere else in the groff manual, so a reader unfamiliar with the concept who sees this phrase here cannot learn more by searching the manual.)

Dave <barx>
Group Member

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

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 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 14 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-05-03 barx Summaryclarify page offset in doc/groff.texi clarify page offset and spreadwarn behavior in doc/groff.texi
    2022-03-14 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2022-03-06 gbranden StatusFixed In Progress
        Open/ClosedClosed Open
        Planned Release1.23.0 None
    2022-03-03 gbranden StatusNone Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2022-03-02 gbranden StatusIn Progress None
    2020-07-25 gbranden Summaryclarify wording in doc/groff.texi clarify page offset in doc/groff.texi
    2020-04-11 gbranden StatusNone In Progress
        Assigned toNone gbranden

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code