Printable, Downloadable, Forever: An Ode to Offline Documentation

The PDF file format has stood the test of time as a versatile and highly portable means to producing print-oriented media, reports, documents, and knowledge works, to facilitate information exchange in varied settings. This talk advocates for the proliferation of distributing FOSS project documentation in the PDF file format. I would like to highlight various incentives towards such a paradigm where documentation is browsed offline, while also being balanced and offering a sense into its pitfalls.

While most projects consider offline documentation (via PDF, and other formats such as EPUB) as an afterthought in comparison to web-based documentation, there is a case to be made for it—as a missed opportunity—to reach a wider variety of users. A well-structured PDF is something a documentation website cannot replicate easily – it works without an internet connection, works on all sorts of PDF readers and devices, offers features such as annotations, comments, can go places on compact data storage devices such as flash drives, and lastly, can be printed and handed over to users in the form of manuals and booklets. This matters for remote and low-resource regions with limited internet access – for instance, in countries where metered mobile data costs are high and broadband being evenly distributed is a privilege. Another benefit is accessibility, in that it is easier for a PDF with a semantic heading structure to be more navigable with a screen reader, than a documentation site that may layer custom JavaScript navigation widgets over its content.

The most common form of PDF/offline documentation generation is via typesetting tools such as LaTeX, but the tooling landscape in the world of FOSS has changed considerably, having gone through various advancements – to the point where LaTeX is not the sole choice for a FOSS project wanting to share offline documentation. For instance:

1. Typst is a modern typesetting system that produces clean PDF output with much faster builds and genuinely readable error messages
2. rinohtype is a pure Python PDF renderer that integrates with Sphinx and requires no external TeX installation
3. Pandoc is a command-line tool that acts as a universal document converter, allowing conversion between hundreds of markup and word-processing formats
4. Quarto is a multi-language scientific and technical publishing system that allows users to create dynamic, reproducible documents, presentations, and websites
5. nbconvert is a Python library and command-line tool used to export Jupyter Notebooks (.ipynb) into of polished, distributable files in several formats
6. …and so on

Besides documentation authors, there are also projects for users, i.e., documentation readers. Offline documentation readers, such as Zeal are worth knowing about and pointing to.

However, as can be expected, there are also pitfalls to offline documentation, such as math rendering differences across tools, SVG and figure handling, font embedding, maintaining the accessibility conformance of the generated outputs, how EPUB fares across different reader applications, and maintenance questions of who takes up building documentation for such formats and keeps it going.

Here is a proposed (read: provisional) outline of my talk:

1. Making the case for offline documentation
2. What downloadable documentation give a user that a documentation website cannot
3. Bandwidth constraints and intermittent connectivity as design considerations for documentation authors
4. Accessibility of well-tagged PDFs versus JavaScript-heavy documentation sites
5. Archival value: documentation that survives domain expiry and sunsets for FOSS projects
6. PDF vs EPUB: different formats for different reading contexts
7. The extended reading use case, learning something deeply rather than looking something up quickly
8. Current halts in the PDF documentation conveyor belt
9. How Sphinx's LaTeX-based PDF builder works, and what it drags in as dependencies
10. Common failure modes in practice when building PDF documentation
11. Why this is a fixable tooling problem, not a reason to give up on offline documentation
12. A brief tour of FOSS tools
13. Typst and what it improves upon in LaTeX in build speed and error output
14. rinohtype: pure Python, no TeX required, integrates directly into the Sphinx builder ecosystem
15. sphinx-simplepdf and WeasyPrint: CSS-driven layouts for maintainers already comfortable with the web
16. Pandoc as a universal converter and its role in projects with mixed source formats
17. nbconvert and the Jupyter-notebook-form documentation: how it works and what browser-native tooling is building on it
18. FOSS offline documentation readers including Zeal and Foliate
19. Calibre for format conversion and validation
20. Pitfalls for offline documentation
21. Math rendering across tools, including how MathJax, KaTeX, and native math each fare in PDF outputs
22. Figure and image handling, resolution, SVG support, and vector-vs-raster decisions
23. Font embedding and subsetting across generators
24. When should you not look to build a PDF at all? Maintenance, needs, and bigger questions

1. A practical survey of FOSS tools for building offline (PDF/EPUB) documentation, with enough specifics to evaluate tradeoffs for your project
2. A case for offline documentation, including accessibility and connectivity arguments, and how it serves different user needs
3. Specific failure modes to anticipate in offline builds before they find you in production
4. When not to build offline documentation