bugGNU roff - Bugs: bug #62182, [man] automatically prevent page...

 
 

bug #62182: [man] automatically prevent page break between (sub)section heading and tagged paragraph

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Mon 14 Mar 2022 06:17:55 AM UTC
   
 
Category:  Macro man Severity:  1 - Wish
Item Group:  Feature change Status:  Rejected
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Tue 19 Mar 2024 02:31:39 PM UTC, comment #5: 

I don't think there is a way to do this automatically.

Consider the following example:


.SH Foo
.SS Bar
.TP Bazifraglisticexpialidocious \" line break certain here
Now I'm going to ramble on and on about the Baz option to the interface with a series of words that just happens to format on exactly two output lines.


There's just no way for the package to know at the time `SH` is called that the subsequent text is going to present terrible places for page breaks for this many more lines (4 vees, plus the additional vertical spacing on the first caused by using a larger typeface for `SH` section headings).

The user will have to manage this by hand, as groff's own man pages do (imperfectly) with `br` and `ne` requests reserving the desired amount of vertical space.

But we could make this easier for the user by supplying keep macros that populate diversions, as ms has since the mid 1970s.  That is bug #62911.

They could then just "bracket" material that needs protection from breaking with `KS` and `KE` macro calls.

Closing as rejected (infeasible without macro package redesign).

G. Branden Robinson <gbranden>
Group administrator
Thu 17 Mar 2022 12:00:01 AM UTC, comment #4: 

Hi, Bjarni,

comment #2:

>   The request '.ne ...' should be in the macro (.SH, .SS, and so on).


Yes, but how are `SH` and `SS` to know how the argument to specify to the `ne` request?  All of their own arguments are spoken for.

comment #3:

>   Addition.
>
>   The request '.ne' is NOT NEEDED for continuous rendering (cR >= 1).


You're right, it isn't.  This is why all of my commits that add these `br`/`ne` combinations to our man pages are annotated with statements like "adjust dead-tree pagination".

G. Branden Robinson <gbranden>
Group administrator
Wed 16 Mar 2022 10:05:59 PM UTC, comment #3: 

  Addition.

  The request '.ne' is NOT NEEDED for continuous rendering (cR >= 1).

Bjarni Ingi Gislason <bjarniig>
Wed 16 Mar 2022 09:59:12 PM UTC, comment #2: 

  The request '.ne ...' should be in the macro (.SH, .SS, and so on).

Bjarni Ingi Gislason <bjarniig>
Mon 14 Mar 2022 06:22:19 AM UTC, comment #1: 

There are a couple of workarounds.

1. Manually manage dead-tree pagination in man page sources.

Here's an example of how we do that in our own pages.


src/devices/grops/grops.1.man-\&.\|.\|.
src/devices/grops/grops.1.man-.RE
src/devices/grops/grops.1.man-.EE
src/devices/grops/grops.1.man-.RE
src/devices/grops/grops.1.man-.
src/devices/grops/grops.1.man-when the command runs.
src/devices/grops/grops.1.man-.
src/devices/grops/grops.1.man-.
src/devices/grops/grops.1.man:.br
src/devices/grops/grops.1.man-.ne 3v
src/devices/grops/grops.1.man-.\" ====================================================================
src/devices/grops/grops.1.man-.SH Environment
src/devices/grops/grops.1.man-.\" ====================================================================
src/devices/grops/grops.1.man-.
src/devices/grops/grops.1.man-.TP
src/devices/grops/grops.1.man-.I GROFF_FONT_PATH
src/devices/grops/grops.1.man-A list of directories in which to seek the selected output device's


In other words, you put a `br` and `ne` request before the (sub)section heading macro call.

This resort to requests is unfortunate.

2. Write something, like a sentence of regular prose establishing context, between your section heading and (most likely) list of tagged paragraphs.

G. Branden Robinson <gbranden>
Group administrator
Mon 14 Mar 2022 06:17:55 AM UTC, original submission:  

Right now our man(7) implementation isn't smart enough to automatically suppress a page break if the first thing after a (sub)section heading is a tagged paragraph.


$ cat EXPERIMENTS/breaky-section-heading.man
.TH foo 1 "groff test suite" 2022-03-13
.SH Name
foo \- frobnicate a bar
.sp 49v
.SH Environment
.TP
.B MISFORTUNE
The kind of fortune that never misses.
$ groff -b -ww -a -man EXPERIMENTS/breaky-section-heading.man
<beginning of page>
foo(1) General Commands Manual foo(1)
Name
 foo <-> frobnicate a bar
Environment
2022-03-13 groff test suite 1
<beginning of page>
foo(1) General Commands Manual foo(1)
 MISFORTUNE
 The kind of fortune that never misses.
2022-03-13 groff test suite 2


This bug is present in groff 1.22.4 and persists in Git HEAD.

I'm not sure how to fix this.  We could read each paragraph into a diversion.  If we do that we might as well do the four-line window window/orphan control thing.

Most man(7) implementations have problems like this.  I don't think ours is worst than most.

But I'd like it to be better.

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

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -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 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-03-19 gbranden StatusNone Rejected
        Assigned toNone gbranden
        Open/ClosedOpen Closed

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code