From 197948ce3f6c8c3604322c13d17436be6c8d0dfc Mon Sep 17 00:00:00 2001 From: Christian Heller Date: Tue, 26 Sep 2023 15:57:20 +0200 Subject: [PATCH] Move majority of documentation into README. --- README.txt | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++ bookmaker.py | 57 +----------------------------------- 2 files changed, 83 insertions(+), 56 deletions(-) create mode 100644 README.txt diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..57fc9cf --- /dev/null +++ b/README.txt @@ -0,0 +1,82 @@ +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). diff --git a/bookmaker.py b/bookmaker.py index 431587e..2440747 100755 --- a/bookmaker.py +++ b/bookmaker.py @@ -2,62 +2,6 @@ """ 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. """ -help_epilogue = """ -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). -""" import argparse import io import os @@ -143,6 +87,7 @@ class HandledException(Exception): def parse_args(): + help_epilogue = "See README.txt for detailed usage instructions, command examples, etc." parser = argparse.ArgumentParser(description=__doc__, epilog=help_epilogue, formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument("-i", "--input_file", action="append", required=True, help="input PDF file") parser.add_argument("-o", "--output_file", required=True, help="output PDF file") -- 2.30.2