search

amazon-ion / ion-docs

Source for the GitHub Pages for Ion.
https://amazon-ion.github.io/ion-docs/
Apache License 2.0
22 stars 22 forks source link

Rework PDF rendering pipeline to use dblatex #283

Closed toddjonker closed 8 months ago

toddjonker commented 9 months ago

Description of changes:

This uses the xmlto and dblatex packages to transform AsciiDoctor-generated DocBook XML into LaTeX and then to PDF. This enables a more robust and configurable rendering solution than AsciiDoctor's direct PDF generation, particularly with respect to math notation. This is effectively a precondition for the denotational semantics document, which is naturally and unavoidably math-heavy.

There's a fair amount of customization and workarounds in here, about half of which were forced by limitations and outright defects in dblatex. I've tried to document everything internally with the "why"s and links to relevant documentation, and that's what's most worth your attention, IMO.

I do not suggest reading too deeply into this PR unless you're particularly curious about the ugly details.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

toddjonker commented 9 months ago

Here are copies of the resulting Ion Spec PDF: