Generate a book with Asciidoctor PDF.
Typesetting for print-on-demand printing is complex. This helps. Use this code as a starting point for your own print book.
The output is a PDF ready to print with Lulu. Lulu is currently the only supported printer. Patches welcome to resolve issue ad04.
The build script above also serves as an automated acceptance test. If the build completes without errors, this test passes. Ignore warnings and less severe output.
The manual acceptance test is to upload the PDF to Lulu. If Lulu accepts the PDF as valid, this test passes. Ignore warnings and less severe output.
Here’s a brief summary of the stuff we are aware of and working on.
| ID | Description | Status | Resolution Details |
|---|---|---|---|
ad02 |
translate to any language besides English |
OPEN |
|
ad04 |
support another printer/publisher besides Lulu |
OPEN |
|
ad05 |
document all attributes at top of |
OPEN |
|
ad06 |
emoji: no color, no genie |
WON’T FIX |
See detail below |
We maintain our own issue list here so this repository is more useful on its own.
IDs start with ad to avoid conflicts with IDs that might be generated by some other issue tracker, should we choose one.
Completed items can be removed, just make sure to leave the last one so we don’t skip IDs.
Don’t apply specific AsciiDoc formatting (e.g. column widths), the default should be good enough.
Don’t change spacing in the source, it is natural/uneven on purpose to optimize for proper diffs in source control history.
-
pay attention to and follow the existing style
-
standardize whenever possible and formalize conventions here
-
-
source control
-
commit early and often
-
group logically related changes into single commits
-
consider future maintainers may wish to
git revert: try to make that easy for them
-
-
group a series of related changes in a branch
-
squashing is OK
-
before submitting patches:
-
ensure build passes
-
-
commit log messages
-
the first line of a commit log message is very important: say precisely what change you made, save the why for the rest
-
use infinitive verb forms, e.g. "add -q quiet option"
-
don’t wrap body text
-
see also:
-
-
Asciidoctor-PDF does not yet support color emoji, and the fallback font with some emoji is not comprehensive. For what it’s worth, I don’t need nor want color emoji in this project, I’m just documenting why it currently works the way it does.
See:
Lulu accepts the output PDF for printing but shows these warnings:
|
Warning
|
Images: Your file contains images with resolution less than 200 pixels per inch. Lulu suggests using images with a pixel per inch range of 200-600 for the best results. Learn about image print quality. Transparency: We detected an element that may be transparent within your file. We strongly recommend flattening or removing any transparencies in your file. Review print guidelines. Full Bleed: Please note that a white Bleed margin has been added to your file. The book preview will show how this Bleed margin impacts your file. If you require image content that extends to the trimmed edge of the page, please upload a PDF prepared for Full Bleed. Learn about full bleed. |
Your contributions are most welcome! When submitting a patch, please:
-
Heed the Conventions.
-
Sign off every commit (
git commit --signoff). Sorry, I know this is annoying, but it is important. It certifies you wrote or otherwise have the right to submit the patch, following Developer Certificate of Origin, version 1.1.
©2023-2024 Adam Monsen.
The license for all original source code related to this book is the GNU AGPL (Affero General Public License) as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The license for the book content itself (what little there is) is Creative Commons CC0 1.0 Universal.