keyval Error: alt undefined when trying to build pandoc-crossref demo

[sdbbs]

I have been using pandoc-crossref with pandoc in quite a while, and it worked fine for me. However, I wanted to update today, and it broke.

I installed pandoc on Windows 10 with the MSI installer; and then I copied pandoc-crossref.exe in the same folder where pandoc.exe is. Btw, I could not find anywhere in the main README that the idea of unpacking the 7z file is to get a pandoc-crossref.exe which should then be copied in the pandoc.exe installation directory - please add that.

Anyways, since I'm a user of MSYS2, that is where I usually run pandoc, and it seems my path is set up properly:

$ pandoc --version
pandoc 3.8.3
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: C:\Users\user\AppData\Roaming\pandoc
Copyright (C) 2006-2025 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

$ pandoc-crossref.exe --version
pandoc-crossref v0.3.22 git commit c927e7341fa84bce65897e79511eff202c6a6c5e (HEAD) built with Pandoc v3.8.3, pandoc-types v1.23.1 and GHC 9.8.4

So, that seems fine. Then I downloaded the https://github.com/lierdakil/pandoc-crossref/tree/master/docs/demo directory, and I'm trying to run make pdf in it:

$ make pdf
pandoc --number-sections -t latex --filter pandoc-crossref -o output.pdf demo.md
Error producing PDF.
! Package keyval Error: alt undefined.

See the keyval package documentation for explanation.
Type  H <return>  for immediate help.
 ...

l.166 ...s64/tmp/media-8e356f01ab136ab2/img1.jpg}}

make: *** [Makefile:4: pdf] Error 43

I don't understand where that media-8e356f01ab136ab2 came from, there is no such thing in the .tex file - it certainly does not appear in the output.latex file:

$ make latex
pandoc --number-sections -t latex --filter pandoc-crossref -o output.latex demo.md
pandoc --number-sections -t latex --filter pandoc-crossref -o output-chapters.latex demo.md --top-level-division=chapter
pandoc --number-sections -t latex --filter pandoc-crossref -o output-cref.latex demo.md -M cref=True
pandoc --number-sections -t latex --filter pandoc-crossref -o output-listings.latex demo.md -M listings --syntax-highlighting=idiomatic

$ grep img1.jpg output.latex
\pandocbounded{\includegraphics[keepaspectratio,alt={A figure}]{img1.jpg}}
\pandocbounded{\includegraphics[keepaspectratio,alt={First figure}]{img1.jpg}}
\pandocbounded{\includegraphics[keepaspectratio,alt={Unlabelled image}]{img1.jpg}}
\begin{subfigure}{1.0\linewidth}\pandocbounded{\includegraphics[keepaspectratio,alt={Subfigure a}]{img1.jpg}}\caption{Subfigure
\begin{subfigure}{1.0\linewidth}\pandocbounded{\includegraphics[keepaspectratio,alt={Subfigure b}]{img1.jpg}}\caption{Subfigure
\begin{subfigure}{0.495\linewidth}\pandocbounded{\includegraphics[keepaspectratio,alt={Subfigure a}]{img1.jp}}\caption{Subfigure

What is going on, and how can I get the demo build to work?

[sdbbs]

I eventually used Mistral vibe to analyze, and it found the error:

I can see the issue! The problem is that pandoc-crossref is generating \includegraphics commands with an alt parameter, but your LaTeX installation (TeX Live 2020) doesn't support the alt key in the keyval package for the graphicx package.

This is a compatibility issue. The alt key was introduced in newer versions of the graphicx package. Let me check what version of graphicx you have and see if we can work around this.

So now I've installed TexLive 2025, but I still cannot confirm whether that was that, because now I get:

$ make pdf
pandoc --number-sections -t latex --filter pandoc-crossref -o output.pdf demo.md
Error producing PDF.
! LaTeX Error: File `footnote.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name:
! Emergency stop.
<read *>

l.87 \makesavenoteenv

make: *** [Makefile:4: pdf] Error 43

... but I have no idea where this footnote.sty could be - since my tlmgr cannot find a footnote package:

C:\WINDOWS\system32>tlmgr install footnote
tlmgr.pl: package repository https://mirrors.dotsrc.org/ctan/systems/texlive/tlnet (not verified: gpg unavailable)
tlmgr.pl install: package footnote not present in repository.
tlmgr.pl: action install returned an error; continuing.
tlmgr.pl: An error has occurred. See above messages. Exiting.

EDIT: that footnote.sty one is in tlmgr install mdwtools, and with a couple of more packages, I got make pdf of the demo to work.

[lierdakil]

Glad to hear you've resolved it eventually. Sorry if it was less straightforward than necessary.

Yeah, apparently Pandoc started including alt at some point, you'll have to dig through its changelog if you want to find out when exactly. PDF being produced through LaTeX by default is expected.

should then be copied in the pandoc.exe installation directory

Actually, not really? Anywhere where Pandoc can find it is fine, be it somewhere in PATH, cwd, etc. This is explained in pandoc user guide, see https://pandoc.org/MANUAL.html#option--filter.

If you could open a PR at least drafting the changes you believe are necessary, that would help quite a bit, thanks in advance.

[sdbbs]

Thanks @lierdakil :

should then be copied in the pandoc.exe installation directory

Actually, not really? Anywhere where Pandoc can find it is fine, be it somewhere in PATH, cwd, etc. This is explained in pandoc user guide, see https://pandoc.org/MANUAL.html#option--filter.

Ah, OK - I was not aware of that; I must have followed some tutorial some years ago, that advised placement in the pandoc installation directory; so this time I just followed the example without thinking. Good to know in any case!

If you could open a PR at least drafting the changes you believe are necessary, that would help quite a bit, thanks in advance.

It ended up just being a single sentence in the README, here it is: #501