swift-book-pdf

PDF Generator for The Swift Programming Language

Convert the DocC source for The Swift Programming Language book into a print-ready PDF document. The final document follows the DocC rendering style and retains all internal references and external links.

Preview Books
Light Mode
Dark Mode

Features

• Generate a PDF version of the The Swift Programming Language book, perfect for offline browsing or printing.
• Choose from one of two rendering modes:
  • Digital mode with hyperlinks for cross-references between chapters and external links.
  • Print mode with page numbers accompanying cross-references between chapters and full URLs shown in footnotes for external links.
• Both versions follow the DocC rendering style used in docs.swift.org, including code highlighting.

Requirements

• Python 3.9+
• Git
• LuaTeX (see MacTeX, TeX Live, or MiKTeX)
• Fonts for typesetting. See the Fonts article for more details.

Installation

Latest PyPI stable release

pip install swift-book-pdf

Usage

Basic usage

Call swift_book_pdf without any arguments to save the resulting PDF as swift_book.pdf in the current directory. The package defaults to the digital rendering mode in Letter paper size.

$ swift_book_pdf

[INFO]: Downloading TSPL files...
[INFO]: Creating PDF in digital (light) mode...
[INFO]: PDF saved to ./swift-book.pdf

When invoked, swift_book_pdf will:

• Clone the swift-book repository
• Convert all Markdown source files into a single LaTeX document
• Render the LaTeX document into the final PDF document

[!NOTE] swift_book_pdf will create a temporary directory to store the swift-book repository, LaTeX file and intermediate files produced during typesetting. This temporary directory is removed after the PDF is generated.

Output path

You can specify an output path:

swift_book_pdf /path/to/output.pdf

Input path

Use the --input-path/-i option to specify a path to the root of a local copy of the swift-book repository. If not provided, the repository will be cloned from GitHub.

swift_book_pdf -i /path/to/swift-book/

Rendering modes

swift_book_pdf supports two rendering modes:

• digital (default): Best for browsing The Swift Programming Language book as a PDF, the digital mode renders internal references and external links in blue hyperlinks.
• print: Best for reading through The Swift Programming Language book in print, the print mode includes page numbers for all internal references and complete URLs in footnotes for external links.

Use the --mode option to set your preferred rendering option:

swift_book_pdf /path/to/output.pdf --mode print

Paper sizes

swift_book_pdf supports three paper sizes:

• letter (default)
• legal
• A4

Use the --paper option to set your preferred paper size:

swift_book_pdf --paper legal

Appearance

swift_book_pdf renders The Swift Programming Language book in light mode by default. To render the book in dark mode, use the --dark flag.

swift_book_pdf --dark

Book Gutter

swift_book_pdf renders The Swift Programming Language book with a book gutter by default. To render the book without a gutter, use the --no-gutter flag.

swift_book_pdf --no-gutter

Fonts

swift-book-pdf requires a set of fonts to typeset The Swift Programming Language book. You can use any of the available default options, or specify your own fonts. To learn more about fonts and available configuration options, see this article.

Number of typesetting passes

This package uses LaTeX to typeset the TSPL book. LaTeX arranges page elements dynamically, so references added in the second pass may shift the page content, and alter the placement of headers and footers. To ensure everything is properly rendered, swift_book_pdf typesets the document four times.

If needed, you can adjust the number of typesets:

swift_book_pdf /path/to/output.pdf --typesets 5

[!CAUTION] Only increase the number of typesets if the document has missing references or misaligned headers or footers.

Do not decrease the number of typesets. Given the document's complexity (650+ pages with relative anchors), the extra typesets ensure proper rendering of headers and footers.

Always run at least two typesets. Skipping this may break internal references to other sections.

Acknowledgments

At runtime, the swift-book repository is temporarily cloned for processing, but no part of the repository is directly redistributed here.

chapter-icon.png is derived from the ArticleIcon.vue component in the swift-docc-render repository.

The swift-book and swift-docc-render repositories are part of the Swift.org open source project, which is licensed under the Apache License v2.0 with Runtime Library Exception. See https://swift.org/LICENSE.txt for more details. The Swift project authors are credited at https://swift.org/CONTRIBUTORS.txt.

The Swift logo is a trademark of Apple Inc.