Legacy Documents and TeX Live Docker Images

Over the past few years there have been a number of major changes to the LaTeX kernel that have unfortunately broken code in old packages, classes and documents. The changes are beneficial to new documents and packages, but before the introduction of the new kernel features it was necessary for packages to hack the old kernel internal commands in order to achieve the desired result and, for the most part, the instabilities come from these hacks.

Some of the affected packages have been updated to work with the new kernels, but in some cases the original hack may have been too complicated to untangle or the package author may no longer be available to update the code.

My own packages have been affected, starting with flowfram.sty in 2015, then datatool in 2019 (that had a knock-on problem for mfirstuc.sty, which requires datatool-base.sty and glossaries.sty, which relies on mfirstuc), and jmlrbook.cls in 2020.

So what happens if you have a legacy document that compiled without a problem when it was first created but now goes wrong? This may not necessarily mean than an error occurs, but it could silently cause unexpected output.

For example, when I wrote LaTeX for Administrative Work (volume 3 of the Dickimaw LaTeX series) I had TeX Live 2014 installed. Below is an image of page 35 (from the A4 PDF version). The page starts with the page header, there is then a figure (which has floated to the top of the page) and then the page body. All looks fine.

Image of page 35 with correctly typeset content.
Page 35 Built with TeX Live 2014

However, if I rebuild the document with a newer TeX distribution then the page content becomes mangled, as shown below. The figure is now at the top of the page, and the page header has been shunted down so that it overlaps the figure caption. The text body height doesn’t take the figure into account, which causes the text to overflow the bottom of the page.

Image of page 35 with textual content shunted down the page.
Page 35 Built with TeX Live 2021

The hack of adding \def\f@depth{1sp} suggested in bug report #105 works in some cases, but unfortunately in this case it leads to the “Too many unprocessed floats” error. So, until I can find a reliable fix for flowfram.sty, how can I rebuild this document? I do have some old versions of TeX Live installed, but not that far back.

The solution lies with the Docker images provided by the Island of TeX. Docker basically allows you to run an application inside an isolated container. So, instead of hunting for my TeX Live 2014 DVD and installing TL2014, I can fetch the Docker image and build my document inside a container.

If you don’t already have Docker installed, you will first need to install it. Once it’s installed, you can use the docker command line tool. On Unix-like systems, you may need to use sudo. You can view the currently installed Docker images using docker images (or sudo docker images).

I need the TeX Live 2014 image so I have to pull the TL2014-historic release from the Island of TeX:

sudo docker pull registry.gitlab.com/islandoftex/images/texlive:TL2014-historic

Now I need to change to the directory (cd) where my document source is located (change the path as applicable):

cd path/to/directory

If my document source code is in the file called document.tex and I would ordinarily compile it using:

pdflatex document.tex

then when I want to compile it inside a TL2014 Docker image container I would need to do:

sudo docker run -i --rm --name latex -v "$PWD":/usr/src/app -w /usr/src/app registry.gitlab.com/islandoftex/images/texlive:TL2014-historic pdflatex document.tex

In this case, my document source file is called admin-report.tex and the build process is rather complicated as it consists of multiple pdflatex, bibtex, makeglossaries and makeindex invocations. Rather than using docker run for each step, it’s simpler to use an automated process, such as arara. First I need to ensure that I have the appropriate arara directives at the start of admin-report.tex:

% arara: pdflatex
% arara: bibtex
% arara: makeglossaries
% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
% arara: makeindex: { style: admin-index.ist, options: -c }
% arara: pdflatex
% arara: pdflatex

Now I just need one docker run instance:

sudo docker run -i --rm --name latex -v "$PWD":/usr/src/app -w /usr/src/app registry.gitlab.com/islandoftex/images/texlive:TL2014-historic arara --verbose admin-report.tex

This is rather lengthy to type, so I wrote a simple bash script called dockerbuild:

#!/bin/sh

docker run -i --rm --name latex -v "$PWD":/usr/src/app -w /usr/src/app registry.gitlab.com/islandoftex/images/texlive:TL2014-historic arara --verbose "$@"

So I can now just do:

sudo ./dockerbuild admin-report

Unfortunately using sudo means that I end up with files owned by root, but this can be fixed by adding chown to the bash script (change the username and groupname to your own):

chown username:groupname `basename "$@" .tex`.*

There were two further problems. Firstly, the version of flowfram.sty bundled with TeX Live 2014 doesn’t have a couple of options used by the document. This is probably because I added those options while I was working on the book but I uploaded the package to CTAN after the version of TL 2014 captured in the Docker image. I needed to copy the newer v1.17 into my current directory to ensure the document compiled correctly.

Secondly, I can’t input files on my hard drive that are outside of the current working directory from inside the container. Volume 3 cross-references the previous two books in the series using:

\externaldocument[nov-]{../novices/novices-report}
\externaldocument[thesis-]{../thesis/thesis-report}

This picks up the cross-referencing information from the aux files of volumes 1 and 2, but this won’t work inside the Docker container. Instead, I need to copy those files into my current directory. (Note that symbolic links to files outside the current directory won’t work.)

Ideally the best solution is for me to find a way to fix all my affected packages, but this is proving to be non-trivial. The historic TeX Live Docker images at least provide a workaround.

TeX Live and Fedora

I’ve been using TeX Live on Fedora for years, but today I encountered an odd error when trying to perform the usual sudo tlmgr update package. I tried an Internet search of the error message but it didn’t provide any helpful clues. I finally worked out what had happened and, since it’s possible someone else might stumble on the same thing, I thought it might be useful to post about it in case it helps others.

First a little background information to supply some context. I normally use dnf to install or update software on Fedora, but not when it comes to TeX because I have found in the past that the Linux distros tend to have outdated TeX packages. Instead, I install TeX Live from the DVD (which I automatically receive as a joint member of UK TUG and TUG) as I have an iffy broadband connection, and I also have to update the TeX Live distributions for other family members. It’s easy to slap the DVD in the drive and set the installer going regardless of whether the computer has Linux or Windows. On my own device, I keep the TeX Live installations from the previous couple of years as it’s useful to be able to switch to an older version when trying to investigate a bug that has appeared with a new TeX Live release. (I have a symbolic link /usr/local/texlive/default that points to the release I want to use. All I need to do is change the link to switch to a different release.)

I don’t like automatic updates (it can be confusing if an update occurs without my noticing and causes an unexpected conflict) so I just periodically run sudo tlmgr update --all but today this resulted in an unexpected error. (The message suggests it’s a warning but the process fails.)

*** WARNING ***: Performing this action will likely destroy the Fedora TeXLive install on your system.
*** WARNING ***: This is almost NEVER what you want to do.
*** WARNING ***: Try using dnf install/update instead.
*** WARNING ***: If performing this action is really what you want to do, pass the "ignore-warning" option.
*** WARNING ***: But please do not file any bugs with the OS Vendor.

As is often the case, the problem is obvious in hindsight but it flummoxed me for a while. Why was the TeX Live manager suddenly telling me to use dnf when I’d installed it from the DVD? It had worked fine the last time (not that long ago), so what had changed since then? A few days ago I’d upgraded to Fedora 31.

It turned out that I now have an extra TeX Live installation that I didn’t know about in /usr/share/texlive/ with its own tlmgr in /bin (which is a symbolic link to /usr/bin). To add to the confusion my normal user PATH has /usr/local/texlive/default/bin/x86_64-linux near the start of the list but the /etc/sudoers file had it at the end:

Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/texlive/default/bin/x86_64-linux

This means that when I use TeX as a normal user it’s picking up the installation from the DVD, but with sudo it’s picking up the other installation, which requires dnf rather than tlmgr to update TeX packages. The question is, how did that other TeX Live installation suddenly appear?

Some years ago I installed texlive-dummy to satisfy dependencies in the event that I had to install software that required a TeX distribution. As far as I can tell, that texlive-dummy RPM no longer exists. My guess is that when I upgraded to Fedora 31, the upgrade process detected the TeX Live dependency, but texlive-dummy had disappeared, so it installed the complete TeX Live distribution instead. For now, I’ve simply edited the /etc/sudoers file so that /usr/local/texlive/default/bin/x86_64-linux is listed first in the path.