Debugging filters

[fuhrmanator]

I am using the PlantUML filter.

The java and plantuml.jar parts are working, but the expected (generated) .svg files are not found, either in the preview or render commands:

GET: /chapters/04-MDD.html
  /chapters/b74d89750c84f84c6c71edc71c27ba78f0cdb84a.svg (404: Not Found)

LaTeX Error: File `b74d89750c84f84c6c71edc71c27ba78f0cdb84a.svg' not found.

How can I turn on debugging messages to see when the filter is invoked (and the output of the java command, etc.)? Is it possible from the .yaml file?

[jjallaire]

You can set log-level: debug and see if that gives you any additional diagnostics.

Note that we are in the process of implementing native support for graphviz and mermaid diagrams (not sure if that will meet your requirements?)

[fuhrmanator]

Thanks - I'll give it a shot.

Thanks for letting me know about graphviz and mermaid. I hope you can consider PlantUML, too (I'm heavily invested in it).

[jjallaire]

We'll probably leave PlantUML to extensions (as the Java dependency will make it hard to run out of the box for a lot of people)

[fuhrmanator]

Alright, I used quarto render --log-level debug to get some more info, but it wasn't detailed inside the filter.

I finally wrote some debugging messages to stderr inside the diagram-generator.lua code, and I was able to verify that the SVG output for the file is indeed produced, but it's never written to disk as far as I can see. I think typical filters just modify the AST, but I wonder if quarto supports ones that generate files? I even tried running it in a terminal with admin privs (windows) but the files are not saved.

The problem is actually the same for graphviz which is supported by the same filter.

Is there a way to see the underlying pandoc command that is generated by quarto?

I could put a minimal working example up on GitHub if someone could look at it. I'm really excited to switch my textbook over to quarto if I can get PlantUML to work 🚀

[fuhrmanator]

I got it to work partially. The HTML preview will make data:image/svg... links (embedding the svg in the URI) if I turn on the self-contained: true option:

format:
  html:
    theme: cosmo
    self-contained: true
  pdf:
    documentclass: scrbook

This allows me to see the result in HTML, and it looks awesome!

But, this doesn't work for LaTeX; it's still looking for local .svg files.

[jjallaire]

We print the parameters sent to pandoc during render (you'll see your filter in the filters entry).

One thing to be aware of is that Quarto runs pandoc in the same working directory as the document, so if the Lua filter has expectations about where its data files (or jar file) live relative to the current working directory that could cause a problem.

Note that AFAIK LaTeX won't utilize svg files (you need to create pdfs, pngs, or tkiz graphics)

[fuhrmanator]

Indeed I see the filter on the list, as you said. But there are no messages when it's invoked or anything.

The filter is working properly with vanilla pandoc, e.g., if I do this command I get a PDF that looks good for both PlantUML and GraphViz inline (only the cross references with @ don't work, which is something I suspect quarto is managing?):

pandoc --metadata-file=_quarto.yml index.qmd --lua-filter=filters\diagram-generator.lua --output=test.pdf

It's true that SVG isn't normally kosher in LaTeX (I've always used PDF figures), but the Pandoc chain figures it out somehow to create that PDF - it's precisely the debugging info that is missing. I'm wondering if maybe since the xetex steps are being done in quarto, it's changing/breaking something wrt that seamless conversion.

[jjallaire]

Yeah that could be. You can turn off Quarto's PDF compilation pipeline with latex-auto-mk: false (https://quarto.org/docs/output-formats/pdf-engine.html#latexmk)

[fuhrmanator]

Sorry for the noise @jjallaire -- I finally realized these discussions are like SO with answers, etc. Never used it on GitHub before.

[fuhrmanator]

I got a good PDF finally by using pdf-engine: latexmk. It seems all the other options couldn't find the .svg files that were supposed to be generated by the filter.

format:
  pdf:
    pdf-engine: latexmk

The latex-auto-mk option setting seems to make no difference (true or false).

For reference, I used quarto render --to pdf to create the pdf, and it goes into the _book directory.

It's working nicely so far (although I don't really understand how I fixed it, apart from trying the different options). Thanks for your help! 👍🏼

[jjallaire]

perhaps latexmk has some additional logic for handing this scenario? In any case, glad this is all working now!