Re: reformatting man pages at SIGWINCH

[Dirk Gouders]

Hi Branden,

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

> 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.)

Thank you for the detailled assessment.  Perhaps my misunderstanding is
because I'm not a native speaker but which document should I format to
see what those intentions are?

>> 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.

Yes, such a fallback would be good to have.  I am again about to
implement a suggestion with some modifications: I would make using the
section-word-count (which is expensive) dependent on _how many_ words I
found while searching for an empty line or the section header.  My
motivation for this is that an increasing number of continuous words
also increases the possibility for hyphenation working against the
heuristics.  Saying that, I probably also need to consider the number of
lines that contain those words.  I have to think more about this.

>> 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.

Oh well, I didn't measure it but I spent quite some time to work on
doc/lsp-help.1 and try to find a solution for that "nasty empty line"
that appeared in of the tables that I use for the online help -- I was
convinced it was my fault.

Gentoo already has an ebuild for groff-1.23.0-rc3 and simply using this
fixes that problem in the table.  So, from now on all my testing happens
with groff-1.23.0-rc3 and I will report should I recognize problems.

Regards,

Dirk