bugGNU roff - Bugs: bug #65190, [man,mdoc] revise implementation...

 
 

bug #65190: [man,mdoc] revise implementation of continuous rendering mode

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Mon 22 Jan 2024 08:25:59 PM UTC
   
 
Category:  Macro package - others/general Severity:  3 - Normal
Item Group:  Incorrect behaviour Status:  Confirmed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sat 03 Feb 2024 12:53:18 AM UTC, comment #8: 

comment #6:

> I've heard no demand expressed for continuously rendered
> ms/me/mm/mom documents.


Less self-serving instances:

There may well be more, but it's not an easy thing to search because there's no historically consistent terminology for the concept.

Dave <barx>
Group Member
Thu 25 Jan 2024 12:01:13 AM UTC, comment #7: 

comment #6:

> I've heard no demand expressed for continuously rendered
> ms/me/mm/mom documents.


The act of filing #61453 might be said to constitute demand. ;-)

Granted, for me it's low priority: I have a solution that works, albeit one that's kludgy and requires poking into -me-package internals.  Something cleaner would be nice but won't materially alter my current functionality.

> that's why I don't think this ticket is a duplicate of that one.


Not a duplicate, a special case.  But a case with higher demand.

Dave <barx>
Group Member
Wed 24 Jan 2024 11:34:23 PM UTC, comment #6: 

Hi Dave,

comment #5:

> Those steps will solve the problem in the man/mdoc domain.


Right.

>  Which is maybe all you care about for now.  It is an easier problem.


For now, yes, because this is a problem that is provoking user complaints, whereas I've heard no demand expressed for continuously rendered ms/me/mm/mom documents.  (I've felt some myself, with respect to ms.ms...)

>  My point is that bug #61453 is looking for a general solution for continuous rendering that works for all nroff output -- which might include diverted footnotes and a footer of one or more lines.  This is a harder problem.


Agreed, and that's why I don't think this ticket is a duplicate of that one.

> But if it's solved, the easier problem is also solved for free.


I don't think there is a general solution, but a solution to the .R=INT_MAX problem will make particularized ones (flush footnotes and pending displays at a [configurable?] section heading level and/or the end of the document) easier.

Regards,
Branden

G. Branden Robinson <gbranden>
Group administrator
Wed 24 Jan 2024 11:28:54 PM UTC, comment #5: 

Those steps will solve the problem in the man/mdoc domain.  Which is maybe all you care about for now.  It is an easier problem.  My point is that bug #61453 is looking for a general solution for continuous rendering that works for all nroff output -- which might include diverted footnotes and a footer of one or more lines.  This is a harder problem.  But if it's solved, the easier problem is also solved for free.

Dave <barx>
Group Member
Wed 24 Jan 2024 06:04:59 PM UTC, comment #4: 

Hi Dave,

comment #3:

> This seems like a specific case of the general enhancement bug #61453 seeks.


Possibly we could do some ticket merging here (a manual process involving "closing" as "duplicate", adding cross references in both directions, and updating ticket dependencies), but I conceive of this problem as comprising 3 stages.

1.  Make it possible to represent INT_MAX in register values and decide what to do about overflow (saturating arithmetic, maybe) and update the documentation (bug #64301).
2.  Assign the `.R` register this value by default and update the documentation (bug #63587).
3.  Update the man and mdoc packages to use the mechanism described at the end of comment #0 (this bug).  Blissfully, this would require no documentation update.  It should "just work".

Optimistically yours,
Branden

G. Branden Robinson <gbranden>
Group administrator
Tue 23 Jan 2024 08:07:14 PM UTC, comment #3: 

This seems like a specific case of the general enhancement bug #61453 seeks.

Dave <barx>
Group Member
Tue 23 Jan 2024 12:36:06 AM UTC, comment #2: 

Hi Bjarni,

comment #1:

>   The examples "lsp-help.1" and "lsp-help.broken.1" render OK
> with the patch in bug #63960, which I installed in my repository
> at that time.


In my opinion, that's a hack.  It extends the page length by one thousand inches, and has to modify a groff man internal register to compensate.  The latter might be fair enough since the patch is to "an.tmac", but it simply doesn't feel as simple and robust as my proposed fix.

On the downside, someone can apply your patch today, whereas this one ultimately requires hardening the formatter's arithmetic expression evaluator.  :-|

But we should be doing that anyway.

Regards,
Branden

G. Branden Robinson <gbranden>
Group administrator
Tue 23 Jan 2024 12:19:48 AM UTC, comment #1: 

  The examples "lsp-help.1" and "lsp-help.broken.1" render OK
with the patch in bug #63960, which I installed in my repository
at that time.

Bjarni Ingi Gislason <bjarniig>
Mon 22 Jan 2024 08:25:59 PM UTC, original submission:  

The present approach leads to issues like bug #65189, because it's impossible for the macro package to know how long a tbl table will be before formatting it.

At present, continuous rendering is handled by accepting the default page length, and then incrementally growing it as the formatter gets "close" to the page bottom, by setting a trap.

This has been a fragile procedure and I fixed several bugs in it for groff 1.23.0 so that we could get better results when support rendering hundreds of man page documents in one formatter run.

But bug #65189 seems intractable by the foregoing trapping/page-length incrementation approach.  Our trap for breaking the page body before the footer doesn't seem go off inside tbl tables, I think because they are formatted in diversions by default.  (I tried to tell tbl not to use keeps when continuously rendering, but it didn't help cases like lsp-help(1) and ascii(7)).  (The problem may be that text blocks are formatted in diversions no matter what.)

What appears to happen is that output sneaks across a page boundary (as the formatter conceives it) anyway.  This has a couple of negative consequences.

1.  Vertical rules, drawn upward from the table bottom, can show up in the wrong place; this is bug #65189.
2.  Warnings in the "break" category have long been pretty useless with continuously formatted man pages.  Because the page length is variable, the reported page number means nothing.

Here's a reproducer.


$ cat ATTIC/line-too-long.man
.pl 10v \" contrive an artifically short page length
.TH foo 1 2024-01-22 "groff test suite"
.SH Name
foo \- bar
.SH Description
.TS
L.
T{
.nf
1
2
3
4
5
6
T}
T{
.nf
1
2
3
4
5
6
T}
.TE
.P
12345678901234567890123456789012345678901234567890123456789012345678901234567890


We get the following warning.


troff:ATTIC/line-too-long.man:28: warning [page 2, line 7]: cannot break line


...which has no relationship to any reality the user can perceive.


$ nroff -t -rLL=65n -man ATTIC/line-too-long.man | cat -n
troff:ATTIC/line-too-long.man:28: warning [page 2, line 7]: cannot break line
     1  foo(1)               General Commands Manual               foo(1)
     2
     3  Name
     4       foo - bar
     5
     6  Description
     7       1
     8       2
     9       3
    10       4
    11       5
    12       6
    13       1
    14       2
    15       3
    16       4
    17       5
    18       6
    19
    20       12345678901234567890123456789012345678901234567890123456789012345678901234567890
    21
    22  groff test suite            2024‐01‐22                     foo(1)


Line 7 of what?  Where?

If the page length were unbounded (or practically so), we could radically simplify the implementation of continuous rendering mode, and fix the foregoing problems.

So what we want to do is the moral equivalent of `.pl INT_MAX`.  But thereby hangs a tale...

G. Branden Robinson <gbranden>
Group administrator

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Carbon-Copy List
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by bjarniig (Posted a comment)
  • -email is unavailable- added by gbranden (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 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-01-22 gbranden Dependencies- Depends on bugs #63587
    2024-01-22 gbranden Dependencies- bugs #65189 is dependent

    Back to the top

    Powered by Savane 3.13-ee12.
    Corresponding source code