Wiki source code of Export Package
Last modified by Vincent Massol on 2026/08/30 19:44
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Exporting to LaTeX produces a zip, and that zip is a small LaTeX project rather than one long file. For each page it exports, the output filter builds the page's XDOM, hands it to the LaTeX renderer, and writes the result as a file of its own; it then adds an ##index.tex## that ties those files together. Everything a compiler needs is inside the zip, so the package builds anywhere a LaTeX distribution is installed. That filter can also be driven from code, with [[parameters of its own>>doc:documentation.extensions.dev.latex.export-package.filter-parameters.WebHome]]. | ||
| 2 | |||
| 3 | {{plantuml}} | ||
| 4 | @startuml | ||
| 5 | !theme bluegray | ||
| 6 | skinparam componentStyle rectangle | ||
| 7 | |||
| 8 | component "**index.tex**\n//the root document://\n//preamble, cover page, TOC,//\n//one \\include per page file//" as INDEX | ||
| 9 | component "**pages/<wiki>/<space>/<page>-<hash>.tex**\n//one complete LaTeX document//\n//per exported page//" as PAGES | ||
| 10 | component "**files/attachments/<wiki>/<space>/<page>/<name>-<hash>.<ext>**\n//every attachment and image//\n//the exported pages reference//" as ATT | ||
| 11 | component "**files/downloaded/<host>/<hash>/<name>**\n//images referenced by an external URL,//\n//fetched at export time//" as DL | ||
| 12 | |||
| 13 | INDEX --> PAGES : \\include | ||
| 14 | PAGES --> ATT : \\includegraphics | ||
| 15 | PAGES --> DL : \\includegraphics | ||
| 16 | @enduml | ||
| 17 | {{/plantuml}} | ||
| 18 | |||
| 19 | == What the Package Holds == | ||
| 20 | |||
| 21 | |=Entry|=What it is | ||
| 22 | |##index.tex##|The document to compile. It carries the preamble, whatever the export options asked for around the content, and one ##\include## per page file. | ||
| 23 | |##pages/##|One LaTeX file per exported page. | ||
| 24 | |##files/attachments/##|Every attachment and image the exported pages reference, copied out of the wiki. | ||
| 25 | |##files/downloaded/##|Images the pages display from an external address, fetched while the export runs. | ||
| 26 | |||
| 27 | The last entry appears only when a page shows an image that lives outside the wiki. An image is always downloaded into the package, because a compiler cannot go and get it later; an ordinary link is left pointing where it pointed. | ||
| 28 | |||
| 29 | == Every Page File Is a Document of Its Own == | ||
| 30 | |||
| 31 | A file under ##pages/## is not a fragment. It has its own ##\documentclass##, its own preamble and its own ##\begin{document}##, exactly as if that single page had been exported alone. That is why ##index.tex## loads the ##standalone## package before including them: ##standalone## keeps the body of an included document and drops its preamble. | ||
| 32 | |||
| 33 | Two things follow. Any page file compiles on its own, which is the quickest way to see what one page produced. And everything the [[export options>>doc:documentation.extensions.user.latex.export-page.export-options.WebHome]] wrap around the content, from the cover page to the table of contents and the lists of figures and tables, is written into ##index.tex## alone, so [[compiling the package>>doc:documentation.extensions.user.latex.convert-package-pdf.WebHome]] means compiling that file. | ||
| 34 | |||
| 35 | == Why the Paths Look Like That == | ||
| 36 | |||
| 37 | The names inside the package are not the wiki's names. Each part of a path is cleaned first: spaces go, the characters LaTeX reads as markup go with them, and anything non-ASCII is percent-encoded before the percent signs are removed in turn. What is left is a path that can sit inside ##\include{}## or ##\includegraphics{}## without being taken for markup. | ||
| 38 | |||
| 39 | That cleaning is lossy, so two different names can collapse onto the same one. The hash of the original name, inserted before the extension, is what keeps them apart, which is how an attachment named ##späce percent%dot.some.png## arrives as ##spC3A4cepercentdot.some-1407747243.png##. | ||
| 40 | |||
| 41 | Every reference in the package is relative to the package root. A compiler run from anywhere else will not find the page files or the images. | ||
| 42 | |||
| 43 | == What Does Not Travel == | ||
| 44 | |||
| 45 | Links out of a page are rewritten, not resolved into the package. A link to another wiki page becomes an absolute address of that wiki, rendered as an ##\href##, and it stays one even when the page it points at is in the same package; the package holds no cross-references between its own pages. A link a page makes to itself keeps its label and loses its link altogether. |
