| Name | swift-book-pdf JSON |
| Version |
1.4.1
JSON |
| download |
| home_page | None |
| Summary | A tool to generate a PDF version of The Swift Programming Language book. |
| upload_time | 2025-08-17 17:58:57 |
| maintainer | None |
| docs_url | None |
| author | Evangelos Kassos |
| requires_python | >=3.9 |
| license | Apache-2.0 |
| keywords |
swift
book
pdf
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.
<table>
<tr>
<td colspan="3"><b>Preview Books</b></td>
</tr>
<tr>
<td>Light Mode</td>
<td><a href="https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_digital.pdf" target="_blank"><img src="https://img.shields.io/badge/download_book_(digital_mode)-064789?style=for-the-badge&logo=googledocs&logoColor=white" alt="Download book in digital mode"></a></td>
<td><a href="https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_print.pdf" target="_blank"><img src="https://img.shields.io/badge/download_book_(print_mode)-941b0c?style=for-the-badge&logo=googledocs&logoColor=white" alt="Download book in print mode"></a></td>
</tr>
<tr>
<td>Dark Mode</td>
<td><a href="https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_digital_dark.pdf" target="_blank"><img src="https://img.shields.io/badge/download_book_(digital_mode,_dark)-064789?style=for-the-badge&logo=googledocs&logoColor=white" alt="Download book in digital mode"></a></td>
<td><a href="https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_print_dark.pdf" target="_blank"><img src="https://img.shields.io/badge/download_book_(print_mode,_dark)-941b0c?style=for-the-badge&logo=googledocs&logoColor=white" alt="Download book in print mode"></a></td>
</tr>
</table>
## 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](#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](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/), including code highlighting.
## Requirements
- Python 3.9+
- Git
- LuaTeX (see [MacTeX](https://www.tug.org/mactex/), [TeX Live](https://www.tug.org/texlive/), or [MiKTeX](https://miktex.org))
- Fonts for typesetting. See [the Fonts article](https://github.com/ekassos/swift-book-pdf/wiki/Fonts) 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](#rendering-modes) in Letter [paper size](#paper-sizes).
```
$ 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:
1. Clone the `swift-book` [repository](https://github.com/swiftlang/swift-book)
2. Convert all Markdown source files into a single LaTeX document
3. 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](https://github.com/swiftlang/swift-book). 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:
1. `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.
2. `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:
1. `letter` (default)
2. `legal`
3. `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](https://github.com/ekassos/swift-book-pdf/wiki/Fonts/).
### 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](https://github.com/swiftlang/swift-book) is temporarily cloned for processing, but no part of the repository is directly redistributed here.
`chapter-icon.png` is derived from the [`ArticleIcon.vue`](https://github.com/swiftlang/swift-docc-render/blob/1fe0a7a032b11272d0407317995169f79bba0d84/src/components/Icons/ArticleIcon.vue) component in the swift-docc-render [repository](https://github.com/swiftlang/swift-docc-render/).
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "swift-book-pdf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "swift, book, pdf",
"author": "Evangelos Kassos",
"author_email": "github@evangeloskassos.com",
"download_url": "https://files.pythonhosted.org/packages/54/22/f99c5bdfe9a5c99afb632442e48ec1514c08cf028e338ecd4167ed4e26d9/swift_book_pdf-1.4.1.tar.gz",
"platform": null,
"description": "# PDF Generator for _The Swift Programming Language_\n\nConvert 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.\n\n<table>\n <tr>\n <td colspan=\"3\"><b>Preview Books</b></td>\n </tr>\n <tr>\n <td>Light Mode</td>\n <td><a href=\"https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_digital.pdf\" target=\"_blank\"><img src=\"https://img.shields.io/badge/download_book_(digital_mode)-064789?style=for-the-badge&logo=googledocs&logoColor=white\" alt=\"Download book in digital mode\"></a></td>\n <td><a href=\"https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_print.pdf\" target=\"_blank\"><img src=\"https://img.shields.io/badge/download_book_(print_mode)-941b0c?style=for-the-badge&logo=googledocs&logoColor=white\" alt=\"Download book in print mode\"></a></td>\n </tr>\n <tr>\n <td>Dark Mode</td>\n <td><a href=\"https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_digital_dark.pdf\" target=\"_blank\"><img src=\"https://img.shields.io/badge/download_book_(digital_mode,_dark)-064789?style=for-the-badge&logo=googledocs&logoColor=white\" alt=\"Download book in digital mode\"></a></td>\n <td><a href=\"https://github.com/ekassos/swift-book-pdf/releases/download/v1.4.0/swift_book_print_dark.pdf\" target=\"_blank\"><img src=\"https://img.shields.io/badge/download_book_(print_mode,_dark)-941b0c?style=for-the-badge&logo=googledocs&logoColor=white\" alt=\"Download book in print mode\"></a></td>\n </tr>\n</table>\n\n\n\n## Features\n- Generate a PDF version of the _The Swift Programming Language_ book, perfect for offline browsing or printing.\n- Choose from one of two [rendering modes](#rendering-modes):\n - Digital mode with hyperlinks for cross-references between chapters and external links.\n - Print mode with page numbers accompanying cross-references between chapters and full URLs shown in footnotes for external links.\n- Both versions follow the DocC rendering style used in [docs.swift.org](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/), including code highlighting.\n\n## Requirements\n- Python 3.9+\n- Git\n- LuaTeX (see [MacTeX](https://www.tug.org/mactex/), [TeX Live](https://www.tug.org/texlive/), or [MiKTeX](https://miktex.org))\n- Fonts for typesetting. See [the Fonts article](https://github.com/ekassos/swift-book-pdf/wiki/Fonts) for more details.\n\n## Installation\n### Latest PyPI stable release\n```\npip install swift-book-pdf\n```\n\n## Usage\n### Basic usage\nCall `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](#rendering-modes) in Letter [paper size](#paper-sizes).\n```\n$ swift_book_pdf\n\n[INFO]: Downloading TSPL files...\n[INFO]: Creating PDF in digital (light) mode...\n[INFO]: PDF saved to ./swift-book.pdf\n```\n\nWhen invoked, `swift_book_pdf` will:\n1. Clone the `swift-book` [repository](https://github.com/swiftlang/swift-book)\n2. Convert all Markdown source files into a single LaTeX document\n3. Render the LaTeX document into the final PDF document\n\n> [!NOTE]\n> 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.\n\n### Output path\nYou can specify an output path:\n```\nswift_book_pdf /path/to/output.pdf\n```\n\n### Input path\nUse the `--input-path`/`-i` option to specify a path to the root of a local copy of the swift-book [repository](https://github.com/swiftlang/swift-book). If not provided, the repository will be cloned from GitHub.\n```\nswift_book_pdf -i /path/to/swift-book/\n```\n\n### Rendering modes\n`swift_book_pdf` supports two rendering modes:\n\n1. `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.\n2. `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.\n\nUse the `--mode` option to set your preferred rendering option:\n\n```\nswift_book_pdf /path/to/output.pdf --mode print\n```\n\n### Paper sizes\n`swift_book_pdf` supports three paper sizes:\n\n1. `letter` (default)\n2. `legal`\n3. `A4`\n\nUse the `--paper` option to set your preferred paper size:\n```\nswift_book_pdf --paper legal\n```\n\n### Appearance\n`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.\n\n```\nswift_book_pdf --dark\n```\n\n### Book Gutter\n`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.\n\n```\nswift_book_pdf --no-gutter\n```\n\n### Fonts\nswift-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](https://github.com/ekassos/swift-book-pdf/wiki/Fonts/).\n\n### Number of typesetting passes\nThis 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.\n\nIf needed, you can adjust the number of typesets:\n```\nswift_book_pdf /path/to/output.pdf --typesets 5\n```\n\n> [!CAUTION]\n> Only increase the number of typesets if the document has missing references or misaligned headers or footers.\n>\n> 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.\n>\n> **Always run at least two typesets.** Skipping this may break internal references to other sections.\n\n## Acknowledgments\n\nAt runtime, the swift-book [repository](https://github.com/swiftlang/swift-book) is temporarily cloned for processing, but no part of the repository is directly redistributed here.\n\n`chapter-icon.png` is derived from the [`ArticleIcon.vue`](https://github.com/swiftlang/swift-docc-render/blob/1fe0a7a032b11272d0407317995169f79bba0d84/src/components/Icons/ArticleIcon.vue) component in the swift-docc-render [repository](https://github.com/swiftlang/swift-docc-render/).\n\nThe 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.\n\nThe Swift logo is a trademark of Apple Inc.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A tool to generate a PDF version of The Swift Programming Language book.",
"version": "1.4.1",
"project_urls": {
"Documentation": "https://github.com/ekassos/swift-book-pdf/wiki",
"Repository": "https://github.com/ekassos/swift-book-pdf.git",
"changelog": "https://github.com/ekassos/swift-book-pdf/blob/main/CHANGELOG.md",
"issues": "https://github.com/ekassos/swift-book-pdf/issues",
"releasenotes": "https://github.com/ekassos/swift-book-pdf/releases"
},
"split_keywords": [
"swift",
" book",
" pdf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "df37bf4f00ad5a5b48373223ce440f0e1cfd24f16edc355569d67d9f27829ff3",
"md5": "375a1243139f22dfd381d05a3e3283fe",
"sha256": "6d2e16a405b0c9d52254f36bbad50a0008a524535070eba5a8a67dee532f697c"
},
"downloads": -1,
"filename": "swift_book_pdf-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "375a1243139f22dfd381d05a3e3283fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 392040,
"upload_time": "2025-08-17T17:58:55",
"upload_time_iso_8601": "2025-08-17T17:58:55.905290Z",
"url": "https://files.pythonhosted.org/packages/df/37/bf4f00ad5a5b48373223ce440f0e1cfd24f16edc355569d67d9f27829ff3/swift_book_pdf-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5422f99c5bdfe9a5c99afb632442e48ec1514c08cf028e338ecd4167ed4e26d9",
"md5": "2829839107c4c842031a9c631f15808f",
"sha256": "f23da11276364de077d3e86f1922ef6a13e0d2366f3add68bcd670c58d29d945"
},
"downloads": -1,
"filename": "swift_book_pdf-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "2829839107c4c842031a9c631f15808f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 378144,
"upload_time": "2025-08-17T17:58:57",
"upload_time_iso_8601": "2025-08-17T17:58:57.620950Z",
"url": "https://files.pythonhosted.org/packages/54/22/f99c5bdfe9a5c99afb632442e48ec1514c08cf028e338ecd4167ed4e26d9/swift_book_pdf-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 17:58:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ekassos",
"github_project": "swift-book-pdf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "swift-book-pdf"
}
