1  # PPP
  2  
  3  Paul's Preponderating Prepresser (PPP) is a neat little Python utility that ingests a .PDF e-book and "imposes" it onto letter-size pages, so you can print it out. 
  4  
  5  I can hear the hippies crying now: "But PAUL! DUUUUDE! Surely we shouldn't be encouraging people to *print books* on *dead trees!* Think of the *treeeees*, *maaaaaan!*
  6  
  7  Hear me out, people. Yes, physical books use paper. So does junk mail. So do CVS receipts. So do the reams of corporate marketing materials that no one will ever read. When you actually *need* a book you can annotate, loan, or read without electricity (what's the carbon footprint of that charger? how about the AWS data center?), PPP is the tool for the job. If you're concerned about environmental impact, there are about 22,000 higher-leverage targets than this program. They're called "private jets". When those no longer exist, *then* we can talk about the occasional hand-bound dead-tree book.
  8  
  9  BUT I DIGRESS
 10  
 11  **Installation Instructions**
 12  
 13  PPP runs on Linux and macOS. (If you want to port it to Windoze, be my guest.) It's written in [Python](https://www.python.org) and assumes you're running `bash` for a shell.
 14  
 15  **The easy way:** `git` the repo down and run the installer:
 16  
 17  ```bash
 18  ./install.sh
 19  ```
 20  
 21  The installer auto-detects your OS and handles everything — system packages via Homebrew (macOS) or apt (Linux), then installs PPP system-wide via [pipx](https://pipx.pypa.io/). No venvs to manage, no PATH hacking, no shebang headaches. Works identically on both platforms.
 22  
 23  **The pipx-only way** (if you already have the system dependencies):
 24  ```bash
 25  pipx install .
 26  ```
 27  
 28  **The manual way:** ensure the following are installed on your system:
 29  * `pdftk`
 30  * `poppler-utils` / `poppler` (provides `pdftops`)
 31  * `psutils` (provides `psbook` and `pstops`)
 32  * `ghostscript` (provides `gs` and `ps2pdf`)
 33  * `cowsay`
 34  
 35  Then install PPP:
 36  ```bash
 37  pipx install .
 38  ```
 39  
 40  Now you're ready to *PPPartaaaaay!!*
 41  
 42  **Quick-Start Guide**
 43  
 44  Acquire a .PDF by whatever method brings you joy, but *definitely not* by going on LibGen. Put that sucker in a convenient place, fire up a terminal, punch in `ppp.py`, and away you go. The program will prompt you at various points. If you know what you're doing, you can stop reading now and let 'er rip, but if you find my writing style entertaining and want to better understand what it's doing, you should probably be familiar with a little bit of the publishing process.
 45  
 46  **Workflow Explanation**
 47  
 48  A traditionally-bound book actually consists of several little books called *signatures*. In order to make a signature (also called a "section" or "gathering"), we could just staple the individual pages together, one after the other, but that would get bulky and the pages would rip out really easily. Instead, we manipulate the pages around in a special way, so that when the whole signature is collated and folded in half, you can turn the pages and they'll be in the right order. This process is called *imposition*. 
 49  
 50  If we make our pages 5.5 x 8.5 inches, we can rotate them and put two on each side of a standard letter-size sheet (called "2-up imposition"). We then use some fancy math to figure out the order to put the pages in so they'll be sequential when the signature is folded. You don't have to memorize the order. PPP does it for you!
 51  
 52  Basically, what PPP does is:
 53  * take the source .PDF and check it for errors
 54  * shrink or expand the pages to be 5.5 x 8.5 inches
 55  * rotate and rearrange the pages 2-up
 56  * impose everything into signatures
 57  * output the resulting signatures to a new subfolder
 58  * optionally, batch several signatures together for simplified printing
 59  
 60  You then take the resulting .PDFs and print them. Make sure you have permission to do this! Commandeering office equipment can be great fun, but it may be against company policy. Use your own judgment. I just write the software. I'm not responsible for what you do with it.
 61  
 62  **Example**
 63  
 64  I've included a couple handy-dandy half-letter size example files (lipsum-8.pdf and lipsum64.pdf) for you to mess around with. Let's use the latter to demonstrate how PPP works.
 65  
 66  After installing, just type `ppp` from anywhere on your system. No `chmod`, no `python3`, no `./` needed.
 67  
 68  lipsum64.pdf is already the correct size, but if it weren't, PPP will resize it for you. *N.B.:* PPP doesn't change the aspect ratio of the pages - it simply shrinks them to fit. You'll probably end up with whitespace at the top and bottom of the pages. If this bugs you, grab a guillotine cutter and trim the excess after printing. You can also fork the code and fix it yourself. (That don't buffront me, long as I get *my* money next Friday.)
 69  
 70  Next, you'll be presented with some choices for how big to make the signatures. Pick whichever one seems best. PPP will preferentially suggest 32- and 36-page signatures. This is about the biggest you can get and still be able to fold cleanly. (By the way, get yourself a bone folder if you're going to be doing a lot of these. There really is no substitute for this specialized tool.)
 71  
 72  Next, PPP will split the file into signatures of the correct size. You can bail out here if you want, but 99.9% of the time you'll want to just hit Enter.
 73  
 74  Next, PPP will rotate and rearrange the pages, imposing them 2-up. Then it will give you the option to combine several signatures into print jobs, if that's appropriate. (*N.B.:* PPP puts blank sheets between the signatures to make them easier to identify. Pick them out after printing and either put 'em back in the tray or use them for scrap. Your choice.)
 75  
 76  At this point you have to take over, because the various PDF readers and printers have different UI. To print the jobs correctly, you'll want to select double-sided, flip SHORT edge.
 77  
 78  And that's it!
 79  
 80  **Standalone Tools**
 81  
 82  If you don't need to run the whole workflow, you can invoke the components separately. All commands are installed system-wide:
 83  
 84  * `ppp-pad` — adds blank pages so the signatures divide correctly
 85  * `printydump` — splits the file into signatures
 86  * `singledingle` — imposes a single signature 2-up
 87  * `fppp` — runs `singledingle` on all PDFs in the current directory
 88  * `flippar` — fixes upside-down back pages from misconfigurated printers
 89  * `pppf` — runs `flippar` on all PDFs in the current directory
 90  * `pdfmerge` — merges multiple PDFs into one
 91  * `impose-4up` — 4-up imposition
 92  * `isbnner` — sets ISBN metadata in Calibre
 93  
 94  **Troubleshooting**
 95  
 96  Most of the errors I run into involve errant blank pages getting inserted into signatures. If you see asterisks in the imposition output (like this):
 97  
 98  ```
 99   ... rearranging pages ...
100  [*] [1] [2] [*] [*] [3] [4] [41] [40] [5] [6] [39] [38] [7] [8] [37] [36] [9] 
101  [10] [35] [34] [11] [12] [33] [32] [13] [14] [31] [30] [15] [16] [29] [28] 
102  [17] [18] [27] [26] [19] [20] [25] [24] [21] [22] [23] 
103  Wrote 44 pages, 1374472 bytes
104   ... imposing pages 2-up ...
105  [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] 
106  [18] [19] [20] [21] [22] Wrote 22 pages, 1390639 bytes
107   ... re.PDFenating ...
108  ```
109  
110  ... something's gone wrong. Bail out and examine the source file. Chances are, its length isn't a multiple of 4. If there are extra blank pages, strip them out with `pdftk foo.pdf cat x-y output fixed.pdf` or something similar. If you need to add blank pages, those are included. Add them with `pdftk foo.pdf 3pp.pdf cat output fixed.pdf` or something similar.
111  
112  **Misconfigurated Printers**
113  
114  You may run into a situation where you're doing everything right, but the printer just. will. not. print. the job. correctly. For this reason, you should *never* print a whole-ass document unless you're *absolutely sure* the printer is going to behave. Start with a test page or two. You can `pdftk foo.pdf cat 1-4 output test.pdf` to see what happens.
115  
116  A common issue is when the printer refuses to perform a "flip short edge". This will result in the back sides of every page being upside down, thus ruining your good mood. If this happens, dump all yer output files into a working directory and run `pppf`.
117  
118  **Contact**
119  
120  If you like this software, if you think I'm cool, or otherwise want to get in touch, email [info@neroots.net](mailto:info@neroots.net). If you hate this software or don't think I'm cool, those communications can be routed to `/dev/null`. I'll be sure to check that mailbox periodically.
121  
122  Yours in Cthulhu,
123  
124  Paul Fusco-Gessick
125  
126  Delmar, N.Y. Atlantic Republic