LaTeX: large voids at bottom of pages in PDF with a section moved needlessly to next page

[jfbu]

Describe the bug

One observes sometimes large voids at bottom of pages. This is a relatively rare and delicate phenomenon.

After some analysis, it is due to interaction between two LaTeX packages: parskip and titlesec due to the fact we load the latter with option nobottomtitles*. See #6633 which introduced its use.

(we could produce a pure LaTeX example using only parskip and titlesec as Sphinx does and dropping all Sphinx LaTeX support files).

Sphinx uses parskip with [=v1] option but the issue can be reproduced without it (minimal reproducer has to be modified a bit because vertical whitespace chnages).

EDIT: actually parskip is not involved in this issue (we were fooled because suppressing it made the issue go away in our tests, but this is simply consequence of modified vertical spacing). Thanks @dbitouze.

In the above example if we toggle two sections we see there was ample room to fit entirely the one which was pushed to next page.

The issue was observed in a real-life project (with a 2000+ pages PDF) and the gap was even more spectacular but it is delicate to reproduce exactly if not using the exact same contents.

(for the sake of the screenshots, the openany option was added and a page was added so that I could get my PDF viewer to display the pages by 2 as above)

How to Reproduce

index.rst is

FOO documentation
=================

Test
====


Tttttt Ttt tt TtTtttttTtttt, tt Ttttt Tttttttttt tt tt.
-------------------------------------------------------

Xxxxxx Xxx xéxxxx xx xx xxxxxx XxxxXxxx xxxxxxxxxxx xxxxxxxxx xxxxxxxxxx xx
xêxx xxx x’Xxxxx.  Zzz zzzzzzz zzzz zzzzzzz zzzz zzzzzzzzz zzz ppppppp
ppppppppppp pp ppppp pppppp pp pppppp Ppppp Pppp 1.  Z’zzzzzzzzz ZzzzzzZzz
zzz zz zzzzz zz zzzzzzz zzzzz zz zzzzézzzzzzz zz zzzzzzzzz Zzzzzz Zzz zzzz
zz zzz zz zzzzzzz zzzzzzzz (zz zzzzzzz) ZzZzzzzz ézzzz zzzzzzézzzzzzzzz zz
zzzzzzzzzz zzz zzzzzzzz.


VV Vvvv
-------

ZZ Zzzz zzz zzz zzzzzzz zz zzzzzzz zz zzzzzzèzzz zzzz zzzzzzzzzzz zzzéz zzz
Zzzzzzzz.  Zzzz zzzzzzzz zzz zzzzzzz zézzzzzzzzz à zz zzzzzzzzzzz
zzzzézzzzzzz (zzzzzzzz, zzzzzzzz zz zzzzzzzzzz zzzzézzzzzzzz, zzzzzzzz
zzzzzzzzzzzzzzz) zzzz zzz zzzzzzzz zzzzzzzz zz zzzzzzz.  Zz zzzzzzz zzzzzzzz
ézzzzzzzz zzzzzz zzz zzzzzzz zz zzzzz zzzzzézz ZZ1, Z1 zz zzzzézzzzzz zzzzzz,
zzzzz zzz zzz zzzzzzz zzzz zzz zzzzzzz zzz zzzz zzzzzz zz z’zzzzzzzz ZZ1.  Zzz
zzzzzzzzz zzzzzzzzzz z’zzzzzzzz zzz zzzzzzz zzzz Zzzzz ZzZ, ZzZzZ 2.09 zz
ZzZzZ zzzz zzzzzzzz.  Zzz zzzzzzzzzzzz zzz zz êzzz zzzzzézz zzz zzz zzzzzzz
zz zzzz zz ZzzzzZzzzz zzzz zz zzzzézé z’zzzzzz zzzz.

UU Uuuu, uu UuuuuUuuuu Uuu.
---------------------------

YY Yyyy yyy yyy yyyyyyy yy 14 yyyyyyy yy yyyyyyèyyy yyyy yyyyyyyyyyy,
yyyyyyéy yy yy yyyyyy Yyyyy.  YY Yyyy yyyyyyyy yyy yyyyyyy yéyyyyyyyyy à
yy yyyyyyyyyyy yyyyéyyyyyyy (yyyyyyyy, yyyyyyyy yy yyyyyyyyyy yyyyéyyyyyyyy)
yy yyyyyyyy yyyyyyyy yy yyyyyyy.  Yy yyyyyyy yyyyyyyy éyyyyyyyy yyyyyy yyy
yyyyyyy yy yyyyy yyyyyéyy YY1 yy Y1 yy yyyyéyyyyyy yyyyyy, yyyyy yyy yyy
yyyyyyy yyyyyyyyy yyy yyyyyyy yyy yyyy yyyyyy yy y’yyyyyyyy YY1.  Yyy
yyyyyyyyyy yyyyyyyyyy y’yyyyyyyy yyy yyyyyyy yyyy Yyyyy YyY, YyYyY 2.09 yy
YyYyY yyyy yyyyyyyy.  Yyy yyyyyy yyyyyyyyyyyy yyy yyyyyyy yyyy yyyyyyyyyyy
yyyyyyyyyyyy yyy YYYY.  Yyy yyyyyyyyyyyy yyy yy êyyy yyyyyéyy yyy yyy yyyyyyy
yy yyyy yy YyyyyYyyyy yyyy yy yyyyéyé y’yyyyyy yyyy.


ttttttt, ttttttt tt ttttt tétttét
---------------------------------

xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx


T’tttttttt Ttttttt ttttttt 1.0 (26 ttttt) tt Ttttt Ttt.
-------------------------------------------------------

X’xxxxxxxx xxxxxxx xxx xxxxxxxxé xx 26 xxxxxxx :

xxx xxxxxxx xx xxxxx xxxxxxxxxx xxxxxxxxx Xxxxx Xxxxxxxx
(xx xxx xxxxxxçxxx XXX Xxxxxxxx) xxxx xxx xxxxxxxx xxxx, éxxx xx xxxxx xxxxxxx xxxxxxéx ;

xxx xxxxxxxxx xxxxéxxxxxxxx xxxxxxxxx Xxxxxxxx (xx Xxxxxxxx) ;

xxx xxxxxxx xxxxéxxxxxxxx xx xxxx xxx xxxxxxxx xxx xxxxxxx xxxxéxxxxxxxx xxxxxxxx
(xxxx, xxxx, xxxx xx xxx xxxxxxx xxxxxxxx xx xxx) ;

xxx xxxxxxx xxxxéxxxxxxxx xx xxxx xxx xxxxxxxx xxxxxxxxxxxxx xxx xxxxxxx XXX
(xxxx xx xxxx) ;

xxx xxxxxxx xxxxéxxxxxxxx xxxxxéxxxxxxxxx xxxx xxxxxx xxxxxxxx.

Environment Information

Python version:        3.12.3 (v3.12.3:f6650f9ad7, Apr  9 2024, 08:18:48) [Clang 13.0.0 (clang-1300.0.29.30)])
Python implementation: CPython
Sphinx version:        8.1.0+/53f8edfba
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

none

Additional context

No response

[dbitouze]

I don't think parskip has anything to do with this issue: even without it, the problem remains. One solution is to reduce the length of \bottomtitlespace, which by default is .2\textheight, e.g. as follows:

\renewcommand{\bottomtitlespace}{.1\textheight}

[jfbu]

The cause is simply that the default of titlesec under nobottomtitles* appears to require that there is at least 0.2\textheight space available for not moving section title to next page. I.e. for Sphinx default with letterpaper, and 1in margins, this is a whopping 1.8in (4.57cm), and with a4paper this is 4.92cm (1.94in). These dimensions are enormous.

Fortunately we can customize this by reassigning the titlesec parameter \bottomtitlespace. It does not seem to make any sense to let it be a multiple of \textheight, an absolute dimension (or a relative one related to \baselineskip) makes much more sense.

[jfbu]

Thanks @dbitouze for help in this matter.