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:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.24.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 18 May 2025 05:08:47 PM UTC, comment #9: 


commit 732b07d4998bec1cc942481e7cf4e7287050c40b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun May 18 10:07:35 2025 -0500

    [man]: Fix Savannah #65190 (1/2).

    Refactor continuous rendering mode to use an "infinite page length"
    method facilated by the new semantics of the `.R` register.

    * tmac/an.tmac (an-ne): Drop unneeded macro.

      (an-bp): Rename this...
      (an*bp): ...to this, define it with `de1` to temporary disable
      compatibility mode, and replace definition.  No longer altering
      the page length, it works like `br`, including
      control-character-sensitive behavior.

      (an-end): If continously rendering, stop incrementing the page length
      prior to writing the footer and document separation line, and upon
      encountering the end of the last document (the input file name
      register `.F` becomes empty), set the page length to the vertical
      drawing position.

      (an-end, TH): Call `an*break-page-with-new-number` only if _not_
      continuously rendering.

      (an-set-up-continuous-rendering): Drop macro in favor of open-coded
      initialization logic.

      (PT, BT): Stop manipulating the page length when continuously
      rendering.

      ([initialization]): If continuously rendering, set up replacement
      macro for `bp` request and set the page length to "infinite".

    Fixes Savannah #65190 (1/2).

commit d8cd70f3a8cfd06996ddce6b1d18150eaef69983
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun May 18 10:35:01 2025 -0500

    [mdoc]: Fix Savannah #65190 (2/2).

    [mdoc]: Refactor continuous rendering mode to use an "infinite page
    length" method facilated by the new semantics of the `.R` register.

    * tmac/mdoc/doc-common (doc-ne): Drop unneeded macro.

      (doc-bp): Define with `de1` to temporary disable compatibility mode,
      and replace definition.  No longer altering the page length, it works
      like `br`, including control-character-sensitive behavior.

      (doc-set-up-continuous-rendering): Drop macro in favor of open-coded
      initialization logic.

      ([initialization]): If continuously rendering, set up replacement
      macro for `bp` request and set the page length to "infinite".

      (Dd): Call `an*break-page-with-new-number` only if _not_ continuously
      rendering.

      (doc-end-macro): If continously rendering, stop incrementing the page
      length prior to writing the footer and document separation line, and
      upon encountering the end of the last document (the input file name
      register `.F` becomes empty), set the page length to the vertical
      drawing position.

    Fixes Savannah #65190 (2/2).


G. Branden Robinson <gbranden>
Group administrator
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 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2025-05-18 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.24.0
    2025-05-18 gbranden Dependencies- bugs #65099 is dependent
    2025-05-18 gbranden StatusConfirmed In Progress
    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.15-26b0.
    Corresponding source code