Latest news 2024-10-15: New blog post: Tales for Our Times Book Launch.

Dickimaw Books Blog RSS feed

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.

Nicola Talbot 2021-09-06 📂 (La)TeX 🔖 Docker TeX Live

Next Post

image of dickimaw parrot with cookies in cloudsOnce upon a time, a little parrot decided to migrate across the vast ocean to the cloud lands, with nothing more than a handful of cookies. The Dickimaw Books site has migrated to a new web hosting provider and this is the story of its journey.
Nicola Talbot 2019-09-15 📂 Site 🔖 Migration

Previous Post

image of dickimaw parrot with cookies in cloudsOnce upon a time, a little parrot decided to migrate across the vast ocean to the cloud lands, with nothing more than a handful of cookies. The Dickimaw Books site has migrated to a new web hosting provider and this is the story of its journey.
Nicola Talbot 2019-09-15 📂 Site 🔖 Migration

Recent Posts

Tales for Our Times Book Launch
Tales for Our TimesThe book launch for the anthology Tales for Our Times, written by Norfolk writing group Ex-Cathedra and published by Smokehouse Press, took place in the Norfolk and Norwich Millennium Library at noon on World Homeless Day (10th October 2024). All profits from the sale of this book will be used to help raise funds to support Norwich-based St Martins Housing Trust in their work to help the homeless into independent living. The book launch included a talk from Dr Jan Sheldon, SEO of St Martins, two readings by authors of the book, and a presentation to the library.
Tales for Our Times: Raising Funds and Awareness for St Martins Housing Trust
Tales for Our TimesTales for Our Times is an anthology of forty stories featuring loss and hope, dreams of love and belonging, biography and science fiction and adventure. Written by Norfolk-based writing group Ex-Cathedra and published by Smokehouse Press, the book will be launched on World Homeless Day 10th October 2024 midday at the Norwich and Norfolk Millennium Library. All profits from the sale of this book will be used to help raise funds to support Norwich-based St Martins Housing Trust in their work to help the homeless into independent living.
The Briefcase: a crime fiction short story
The Briefcase book coverConvinced that his secretive wife, Annie, is cheating on him, Aide meets an attractive young goth at the pub who helps him pick the lock of Annie’s briefcase to search for incriminating evidence.
Smile for the Camera: a cybercrime story
Smile for the Camera book cover.Evelyn, a CCTV operator, sees too much information while she monitors a store’s self-service checkout tills in this cybercrime short story about identity theft.
Nicola Talbot 2024-04-12 (updated 2024-10-31) 📂 Crime Fiction 🔖 News Smile for the Camera
Read an Ebook Week Sale 2024
Ebook coversThe DRM-free ebook retailer SmashWords “Read an Ebook Week” Sale is on from 3rd–9th March 2024. My crime novel “The Private Enemy” and children’s illustrated story “The Foolish Hedgehog” both have a 50% discount and my crime fiction short story “I’ve Heard the Mermaid Sing” and cybercrime fiction short story “Unsocial Media” both have a 100% discount (i.e. free!) for the duration of the sale. Did you know that you can gift ebooks on SmashWords?
End of Year Ebook Sale
Book coversThe DRM-free ebook retailer SmashWords has their end of year sale from 15th December 2023 to 1st January 2024. My crime novel “The Private Enemy” and children’s illustrated story “The Foolish Hedgehog” both have a 50% discount and my crime fiction short story “I’ve Heard the Mermaid Sing” and cybercrime fiction short story “Unsocial Media” both have a 100% discount (i.e. free!) for the duration of the sale. Did you know that you can gift ebooks on SmashWords?
Search for:
Search Tips

📂 Categories

Autism
Books
Children’s Illustrated Fiction
Illustrated fiction for young children: The Foolish Hedgehog and Quack, Quack, Quack. Give My Hat Back!
Creative Writing
The art of writing fiction, inspiration and themes.
Crime Fiction
The crime fiction category covers the crime novels The Private Enemy and The Fourth Protectorate and also the crime short stories I’ve Heard the Mermaid Sing and I’ve Heard the Mermaid Sing.
Fiction
Fiction books and other stories.
Language
Natural languages including regional dialects.
(La)TeX
The TeX typesetting system in general or the LaTeX format in particular.
Music
Norfolk
This category is about the county of Norfolk in East Anglia (the eastern bulgy bit of England). It’s where The Private Enemy is set and is also where the author lives.
Security
Site
Information about the Dickimaw Books site.
Speculative Fiction
The speculative fiction category includes the novel The Private Enemy (set in the future), the alternative history novel The Fourth Protectorate, and the fantasy novel Muirgealia.

🔖 Tags

Account
Alternative History
Sub-genre of speculative fiction, alternative history is “what if?” fiction.
book samples
Bots
Conservation of Detail
A part of the creative writing process, conservation of detail essentially means that only significant information should be added to a work of fiction.
Cookies
Information about the site cookies.
Dialect
Regional dialects, in particular the Norfolk dialect.
Docker
Education
The education system.
Ex-Cathedra
A Norfolk-based writing group.
Fantasy
Sub-genre of speculative fiction involving magical elements.
File formats
Hippochette
A pochette (pocket violin) with a hippo headpiece.
I’ve Heard the Mermaid Sing
A crime fiction short story (available as an ebook) set in the late 1920s on the RMS Aquitania. See the story’s main page for further details.
Inspirations
The little things that inspired the author’s stories.
Linux
Migration
Posts about the website migration.
Muirgealia
A fantasy novel. See the book’s main page for further details.
News
Notifications
Online Store
Posts about the Dickimaw Books store.
Quack, Quack, Quack. Give My Hat Back!
Information about the illustrated children’s book. See the book’s main page for further details.
Re-published
Articles that were previously published elsewhere and reproduced on this blog in order to collect them all together in one place.
Sale
Posts about sales that are running or are pending at the time of the post.
Site settings
Information about the site settings.
Smile for the Camera
A cybercrime short story about CCTV operator monitoring a store’s self-service tills who sees too much information.
Story creation
The process of creating stories.
TeX Live
The Briefcase
A crime fiction short story (available as an ebook). See the story’s main page for further details.
The Foolish Hedgehog
Information about the illustrated children’s book. See the book’s main page for further details.
The Fourth Protectorate
Alternative history novel set in 1980s/90s London. See the book’s main page for further details.
The Private Enemy
A crime/speculative fiction novel set in a future Norfolk run by gangsters. See the book’s main page for further details.
Unsocial Media
A cybercrime fiction short story (available as an ebook). See the story’s main page for further details.
World Book Day
World Book Day (UK and Ireland) is an annual charity event held in the United Kingdom and the Republic of Ireland on the first Thursday in March. It’s a local version of the global UNESCO World Book Day.
World Homeless Day
World Homeless Day is marked every year on 10 October to draw attention to the needs of people experiencing homelessness.