Re: reformatting man pages at SIGWINCH

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4103 bytes --]

Hi Dirk,

At 2023-04-10T21:05:24+0200, Dirk Gouders wrote:
> This relies on the assumption that horizontal resizes don't create or
> delete emty lines and it still has the weakness that manual pages
> (e.g. bash(1)) contain large areas without empty lines but it's
> definitely better than just staying at the position as it was before.

I think this assumption should hold for man and mdoc documents rendered
by a *roff--I'm not sure about mandoc(1), but it probably will for
reasons I'll elaborate below.

Vertical space in *roff documents might get reduced at page breaks, but
not to zero, except at page breaks.

There are a few reasons that I think reinforce the assumption holding:

1.  man(7) and mdoc(7) don't offer macros for just sticking an arbitrary
amount of vertical space into a document.  If you want that, you'll need
to go down to formatter requests, which is seldom done by human man page
authors, but a bit more frequently by automated generators of man(7) or
mdoc(7) from other formats.

2.  Even in traditional *roff, if you issued an ".sp 6" request
(demanding 6 blank lines), then if you were within 6 lines of a "trap"
(usually a page footer trap or the actual bottom of the page), the
result would be that you'd get blank lines until the trap sprung, and
any excess would be thrown away.  So if there were only 4 lines of
distance to the page footer, the leftover two would be discarded and
_not_ appear after the header of the next page.[1]

3.  mandoc(1) and groff's man(7) and mdoc(7) macro packages both
implement "continuous rendering" for terminal output.  This means that
they contrive to arrange for an effectively infinite page length, so
there are no page breaks.  (Except when you render multiple man pages at
a time, a use case groff 1.23.0 will support.) Since pager programs are
applicable only to terminal output in the first place, this should
address your use case.  (You _can_ turn off continuous rendering in
groff, and see man pages as they would have formatted for Western
Electric Teletype machines, which printed to long spools of paper with
66 lines to the nominal page.)

4.  A habit has grown up among man(1) programs and pagers to call for
and support, respectively, a "blank line squeezing" feature: any runs of
more than one blank line are condensed to 1 blank line each.  In groff
1.23.0, this will no longer be necessary when continuously rendering.
(Historically, this squeezing feature was used to "tighten up" vertical
space after the page header, prior to the "NAME" section heading of the
document.)  In my opinion, pager programs should perform as few
transformations as possible on the output of grotty(1), the groff output
driver that supports terminal devices.  The long-time author and
maintainer of less(1) does not agree, so you have to call that program
with its "-R" flag to view grotty(1) output as groff intends it.  (To
see what those intentions are, format the document without paging it.)

> If it turns out to still be too weak, I could count all words between
> two empty lines and set that in relation to the words from the
> preceeding empty line.

You might do this only as a fallback, if there were no blank lines on
the screen at the old window size when the resizing event happened.

> But perhaps, I now learn that empty lines are by no means that
> constant value that I assume...

In my opinion, the presence or absence of a single blank line in
formatted output is important.  groff 1.23.0 will feature some bug fixes
with respect to their handling within and adjacent to tbl(1) input.[2]

Since I flogged groff 1.23.0 three times in this email, I suppose I
should point people to where they can get the 1.23.0.rc3 release
candidate source archive.  Feedback would be appreciated.

https://alpha.gnu.org/gnu/groff/

Regards,
Branden

[1] For example, give the following input to "nroff | cat -n".

--snip--
.pl 10v
.nf
The page length is set to 10 vees.
2
3
4
5
Asking for 6 vees of space now.
.sp 6
How many appeared?
--end snip--

[2] https://savannah.gnu.org/bugs/?57665
    https://savannah.gnu.org/bugs/?49390

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]