From: Christian Heller Date: Sun, 24 Sep 2023 02:21:32 +0000 (+0200) Subject: Bookmaker: Improve documentation. X-Git-Url: https://plomlompom.com/repos/%7B%7Bdb.prefix%7D%7D/%7B%7B%20web_path%20%7D%7D/%7B%7Bprefix%7D%7D/process_descriptions?a=commitdiff_plain;h=41a33e19eb653c08441c5f4f057e6ff1b08e1577;p=misc Bookmaker: Improve documentation. --- diff --git a/bookmaker.py b/bookmaker.py index d9bf685..f233d38 100755 --- a/bookmaker.py +++ b/bookmaker.py @@ -10,16 +10,75 @@ cut_width = 1.05 * points_per_cm middle_point_depth = 0.4 * points_per_cm spine_limit = 1 * points_per_cm -parser = argparse.ArgumentParser(description="build print-ready book PDF") +desc = """bookmaker.py is a helper for optimizing PDFs of books for the production of small self-printed, self-bound physical books To this goal it offers various PDF manipulation options potentially that can also be used indepéndently and for other purposes. +""" +epilogue = """ +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 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 from on 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" -s + +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 as --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 as -n, but draw lines marking printable-region margins, page quarts, spine margins: + bookmaker.py -i INPUT.pdf -o OUTPUT.pdf -n --analyze + +NOTES: + +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). + +The --nup4 quartering puts pages into a specific order optimized for no-tumble duplex print-outs that can easily be folded and cut into pages of a small A6 book. Each unit of 8 pages from the source PDF is mapped thus onto two subsequent pages (i.e. front and back of a printed A4 paper): + + (front) (back) ++-------+ +-------+ +| 4 | 1 | | 3 | 2 | +|-------| |-------| +| 8 | 5 | | 7 | 6 | ++-------+ +-------+ + +To facilitate this layout, --nup4 also pads the input PDF pages to a total number that is a multiple of 8, by adding empty pages. + +(To turn this page into a tiny 8-page book, cut the paper in two on its horizontal middle line. Fold the two halves by their vertical middle lines, with pages 3-2 and 7-6 on the folds' insides. This creates two 4-page books of pages 1-4 and pages 5-8. Fold them both closed and (counter-intuitively) put the book of pages 5-8 on top of the other one (creating a temporary page order of 5,6,7,8,1,2,3,4). A binding cut stencil should be visible on the top left of this stack – cut it out (with all pages folded together) to add the same inner-margin upper cut to each page. Turn around your 8-pages stack to find the mirror image of aforementioned stencil on the stack's back's bottom, and cut it out too. Each page now has binding cuts on top and bottom of its inner margins. Swap the order of both books (back to the final page order of 1,2,3,4,5,6,7,8), and you now have an 8-pages book that can be "bound" in its binding cuts through a rubber band or the like. Repeat with the next 8-pages double-page, et cetera. (Actually, with just 8 pages, the paper may curl under the pressure of a rubber band – but go up to 32 pages or so, and the result will become quite stable.) +""" + +# parser = argparse.ArgumentParser(description="build print-ready book PDF") +parser = argparse.ArgumentParser(description=desc, epilog=epilogue, formatter_class=argparse.RawDescriptionHelpFormatter) +parser._optionals.title = "OPTIONS" 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") parser.add_argument("-p", "--page_range", action="append", help="page range, e.g., '3-end'") -parser.add_argument("-c", "--crop_range", action="append", help="cm crops left, bottom, right, top – e.g., '10,10,10,10'; prefix with ':'-delimited page range to limit effect") +parser.add_argument("-c", "--crops", action="append", help="cm crops left, bottom, right, top – e.g., '10,10,10,10'; prefix with ':'-delimited page range to limit effect") +parser.add_argument("-r", "--rotate_page", type=int, action="append", help="rotate page of number by 90° (usable multiple times on same page!)") parser.add_argument("-s", "--symmetry", action="store_true", help="alternate horizontal crops between odd and even pages") -parser.add_argument("-r", "--rotate", dest="rotate", type=int, action="append", help="rotate page of number by 90° (usable multiple times on same page!)") -parser.add_argument("-n", "--nup4", action='store_true', help="puts 4 input pages onto 1 output page") +parser.add_argument("-n", "--nup4", action='store_true', help="puts 4 input pages onto 1 output page, adds binding cut stencil") parser.add_argument("-a", "--analyze", action="store_true", help="in --nup4, print lines identifying spine, page borders") -parser.add_argument("-m", "--margin", type=float, default=0.43, help="print margin for --nup4 in cm (default 0.43)") +parser.add_argument("-m", "--print_margin", type=float, default=0.43, help="print margin for --nup4 in cm (default 0.43)") +parser.add_argument("-H", "--long_help", action="store_true", help="show examples, explanations, additional usage notes") args = parser.parse_args() @@ -61,13 +120,13 @@ if args.nup4: pages_to_add += [new_page] # rotate page canvas -if args.rotate: - for rotate in args.rotate: - page = pages_to_add[rotate - 1] +if args.rotate_page: + for rotate_page in args.rotate_page: + page = pages_to_add[rotate_page - 1] page.add_transformation(pypdf.Transformation().translate(tx=-a4_width/2, ty=-a4_height/2)) page.add_transformation(pypdf.Transformation().rotate(-90)) page.add_transformation(pypdf.Transformation().translate(tx=a4_width/2, ty=a4_height/2)) - print("-r: rotating (by 90°) page", rotate) + print("-r: rotating (by 90°) page", rotate_page) # normalize all pages to portrait A4 for page in pages_to_add: @@ -82,9 +141,9 @@ for page in pages_to_add: # determine page crops, zooms, crop symmetry crops_at_page = [(0,0,0,0)]*len(pages_to_add) zoom_at_page = [1]*len(pages_to_add) -if args.crop_range: - for crop_range in args.crop_range: - initial_split = crop_range.split(':') +if args.crops: + for crops in args.crops: + initial_split = crops.split(':') if len(initial_split) > 1: page_range = initial_split[0] crops = initial_split[1] @@ -140,11 +199,11 @@ if not args.nup4: else: print("-n: building 4-input-pages-per-output-page book") - print("-m: applying printable-area margin of %.2fcm" % args.margin) + print("-m: applying printable-area margin of %.2fcm" % args.print_margin) if args.analyze: print("-a: drawing page borders, spine limits") n_pages_per_axis = 2 - printable_margin = args.margin * points_per_cm + printable_margin = args.print_margin * points_per_cm printable_scale = (a4_width - 2*printable_margin)/a4_width half_width = a4_width / n_pages_per_axis half_height = a4_height / n_pages_per_axis