Different latexpdf output on Linux and Windows

[nioncode]

Describe the bug When running pdflatex on a .tex file that includes the sphinx package, the vertical spacing after section headers is different between Linux and Windows. This breaks the whole layout of my document, because two lines of a new section regularly spill to the previous page.

To Reproduce Use the latex builder to create a sample tex file for a project. Replace the generated tex file with this MWE:

\def\sphinxdocclass{report}
\documentclass{sphinxmanual}
\usepackage{sphinx}
\usepackage{hyperref}
\usepackage{blindtext}
\begin{document}
\section{Overview}
\blindtext
\end{document}

Expected behavior The output should look the same on Windows and Linux, but it does not. Note that I reuse the generated latex folder on both, Windows and Linux, and do not let sphinx regenerate the folder / styles again (thus there should be no differences in the .sty files etc.).

When I remove \usepackage{sphinx} from the MWE .tex file, the output from both systems is identical.

Your project demo.zip

Screenshots Linux: Windows:

Environment info

• OS: Linux, Windows
• Python version: 3.6.8 and 3.6.5
• Sphinx version: 1.7.8 and 1.8.3
• Extra tools: TeX Live 2018

[jfbu]

Please add \listfiles to the preamble and attach the .log files of each pdflatex compilation. In all probability this is caused by diverging versions of LaTeX packages which is out of Sphinx hand. All I can say at this stage is that strangely the Linux-pdf does not have correct timestamps in its metadata. You don't say which installation of TeX you use on Windows? MikTeX or TeXLive ? and if TeXLive which year ? In all probability the Linux install is old, as MikTeX usually is uptodate. The a priori suspect here is package titlesec. Impossible to tell more without additional info.

[jfbu]

ah sorry you do say you are using TeXLive 2018. Is that the case on both Linux and Windows ? it is not so frequent to use TeXLive on Windows.

[nioncode]

Yes, I use TeXLive 2018 on Windows and Linux. The problematic package is parskip, which is on version '2001/04/09' on my Linux machine, but on '2018/08/24 v2.0a' on Windows. Apparently, in later versions it does not add so much vertical space after sections.

I tried a few different things to work around this. At the moment, I have 'passoptionstopackages': r'''\usepackage{parskip}[=v1]''' in my conf.py to force parskip to behave like in previous versions to have a consistent behavior. Does this seem reasonable?

[jfbu]

hmm, very interesting. I need to check what was parskip version before the very recent update by none the less than Frank Mittelbach prominent LaTeX team member. I doubt very much he would have introduced backwards incompatible changes, but one never knows in interaction with other packages.

What you could try for the time being is to copy the Windows one, or fetch it from CTAN or if you are uneasy about unpacking the style file directly from this gist.

Then add it to your Sphinx project and add latex_additional_files = ['parskip.sty'] to your conf.py. Then this parskip will be added to the files in the latex build repertory.

But as the bug perhaps comes from interaction of parskip with a package like titlesec this might not be enough.

Curious to know the outcome.

[jfbu]

omg, I see strange changes indeed in this recent parskip, why does it patch the core section macros and titlesec ones? it is too late for me to investigate here, but perhaps there is a genuine LaTeX problem, that would be very surprising. It could be that I never noticed that layout change in Sphinx PDF between TL2017 and TL2018 updated. If really there is a problem, then we will need to ship Sphinx with the old parskip. And complain to LaTeX team...

[nioncode]

I don't really know if the new parskip actually fixes wrong behavior, I just noticed that it is different from the old one, because my document reflowed in ugly ways. If I'd add a few sentences here and there, then I guess the new one would look fine also (but the document would then look ugly on older versions).

With my conf.py entry from above you can at least force the behavior to be compatible with the old version to make the output consistent on both versions. I'd assume that many documents broke when parskip changed its behavior, I'm actually surprised that I did not find anyone mentioning this change when searching before. It is mentioned in the parskip manual though.

[jfbu]

The new parskip introduces new behaviour. I had seen it passing by but did not pay enough attention. I have reported it upstream.

I will re-insert the Bug tag, altough this is not a Sphinx bug. But only fix I see for now is to ship the old parskip with Sphinx and let the LaTeX writer copy it to all build repertories of all Sphinx projects :(.

[jfbu]

I tried a few different things to work around this. At the moment, I have 'passoptionstopackages': r'''\usepackage{parskip}[=v1]''' in my conf.py to force parskip to behave like in previous versions to have a consistent behavior. Does this seem reasonable?

It is a solution but it forces you to have two distinct conf.py this one being for Windows (with its more up-to-date LaTeX packages). And with this in conf.py you are tied to compile on very recent TeX installations only, breaking portability of your project sources.

I am sorry about inconvenience, and embarrassed about not having spotted yet the changes in output PDF from Sphinx. I do remember looking at parskip when I first saw it updated, but very superficially, it was completely obvious to me that whatever it did would be backwards compatible per default! I never imagined it could be such a complete breakage of PDF layouts! (and I have now lost one cycle of sleep, time to catch-up and get some rest...).

[nioncode]

Actually my change does not require two separate conf.py files. It works just fine on systems that only have the old version available. It looks like the version information is just ignored there.

EDIT: oh I just read the linked issue. It seems like it works on some TeX distributions, but not on others. Then I'll probably just drop the old parskip.sty into my project and let sphinx copy it to the latex build dir.

[jfbu]

Here is how our PDF documentation in PDF currently looks (current tip 221614654 of 1.8 branch):

And here is how the same bottompage (page 5, first page of Chapter 2) looks when I build locally a checkout of 1.8 branch at same commit checkout 221614654:

With a sharp eye you see the whitespace after section titles is reduced (as you reported), hence more material fits on this first page of second chapter (on 1.8).

Buildling locally (on a fully up-to-date TL2018) I get 391 pages, the RTD build (for v1.8, currently) has 401 pages, because, obviously, it is still with old parskip package.

Hence the pagebreaks are not at same location. Although, in itself this is not necessarily bad, because anyhow these pagebreaks are chosen by LaTeX at suitable places, and we are talking here not about typographical art but automated production of PDF from reST, markdown, or documented Python, C, C++, etc.., sources, it does means that the final PDF for the very same sources and Sphinx configuration and version depends on where it is build.

On my testing, only TL2017 will silently ignore the [=v1] version indication and use the parskip.sty (unmodified since ... 2001 !) it comes with (the old one, hence) without throwing an error.

When Read-the-docs starts to use TL2019 (or TL2018 as updated in September 2018) then suddenly ALL projects PDF documentations will change their page layouts from one day to the next.

I have not pondered really, perhaps the reduced spacing from new parskip is a good thing, but the point is that it creates an impredictability of PDF outcome and the initial issue you reported that one needs exact same TeX installations to get same PDFs. In LaTeX we are accustomed to mostly stable packages, and at Sphinx we make currently usage of rather well-established packages (until recently we supported TL2008 if I recall well).

Now, one could argue that Sphinx was at fault using this (tiny) package from 1989 which had received one update in 2001, as its documentation contained this warning

This package is no more than quick fix; the ‘proper’ way to achieve effects as far-reaching as this is to create a new class. An example class is to be found in the ntgclass set: artikel3.cls

The koma-script bundle classes and the memoir class all provide similar functionality, and their respective documentation files discuss the pros (such as they are) and cons of this approach.

But, then Sphinx should not have used the LaTeX team maintained standard classes article and book at all, if I correctly understand the reasoning behind the above remarks.

Anyway, usage of parskip.sty by Sphinx is certainly a very old decision, and we can only remove it at next major release and mention is as a breaking change. In these last 2 or 3 years of my LaTeX sphinx maintenance I have added a number of\noindent in various places so that even if a positive \parindent is used (which is the default when parskip.sty is not used), various things such as graphics inclusion remain backwards compatible. Thus (untested) not using parskip package will at least not create funny things, like material sticking into the margins.

Or, we ship the old parskip.sty which is as I said only method at our disposal to fix this issue in a backwards compatible way. In the past Sphinx shipped a number of packages because not all Linux distros had them by default in their TeX installs; little by little we have removed all of that, at the same time that we raised our requirement (TeXLive 2013, soon TeXLive 2015).

So this issue will be fixed in say around 2023, when Sphinx will require TeXLive 2019.

I wonder how many university thesis templates are broken by this parskip.sty change!

[jfbu]

Thanks for your detailed reporting about breakage of LaTeX by upstream change.