Move majority of documentation into README.

[bookmaker] / README.txt

usage: bookmaker.py [-h] -i INPUT_FILE -o OUTPUT_FILE [-p PAGE_RANGE]
                    [-c CROPS] [-r ROTATE_PAGE] [-s] [-n] [-a]
                    [-m PRINT_MARGIN]

bookmaker.py is a helper for optimizing PDFs for the production of small self-printed, self-bound physical books.  Towards this goal it offers various PDF manipulation options that may also be used indepéndently and for other purposes.

options:
  -h, --help            show this help message and exit
  -i INPUT_FILE, --input_file INPUT_FILE
                        input PDF file
  -o OUTPUT_FILE, --output_file OUTPUT_FILE
                        output PDF file
  -p PAGE_RANGE, --page_range PAGE_RANGE
                        page range, e.g., '2-9' or '3-end' or 'start-14'
  -c CROPS, --crops CROPS
                        cm crops left, bottom, right, top – e.g.,
                        '10,10,10,10'; prefix with ':'-delimited page range to
                        limit effect
  -r ROTATE_PAGE, --rotate_page ROTATE_PAGE
                        rotate page of number by 90° (usable multiple times on
                        same page!)
  -s, --symmetry        alternate horizontal crops between odd and even pages
  -n, --nup4            puts 4 input pages onto 1 output page, adds binding
                        cut stencil
  -a, --analyze         in --nup4, print lines identifying spine, page borders
  -m PRINT_MARGIN, --print_margin PRINT_MARGIN
                        print margin for --nup4 in cm (default 0.43)

OVERVIEW OF TARGET USAGE:

By cropping with -c and studying the results, define the areas of the input PDF's pages you want visible.  Then, with--nup4, map those areas onto 4 input pages per 1 output page, arranged in such a way that double-sided print-out of those output pages can be cut, folded, and bound (helped by addition of stencils for small incisions to carry rubber bands or the like) into a small A6 book.  Each unit of 8 pages from the input PDF is mapped by --nup4 onto two pages representing two sides of a (no-tumble-duplex-printed) A4 paper:

                      +-------=-------+                     __________________
 (front)  (back)      | 4 | 1 = 2 | 3 |             4      /=|===|============
+-------=-------+ ==> +-------=-------+ ===>  _/|\_ v      >=|===|============
| 4 | 1 = 2 | 3 |                            /  |  \_      \=|===|============
|-------=-------|     +-------=-------+ 1-> | 2 | 3 |      | \   / <- cut out!
| 8 | 5 = 6 | 7 | ==> | 8 | 5 = 6 | 7 |     | _/ \_ |      |  \ |
+-------=-------+     +-------=-------+     |/     \|      |   \| (p. 5)

To turn this paper into a small 8-pages book, first cut it into two A5 papers along its horizontal middle.  Fold both A5's by their vertical middles, with pages 2-3 and 7-6 on the folds' insides.  You now have two 4-page A6 "books" of pages 1-4 and pages 5-8.  Fold both closed and (counter-intuitively) stack the second one on top of the first one (creating a temporary page order of 5,6,7,8,1,2,3,4).  This reveals a small stencil on the top left of page 5 – cut it out, with all other pages folded and aligned under it, creating a small notch in the upper "inner" corner of all pages.  Turn around the stack to find a mirror stencil on the bottom and repeat the cutting.  Each page now has cuts on top and bottom of its inner margins into which a rubber band can be hooked, or through which a string may be looped and tied, to bind the page's inner margins into a kind of book spine.  You may now swap the order of the 4-page books back into a proper final page order (of 1,2,3,4,5,6,7,8) and repeat the whole process for each further --nup4 output paper.

COMMAND EXAMPLES:

Concatenate two PDFs A.pdf and B.pdf to COMBINED.pdf:
    bookmaker.py --input_file A.pdf --input_file B.pdf --output_file COMBINED.pdf

Produce OUTPUT.pdf containing all pages of (inclusive) page number range 3-7 from INPUT.pdf:
    bookmaker.py -i INPUT.pdf --page_range 3-7 -o OUTPUT.pdf

Produce COMBINED.pdf from A.pdf's first 7 pages, B.pdf's pages except its first two, and all pages of C.pdf:
    bookmaker.py -i A.pdf -p start-7 -i B.pdf -p 3-end -i C.pdf -o COMBINED.pdf

Crop each page 5cm from the left, 10cm from the bottom, 2cm from the right, and 0cm from the top:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf --crops "5,10,2,0"

Include all pages from INPUT.pdf, but only crop pages 10-20 by 5cm each from bottom and top:
    bookmaker.py -i INPUT.pdf -c "10-20:0,5,0,5" -o OUTPUT.pdf

Same crops for pages 10-20, but also crop all pages 30 and later by 3cm each from left and right:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -c "10-20:0,5,0,5" -c "30-end:3,0,3,0"

Rotate by 90° pages 3, 5, 7; rotate page 7 once more by 90% (i.e. 180° in total):
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf --rotate 3 -r 5 -r 7 -r 7

Initially declare 5cm crop from the left and 1cm crop from right, but alternate direction between even and odd pages:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -c "5,0,1,0" --symmetry

Quarter each OUTPUT.pdf page to carry 4 pages from INPUT.pdf, draw stencils into inner margins for cuts to carry binding strings:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf --nup4

Same --nup4, but define a printable-region margin of 1.3cm to limit the space for the INPUT.pdf pages in OUTPUT.pdf page quarters:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -n --print_margin 1.3

Same --nup4, but draw lines marking printable-region margins, page quarters, spine margins:
    bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -n --analyze

FURTHER NOTES:

For arguments like -p, page numbers are assumed to start with 1 (not 0, which is treated as an invalid page number value).

The target page shape so far is assumed to be A4 in portrait orientation; bookmaker.py normalizes all pages to this format before applying crops, and removes any source PDF /Rotate commands (for their production of landscape orientations).