cleveref-related pandoc-xnos issues

[elcorto]

This is not a docwatch problem as such, but is caused by the pandoc-related tooling we support. Therefore it bites us in practice and so we record the issue here.

Versions

$ pip list | grep pandoc-
pandoc-eqnos             2.5.0
pandoc-fignos            2.4.0
pandoc-secnos            2.2.2
pandoc-tablenos          2.3.0
pandoc-xnos              2.5.0

It seems that all xnos filters assume that cleveref is loaded but they don't load it. Not sure when this started, thing used to work just fine until recently.

The problem shows up with pandoc 2 and 3, so it is probably related to xnos and/or our TeX stack (TeX Live 2023.20231207) maybe.

pandoc 2

$ cd /path/to/docwatch/examples

$ pandoc --version
pandoc 2.19.2
Compiled with pandoc-types 1.22.2.1, texmath 0.12.5.2, skylighting 0.13,
citeproc 0.8.0.1, ipynb 0.2, hslua 2.2.1
Scripting engine: Lua 5.4

$ docwatch -c -- md.md

[...]

pandoc-eqnos: Wrote the following blocks to header-includes.  If you
use pandoc's --include-in-header option then you will need to manually
include these yourself.

    %% pandoc-eqnos: disable brackets around cleveref numbers
    \creflabelformat{equation}{#2#1#3}

[...]

Error producing PDF.
! Undefined control sequence.
l.187 \creflabelformat

\creflabelformat is a command from cleveref, which doesn't seem to be loaded.

pandoc 3

pandoc 3.1.3
Features: -server +lua
Scripting engine: Lua 5.4

make pandoc 3 work with pandoc-xnos

pandoc-xnos claims that it can't work with pandoc 3:

$ docwatch -c -- md.md

[...]

  File "/home/elcorto/soft/lib/python3.11/site-packages/pandocxnos/core.py", line 179, in _get_pandoc_version
    raise RuntimeError(msg)
RuntimeError: Cannot understand pandocversion=3.1.3
Error running filter pandoc-xnos:
Filter returned error status 1

But this can be fixed by tomduck/pandoc-xnos#29:

-pattern = re.compile(r'^[1-2]\.[0-9]+(?:\.[0-9]+)?(?:\.[0-9]+)?$')
+pattern = re.compile(r'^[1-3]\.[0-9]+(?:\.[0-9]+)?(?:\.[0-9]+)?$')

After that we see the same \creflabelformat error.

Solution

In both cases (pandoc 2 and 3) the workaround is to load cleveref like so in the LaTeX header

diff --git a/examples/md.md b/examples/md.md
index a504541..54099b4 100644
--- a/examples/md.md
+++ b/examples/md.md
@@ -10,6 +10,11 @@ tablenos-plus-name: Tab.
 header-includes:
 - |
   ```{=latex}
+  \usepackage{hyperref}
+  % "capitalise" is what "xnos-capitalise: true" does. If you don't use this
+  % setting, then just \usepackage{cleveref}.
+  \usepackage[capitalise]{cleveref}
+
   \usepackage{xspace}

   % only with lualatex or xelatex

The reason for also loading hyperref is that else we get

! Package cleveref Error: cleveref must be loaded after hyperref!.

Note that each xnos filter will insert its TeX code into the processing chain only it if detects that it will be used, e.g. if you do nothing with equation numbers, then pandoc-eqnos will also insert no code, which means you may not see this error until you use features supported by a filter, even if you have set

filters=
    pandoc-xnos

in ~/.config/docwatch/docwatch.conf. In particular, starting with an empty file by just calling docwatch will always work.