Wiki source code of PDF Conversion
Last modified by Vincent Massol on 2026/08/30 19:36
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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>>doc:documentation.extensions.admin.latex.configuration.WebHome]] decides which one runs. | ||
| 2 | |||
| 3 | == The Two Converters == | ||
| 4 | |||
| 5 | |=Converter|=What it needs|=When to use it | ||
| 6 | |[[Docker>>doc:documentation.extensions.admin.latex.pdf-conversion.docker.WebHome]] — hint ##docker##, the default|A Docker daemon the XWiki server can reach|Whenever Docker can be installed | ||
| 7 | |[[Local process>>doc:documentation.extensions.admin.latex.pdf-conversion.local-process.WebHome]] — hint ##process##|A ##pdflatex## executable installed on the XWiki server|Only when Docker cannot be installed | ||
| 8 | |||
| 9 | 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. | ||
| 10 | |||
| 11 | 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. | ||
| 12 | |||
| 13 | == Why pdflatex Runs Twice == | ||
| 14 | |||
| 15 | Both converters compile the package **twice**, and their default commands say so by naming ##pdflatex## two times over. | ||
| 16 | |||
| 17 | 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>>doc:documentation.extensions.user.latex.convert-package-pdf.WebHome]]. | ||
| 18 | |||
| 19 | == When the PDF Entry Is Missing == | ||
| 20 | |||
| 21 | 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. | ||
| 22 | |||
| 23 | What "ready" means depends on the converter: | ||
| 24 | |||
| 25 | * 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. | ||
| 26 | * 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. | ||
| 27 | |||
| 28 | 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. | ||
| 29 | |||
| 30 | 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>>doc:documentation.extensions.admin.latex.pdf-conversion.debug-logging.WebHome]] puts the whole compilation output in it. |
