Migrating from LaTeX / A report designer or markup toolchain
Migrating off LaTeX, and what you give up in typesetting
A typesetting system with its own language and a compilation step, where the migration is honest about losing typographic quality in exchange for everything else.
What ports and what does not
The data and the document's structure as a concept. Nothing else. LaTeX is a language, the templates are programs, and the packages they load implement layout that has no counterpart. This is the migration where the honest answer is most often not to: if the document is a paper, a thesis or a book with mathematics in it, LaTeX is better at that than a browser engine and will remain so. Where it makes sense is the case LaTeX gets used for by accident, a business document that ended up in LaTeX because somebody in the team knew it, and where the toolchain, the container and the compilation step cost more than the typography is worth.
What the call becomes
The pdflatex or xelatex invocation, usually run twice so cross-references resolve, becomes a single POST to /v1/pdf with html. The double compilation disappears, and so does the container carrying a distribution, the package management and the log parsing that every LaTeX pipeline grows.
Side by side
The old shape and the new one, with the parts that have no counterpart called out in comments rather than quietly omitted.
# Before
pdflatex -interaction=nonstopmode invoice.tex
pdflatex -interaction=nonstopmode invoice.tex # again, for references
# After
curl -X POST https://api.pdfpipe.xyz/v1/pdf \
-H "Authorization: Bearer $PDFPIPE_KEY" \
-H "Content-Type: application/json" \
-d '{ "html": "<!doctype html>...", "options": { "format": "A4" } }'
# Be honest about what is lost, because some of it is not recoverable:
# the paragraph-level line breaking algorithm, which optimises a whole
# paragraph rather than a line at a time, and which is why justified
# LaTeX looks better than justified anything else
# mathematical typesetting
# the bibliography and citation toolchain
# fine-grained control over spacing and penalties
#
# And what is gained:
# no distribution in the container, no package management, no second
# compilation pass, no log parsing to find out whether it worked
# a template a web developer can edit
# the whole of CSS for layout that is not typographicThe CSS delta, in both directions
What the old engine accepted that a current one does not, and what it refused that a current one wants. The second direction is the one people forget, and it is where the value of the migration is.
- Nothing to migrate, and one real loss to acknowledge: line breaking. LaTeX breaks a paragraph as a whole and a browser breaks it a line at a time, which is why justified text is visibly better in LaTeX. Setting text ragged right in the new document is usually the better answer to that than trying to close the gap.
- Mathematical content has no CSS counterpart of comparable quality and needs a different approach entirely.
- Cross-references and the bibliography toolchain have no counterpart. Numbering can be done with CSS counters; citations cannot.
- Everything else in layout is easier, and the whole of CSS is available where LaTeX needed a package.
What changes without anything erroring
The dangerous list. Each of these produces a different document and no diagnostic, so none of them are caught by a test that only checks the render succeeded.
- Everything visual, because it is a rebuild.
- Typographic quality in justified text, which is the change a careful reader will notice and cannot be fixed by configuration.
- Page count.
- Cross-references, which stop resolving rather than resolving wrongly.
What to diff before cutting over
Ask whether to do it at all before diffing anything. If the document is typographically serious, the answer may be no, and that is a legitimate outcome. If it is a business document, diff extracted text and accept that the appearance is being rebuilt.
The one thing that always breaks
Justified text. It is the one thing LaTeX does better than any browser engine and the difference is visible to a non-expert in a side by side, particularly on a narrow measure. Documents set justified in LaTeX and reproduced justified in a browser look worse, and the fix is a design decision, setting them ragged right, rather than a technical one.
Frequently asked
Do I have to rewrite my templates to leave LaTeX?
Effectively yes, and it is better to plan for that than to discover it. The old tool did not have HTML templates to port, so the document has to be expressed as markup for the first time. The value in the old code is the data layer underneath the drawing, and that part survives untouched.
Can I run both for a while?
Yes, and it is the safest way to do it. Put both behind one internal function that takes your data and returns bytes, switch on an environment variable, and run the new path on real traffic while the old one still serves. You get a diff on real documents rather than on fixtures, and you keep a way back that does not involve a deploy.
What about the documents already generated?
Nothing here changes them. They are files that already exist. What is worth deciding before the cutover is whether a regenerated document has to match the original byte for byte or merely say the same thing, because for anything with a legal or audit character the answer is usually to keep the original file rather than to be able to reproduce it.
Other migrations
The nearest neighbours first, then others that started from the same kind of tool, because the model matters more than the language.
Migrating off Apache FOP, from XSL-FO to CSS
A formatter taking XSL-FO, an XML vocabulary for paged layout, usually produced from your data by an XSLT transform, where the transform is the template and both halves change.
Migrating off DOCX templating, and keeping the Word deliverable
A pipeline that fills placeholders in a Word template and converts the result to PDF, where the conversion step is what you are replacing and the Word file may still be a deliverable.
Migrating off Prince, and the paged CSS features you lose
A commercial formatter with the most complete paged CSS implementation available, which makes this the one migration in the cluster where you should expect to give something up.
Migrating off JasperReports, and what happens to the bands
A reporting engine whose layouts are XML files built in a visual designer, organised into bands that repeat by rule, where nothing about the layout is portable and the band model has no equivalent.
Migrating off Crystal Reports, and rebuilding the formula fields
A reporting product whose layouts live in binary report files edited in a designer, with sections, formula fields and its own formula language, none of which are portable.
Every migration, grouped by what you are coming from
The full list, sorted by the model the old tool used rather than by its name.
What this API actually does
One page per option and endpoint that exists, which is what the mappings above point at.
Render one of your existing documents through the playground before changing any code. That comparison is the whole of the risk assessment for this migration.