bugGNU troff - Bugs: bug #58035, clarify page offset in...

 
 

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

Submitted by:  Dave <barx>
Submitted on:  Tue 24 Mar 2020 08:11:40 AM UTC  
 
Category:  Core Severity:  3 - Normal
Item Group:  Documentation Status:  In Progress
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.

 

Sat 11 Apr 2020 08:50:22 AM UTC, comment #1: 

The spreadwarn part of this is done in faf49609f480bcae418a1173fe89fa7c6d981aeb.

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

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

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