PDF Conversion
Explanation
The LaTeX exporter produces a package of LaTeX sources, not a PDF. Turning that package into a PDF means running a LaTeX engine over it, and XWiki ships none, so the work is handed to a converter: the exporter builds the package, the converter compiles it and returns the resulting index.pdf. Two converters come with the extension, and the latex.pdf.export.hint configuration property decides which one runs.
The Two Converters
| Converter | What it needs | When to use it |
|---|---|---|
| Docker — hint docker, the default | A Docker daemon the XWiki server can reach | Whenever Docker can be installed |
| Local process — hint process | A pdflatex executable installed on the XWiki server | Only when Docker cannot be installed |
Docker is both the default and the recommendation. It is more generic, since the LaTeX distribution and every package a document needs come with the image instead of having to be installed and kept up to date on the server; it is simpler to set up, since installing Docker is the whole of it; and it is more secure, because the conversion runs pdflatex with the shell-escape option, which lets a document execute commands, and under Docker that happens inside a throwaway container rather than on the server itself as the user XWiki runs as.
The first PDF export on a freshly set up server is much slower than every export after it: the Docker converter downloads the image it compiles in the first time it needs it, once, and reuses it from then on.
Why pdflatex Runs Twice
Both converters compile the package twice, and their default commands say so by naming pdflatex two times over.
The reason is LaTeX's, not XWiki's. The first pass discovers the headings as it walks the document and writes them to a side file; only the second pass can read that file back and put the table of contents in place. A converter left to run a single pass produces a PDF whose table of contents is missing, or still shows what the previous run collected. The same holds when you compile an exported package by hand.
When the PDF Entry Is Missing
The PDF (LaTeX) entry of the export menu is offered only when the configured converter reports itself ready. The plain LaTeX entry, which gives the sources, is always offered.
What "ready" means depends on the converter:
- The Docker converter pings the Docker daemon. No reachable daemon, no PDF entry — which is what an administrator sees when Docker is not installed or the server cannot talk to it.
- The local process converter always reports itself ready. It does not check that pdflatex exists, so with hint process the entry is offered whether or not the executable is there, and a missing executable surfaces later as a failed export job rather than as a missing menu entry.
The check runs once, when the extension starts. Making Docker available on a running server does not bring the entry back on its own: restart XWiki.
A converter that is offered and then fails is the other problem. The export's Job log says why, and Enable PDF Conversion Debug Logging puts the whole compilation output in it.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
