Behavior change: no more nonpositive page lengths

[G. Branden Robinson]

I ended up pretty tightly constrained with my work on checked arithmetic
(itself a precursor to saturating arithmetic),[1] so I thought I should
advise regarding a non-backward-compatible change I've pushed to HEAD.

(Before anyone goes pale, this has nothing to do with a nonpositive
_vertical drawing position_, which is valid, useful, and fairly well
understood.)

A nonpositive page length, you may ask?

As far as I know, only GNU troff has ever documented what that means.

It's basically a combination of

.vpt 0

and

.pl 1v

...except a page actually _is_ ejected after every output line.
(An actual `.vpt 0` request prevents page ejection.)

Consider the following input document.

$ cat EXPERIMENTS/negative-page-length.roff
.pl 0-1
Sed ut perspiciatis, unde omnis iste natus error sit voluptatem
accusantium doloremque laudantium, totam rem aperiam eaque ipsa, quae ab
illo inventore veritatis et quasi architecto beatae vitae dicta sunt,
explicabo.  Nemo enim ipsam voluptatem, quia voluptas sit, aspernatur
aut odit aut fugit, sed quia consequuntur magni dolores eos, qui ratione
voluptatem sequi nesciunt, neque porro quisquam est, qui dolorem ipsum,
quia dolor sit amet consectetur adipiscivelit, sed quia non-numquam eius
modi tempora incidunt, ut labore et dolore magnam aliquam quaerat
voluptatem.

$ ~/groff-stable/bin/groff --version | head -n 1
GNU groff version 1.23.0
$ ~/groff-stable/bin/groff -T ascii -aww EXPERIMENTS/negative-page-length.roff
<beginning of page>
Sed ut perspiciatis, unde omnis iste natus error sit voluptatem
<beginning of page>
accusantium doloremque laudantium, totam rem aperiam eaque ipsa,
<beginning of page>
quae ab illo inventore veritatis et quasi architecto beatae vitae
<beginning of page>
dicta sunt, explicabo. Nemo enim ipsam voluptatem, quia voluptas
<beginning of page>
sit, aspernatur aut odit aut fugit, sed quia consequuntur magni
<beginning of page>
dolores eos, qui ratione voluptatem sequi nesciunt, neque porro
<beginning of page>
quisquam est, qui dolorem ipsum, quia dolor sit amet consectetur
<beginning of page>
adipiscivelit, sed quia non-numquam eius modi tempora incidunt,
<beginning of page>
ut labore et dolore magnam aliquam quaerat voluptatem.

GNU troff does this is both nroff and troff modes.  DWB and Heirloom
Doctools nroff seem to ignore a nonpositive page length completely (as
bleeding-edge GNU troff now does).

$ ./bin/nroff negative-page-length.roff \" Heirloom
Sed ut perspiciatis, unde omnis iste natus error  sit  voluptatem
accusantium  doloremque laudantium, totam rem aperiam eaque ipsa,
quae ab illo inventore veritatis et quasi architecto beatae vitae
dicta sunt, explicabo.  Nemo enim ipsam voluptatem, quia voluptas
sit, aspernatur aut odit aut fugit, sed quia  consequuntur  magni
dolores  eos,  qui ratione voluptatem sequi nesciunt, neque porro
quisquam est, qui dolorem ipsum, quia dolor sit amet  consectetur
adipiscivelit,  sed  quia non-numquam eius modi tempora incidunt,
ut labore et dolore magnam aliquam quaerat voluptatem.
$ DWBHOME=. ./bin/nroff negative-page-length.roff
Sed ut perspiciatis, unde omnis iste natus error  sit  voluptatem
accusantium  doloremque laudantium, totam rem aperiam eaque ipsa,
quae ab illo inventore veritatis et quasi architecto beatae vitae
dicta sunt, explicabo.  Nemo enim ipsam voluptatem, quia voluptas
sit, aspernatur aut odit aut fugit, sed quia  consequuntur  magni
dolores  eos,  qui ratione voluptatem sequi nesciunt, neque porro
quisquam est, qui dolorem ipsum, quia dolor sit amet  consectetur
adipiscivelit,  sed  quia non-numquam eius modi tempora incidunt,
ut labore et dolore magnam aliquam quaerat voluptatem.

I consequently expect that this feature is more a case of Hyrum's Law,
something wizards of high troff sorcery discovered ages ago but which
was never officially countenanced until Werner Lemberg made an "XXX"
comment about it in the groff Texinfo manual in commit a947dc5443, 19
May 2000, and I eventually documented it in commit 9be6acf926, 29 May
2023.  (I don't remember doing that.  And I missed that a page length of
zero works the same way.)

So, since it was seemingly never documented anywhere until very
recently,[2] and isn't portable across troff and nroff formatters
anyway, I figured no one would weep too much if it went away.

Let the list know if you need a replacement feature.

Here's the commit, minus the ChangeLog entry and code change.

commit a00682e9cb4070e35139f6df59130d9ce12505ce
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Jul 25 15:20:55 2024 -0500

    [troff]: Enforce minimum page length.

    * src/roff/troff/div.cpp (page_length): Clamp `pl` request argument to
      the output device's vertical resolution (similarly to the way `ll` and
      `lt` behave).

    * doc/groff.texi.in (Page Layout):
    * NEWS: Document this.

[...]

diff --git a/NEWS b/NEWS
index 90a1646ad..c89f4b55b 100644
--- a/NEWS
+++ b/NEWS
@@ -22,6 +22,11 @@ o The `mso` request no longer attempts to open a macro file 
named, say,
   simply processes the macro search path for a file name matching the
   request argument, and succeeds or fails depending on an exact match.

+o GNU troff no longer accepts nonpositive page lengths.  Attempting to
+  set one with the `pl` request clamps the page length to the vertical
+  motion quantum as `ll` does with the horizontal motion quantum in AT&T
+  and GNU troffs.
+
 o The `color`, `cp`, `linetabs`, and `vpt` requests now interpret
   arguments with negative values as instructions to disable the
   corresponding feature, using the *roff integer-to-Boolean conversion
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 18aff8d8c..1ea82341d 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -10096,12 +10096,12 @@ @node Page Layout
 @cindex configuring the page length (@code{pl})
 @cindex setting the page length (@code{pl})
 Change (increase or decrease) the page length per the numeric expression
-@var{length}.  The default scaling unit is @samp{v}.  A negative
-@var{length} is valid, but an uncommon application:@: it prevents page
-location traps from being sprung,@footnote{@xref{Traps}.} and each
-output line is placed on a new page.  If @var{length} is invalid, GNU
-@code{troff} emits a warning in category @samp{number}.  If @var{length}
-is absent or invalid, @samp{11i} is assumed.
+@var{length}.  The default scaling unit is @samp{v}.  If @var{length} is
+invalid, GNU @code{troff} emits a warning in category @samp{number}.  If
+@var{length} is absent or invalid, @samp{11i} is assumed.  If
+@var{length} is nonpositive, GNU @command{troff} emits a warning in
+category @samp{range} and sets the page length to the device's vertical
+motion quantum; recall @ref{Motion Quanta}.

 @cindex page length register (@code{.p})
 The read-only register @samp{.p} interpolates the current page length.

Regards,
Branden

[1] https://savannah.gnu.org/bugs/?64301
    https://savannah.gnu.org/bugs/?66001

[2] CSTR #54 doesn't discuss nonpositive page lengths.  Neither does the
    Heirloom Doctools manual.

signature.asc
Description: PGP signature