nbk2pdf 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64fd3b6e1a6523298f069b406c0cf7a3b0b1d0df87cf843c665f5cb10b31f638
-  data.tar.gz: 022be27e074f4f6d0301ea10d10666d461aabdfe4aca1d8bba8751d3ffd23912
+  metadata.gz: 2993302368291aeb45035687bc5bdd501beef69c948910e7f173ea6db799383e
+  data.tar.gz: 720767d5e65bfef5e979661f09222d4af55bdcc62da60b5527dd556de07c2ea3
 SHA512:
-  metadata.gz: 4d8f4247ffe944e73d631dcadc50f01fe463f0c79296b20e0fca9dc2cdbeb1c4c8eeea4b7a1b88bc1729aa8dfddc961b0ac37c0f3861b92b36f892e9dab48646
-  data.tar.gz: bf6aacb7f72b3b4fd86f48f005be933e2f4826f3a3997cacf31a9a1c66489975e0e16b2ef41f09780bc3d4d905e0f27226f851b75bc8e9ff87bc06446e67d814
+  metadata.gz: 91a2ab63c1932539554505defb38810e049adeae2c6c352ca8583d11badd1e5894cfaa6a12adf73656a772a23f33d6bf3609c6e0b2ae48b9aedb2693a9774cb3
+  data.tar.gz: 8b28c36986aaefb0a3478c91fe49dbd221ca4e36cb05af45cbd6475f46f2e472cc5564738eab6637207dbab9c9eb22b8d3f6ef0b6e915be659452547a2b08efd

data/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-10-21
+
+### Added
+
+- `--two-up` prints notebook pages in pairs, side by side on landscape paper,
+  with margins so the pages do not touch.
+- Two-up and booklet pages are numbered in light grey; `--no-page-numbers`
+  leaves the numbers out.
+- `--booklet` lays notebook pages out to fold into a booklet, printed
+  double-sided on the long edge; `--signature` splits it into signatures of
+  that many sheets.
+- `--flip-on-edge short` lays a booklet out for a printer that flips on the
+  short edge.
+
 ## [1.0.1] - 2026-10-20
 
 ### Fixed

data/README.md

@@ -202,6 +202,11 @@ Options:
     -t, --titles FILE                JSON/YAML map of notebook uuid to the name you gave it
         --[no-]template              Draw the notebook's ruled background (default: yes)
     -p, --paper SIZE                 Page size: letter (default), a4, native, ...
+    -2, --two-up                     Put notebook pages in pairs side by side on landscape paper
+    -b, --booklet                    Lay notebook pages out to fold into a booklet
+        --signature SHEETS           Fold the --booklet in signatures of SHEETS sheets each
+        --flip-on-edge EDGE          Edge the printer flips a --booklet on: long (default) or short
+        --[no-]page-numbers          Number the pages when --two-up or --booklet (default: yes)
     -a, --annotations                Add ink to a PDF as annotations, not drawn into the page
     -q, --quiet                      Only report errors
     -h, --help                       Show this message
@@ -325,6 +330,47 @@ never tells a viewer whether scaling is allowed. If a print dialog greys out its
 scale field, that is the viewer's own setting -- in Evince, the manual scale is
 only editable once *Page Scaling* is set to *None*.
 
+#### Two pages per sheet
+
+`--two-up` puts notebook pages in pairs, side by side, on the paper turned
+landscape. Each page stays portrait and is scaled to fit its half. An 18 pt
+margin is kept around the sheet and between the two pages, so they never
+touch. An odd last page sits alone on the left of its sheet.
+
+```
+nbk2pdf --two-up notebook/                  # two pages on landscape Letter
+nbk2pdf --two-up --paper a4 notebook/
+nbk2pdf --two-up --paper native notebook/   # a sheet just wide enough for both
+```
+
+On Letter each page is scaled to 83% of the device's size.
+
+Each page is numbered in light grey, centred under it. `--no-page-numbers`
+leaves the numbers out. Pages printed one per sheet are not numbered.
+
+#### Booklets
+
+`--booklet` lays the pages out two-up in the order that folds into a booklet.
+Print the file double-sided at 100% scale, flipping on the **long** edge. The
+back of every sheet is drawn upside down so that it comes out the right way up
+from a long-edge duplexer. For a printer that flips on the short edge, pass
+`--flip-on-edge short` and the backs are drawn the right way up.
+
+```
+nbk2pdf --booklet notebook/                  # every sheet folded together
+nbk2pdf --booklet --signature 4 notebook/    # signatures of 4 sheets, 16 pages
+nbk2pdf --booklet --flip-on-edge short notebook/
+```
+
+By default all the sheets are folded together down the middle into one
+booklet, padded to whole sheets with blank pages at the end. A thick notebook
+does not fold well as one stack, so `--signature` splits it into signatures of
+that many sheets each. Fold each signature on its own, then stack them in order
+to sew or staple them. The last signature is padded with blank pages to the
+same thickness as the others, so the spine stays even.
+
+Blank pages are not numbered, so the numbers follow the notebook.
+
 #### Stroke taper
 
 The pen records a 12-bit pressure per point, and it varies a lot inside a single

data/lib/kindle_notebook/cli.rb

@@ -52,7 +52,7 @@ module KindleNotebook
       @out = out
       @err = err
       @device = device
-      @options = { template: true, quiet: false, annotations: false }
+      @options = { template: true, quiet: false, annotations: false, two_up: false, page_numbers: true }
     end
 
     # Runs the command and returns the process exit status.
@@ -105,12 +105,34 @@ module KindleNotebook
       opts.on("-p", "--paper SIZE", "Page size: letter (default), a4, native, ...") do |size|
         options[:paper] = size
       end
+      define_layout_options(opts)
       opts.on("-a", "--annotations", "Add ink to a PDF as annotations, not drawn into the page") do
         options[:annotations] = true
       end
       opts.on("-q", "--quiet", "Only report errors") { options[:quiet] = true }
     end
 
+    def define_layout_options(opts)
+      opts.on("-2", "--two-up", "Put notebook pages in pairs side by side on landscape paper") do
+        options[:two_up] = true
+      end
+      opts.on("-b", "--booklet", "Lay notebook pages out to fold into a booklet") do
+        options[:booklet] ||= {}
+      end
+      opts.on("--signature SHEETS", Integer, "Fold the --booklet in signatures of SHEETS sheets each") do |sheets|
+        raise OptionParser::InvalidArgument, "--signature #{sheets}" unless sheets.positive?
+
+        (options[:booklet] ||= {})[:signature] = sheets
+      end
+      opts.on("--flip-on-edge EDGE", %w[long short],
+              "Edge the printer flips a --booklet on: long (default) or short") do |edge|
+        (options[:booklet] ||= {})[:flip] = edge.to_sym
+      end
+      opts.on("--[no-]page-numbers", "Number the pages when --two-up or --booklet (default: yes)") do |number|
+        options[:page_numbers] = number
+      end
+    end
+
     def convert(paths)
       sources = paths.flat_map { |path| Converter.document?(path) ? [File.expand_path(path)] : Notebook.find(path) }
       sources = with_documents(sources)
@@ -231,7 +253,9 @@ module KindleNotebook
     def converter
       @converter ||= Converter.new(titles: titles, render_template: options[:template],
                                    paper: PdfRenderer.paper(options[:paper]),
-                                   annotations: options[:annotations])
+                                   annotations: options[:annotations],
+                                   two_up: options[:two_up], page_numbers: options[:page_numbers],
+                                   booklet: options[:booklet])
     end
 
     def titles = @titles ||= Titles.load(options[:titles])

data/lib/kindle_notebook/converter.rb

@@ -16,10 +16,10 @@ module KindleNotebook
     # +titles+ maps a notebook uuid (or book id) to the name you know it by on
     # the device, since standalone notebooks do not store their own title.
     # +annotations+ adds ink to a document as annotations rather than drawing
-    # it into the page.
-    def initialize(titles: {}, render_template: true, paper: PdfRenderer.paper, annotations: false)
+    # it into the page. The remaining options go to PdfRenderer.
+    def initialize(titles: {}, annotations: false, **rendering)
       @titles = titles
-      @renderer = PdfRenderer.new(render_template: render_template, paper: paper)
+      @renderer = PdfRenderer.new(**rendering)
       @documents = DocumentRenderer.new(annotations: annotations)
       @written = {}
     end

data/lib/kindle_notebook/pdf_renderer.rb

@@ -44,20 +44,72 @@ module KindleNotebook
     # sub-paths instead of one per sample point.
     WIDTH_LEVELS = 8
 
+    # Two-up sheets keep this much space around and between their pages, so
+    # neither page touches the other or the edge of the sheet.
+    SHEET_MARGIN = 18
+
+    # Page numbers sit centred under each page of a two-up sheet, in a band
+    # reserved below it.
+    NUMBER_SIZE = 8
+    NUMBER_BAND = NUMBER_SIZE + 4
+    NUMBER_COLOR = "A0A0A0"
+
     # +paper+ is a resolved [width, height], or nil for the device's own size.
-    def initialize(render_template: true, paper: self.class.paper)
+    # +two_up+ puts pages in pairs side by side on the paper turned landscape;
+    # +page_numbers+ then numbers each of them. +booklet+, when given, is a
+    # hash of the options PdfRenderer.booklet takes; it implies +two_up+.
+    def initialize(render_template: true, paper: self.class.paper, two_up: false, page_numbers: true,
+                   booklet: nil)
       @render_template = render_template
       @paper = paper
+      @two_up = two_up || !booklet.nil?
+      @page_numbers = page_numbers
+      @booklet = booklet
+    end
+
+    # The sides of a booklet's sheets in print order, each as
+    # [[left, right], turned] taken from +items+, nil for a blank side of a
+    # leaf. All the items are folded together in one signature of whole
+    # sheets. Given +signature+, they are split into signatures of that many
+    # sheets instead, each folded on its own and stacked in order; the last is
+    # padded with blanks to the same thickness as the others, unless
+    # everything fits in one, which then shrinks to whole sheets.
+    #
+    # +flip+ is the edge the printer turns the sheet over on. Flipping on the
+    # :long edge lands the back of each sheet upside down, so it is drawn
+    # turned and with its halves swapped; on the :short edge it is drawn as is.
+    def self.booklet(items, signature: nil, flip: :long)
+      whole = ((items.size + 3) / 4) * 4
+      capacity = signature ? [signature * 4, whole].min : whole
+      (0...items.size).step(capacity).flat_map do |first|
+        fold_order(capacity).map { |local| items[first + local] }
+                            .each_slice(4).flat_map do |front_left, front_right, back_left, back_right|
+          back = flip == :short ? [[back_left, back_right], false] : [[back_right, back_left], true]
+          [[[front_left, front_right], false], back]
+        end
+      end
     end
 
+    # Local page indices of one signature in print order, four per sheet: the
+    # front carries the last page on the left and the first on the right, the
+    # back the next two in.
+    def self.fold_order(capacity)
+      (0...(capacity / 2)).step(2).flat_map do |left|
+        right = capacity - 1 - left
+        [right, left, left + 1, right - 1]
+      end
+    end
+    private_class_method :fold_order
+
     # +destination+ may be a path or any IO that responds to #write.
     def render(pages, destination, title: nil)
       raise Error, "notebook has no pages" if pages.empty?
 
-      document = new_document(pages.first, title)
-      pages.each_with_index do |page, index|
-        document.start_new_page(size: page_size(page), margin: 0) unless index.zero?
-        draw_page(document, page)
+      sides = layout(pages)
+      document = new_document(sheet_size(side_page(sides.first, pages)), title)
+      sides.each_with_index do |side, index|
+        document.start_new_page(size: sheet_size(side_page(side, pages)), margin: 0) unless index.zero?
+        draw_side(document, side, side_page(side, pages))
       end
       emit(document, destination)
     end
@@ -85,9 +137,9 @@ module KindleNotebook
 
     private
 
-    def new_document(first_page, title)
+    def new_document(size, title)
       Prawn::Document.new(
-        page_size: page_size(first_page),
+        page_size: size,
         margin: 0,
         info: {
           Title: title,
@@ -106,28 +158,94 @@ module KindleNotebook
       destination
     end
 
-    def page_size(page) = @paper || [page.width_in_points, page.height_in_points]
+    # Each side of a sheet is [slots, turned], a slot being [page, number], or
+    # nil where a booklet leaves a blank.
+    def layout(pages)
+      slots = pages.each_with_index.map { |page, index| [page, index + 1] }
+      return slots.map { |slot| [[slot], false] } unless @two_up
+      return slots.each_slice(2).map { |pair| [pair, false] } unless @booklet
+
+      self.class.booklet(slots, **@booklet)
+    end
+
+    # The page that sets a side's size. A side left wholly blank takes the size
+    # of the notebook's first page.
+    def side_page(side, pages) = side.first.compact.first&.first || pages.first
+
+    # A two-up sheet on the device's own size is just wide enough for its two
+    # pages at full size, plus the margins and the band for numbers.
+    def sheet_size(page)
+      return @paper || [page.width_in_points, page.height_in_points] unless @two_up
+      return [@paper.max, @paper.min] if @paper
+
+      [(page.width_in_points * 2) + (SHEET_MARGIN * 3),
+       page.height_in_points + (SHEET_MARGIN * 2) + number_band]
+    end
+
+    def draw_side(document, side, page)
+      return draw_two_up(document, side, page) if @two_up
+
+      draw_page(document, page, @paper && [0, 0, *@paper])
+    end
+
+    def number_band = @page_numbers ? NUMBER_BAND : 0
+
+    # A pair of pages, left and right, each fitted into its half of the sheet.
+    # An odd last page sits alone on the left.
+    def draw_two_up(document, (slots, turned), reference)
+      sheet_width, sheet_height = sheet_size(reference)
+      width = (sheet_width - (SHEET_MARGIN * 3)) / 2.0
+      height = sheet_height - (SHEET_MARGIN * 2) - number_band
+      upside_down(document, turned, sheet_width, sheet_height) do
+        slots.each_with_index do |(page, number), column|
+          next if page.nil?
+
+          box = [SHEET_MARGIN + (column * (width + SHEET_MARGIN)), SHEET_MARGIN + number_band, width, height]
+          draw_page(document, page, box)
+          draw_number(document, page, box, number) if @page_numbers
+        end
+      end
+    end
 
-    def draw_page(document, page)
+    def upside_down(document, turned, width, height, &)
+      turned ? document.rotate(180, origin: [width / 2.0, height / 2.0], &) : yield
+    end
+
+    def draw_number(document, page, box, number)
+      scale, x, y = placement(page, box)
+      text = number.to_s
+      left = x + (((page.width_in_points * scale) - document.width_of(text, size: NUMBER_SIZE)) / 2)
+      document.fill_color(NUMBER_COLOR)
+      document.draw_text(text, size: NUMBER_SIZE, at: [left, y - NUMBER_BAND])
+    end
+
+    # +box+ is [x, y, width, height] to fit the page into, or nil to draw it
+    # at the device's own size.
+    def draw_page(document, page, box)
       document.cap_style(:round)
       document.join_style(:round)
-      fitted(document, page) do
+      fitted(document, page, box) do
         draw_template(document, page) if @render_template
         page.strokes.each { |stroke| draw_stroke(document, page, stroke) }
       end
     end
 
-    # On a chosen paper size the canvas is scaled to fit and centred, keeping
-    # its proportions, so nothing is stretched or cropped.
-    def fitted(document, page, &)
-      return yield if @paper.nil?
+    def fitted(document, page, box, &)
+      return yield if box.nil?
 
-      width = page.width_in_points
-      height = page.height_in_points
-      scale = [@paper.first / width, @paper.last / height].min
-      document.transformation_matrix(scale, 0, 0, scale,
-                                     (@paper.first - (width * scale)) / 2,
-                                     (@paper.last - (height * scale)) / 2, &)
+      scale, x, y = placement(page, box)
+      document.transformation_matrix(scale, 0, 0, scale, x, y, &)
+    end
+
+    # The canvas is scaled to fit +box+ and centred in it, keeping its
+    # proportions, so nothing is stretched or cropped. Answers the scale and
+    # where the canvas's lower left corner lands.
+    def placement(page, box)
+      x, y, width, height = box
+      scale = [width / page.width_in_points, height / page.height_in_points].min
+      [scale,
+       x + ((width - (page.width_in_points * scale)) / 2),
+       y + ((height - (page.height_in_points * scale)) / 2)]
     end
 
     def draw_template(document, page)

data/lib/kindle_notebook/version.rb

@@ -3,7 +3,7 @@
 # frozen_string_literal: true
 
 module KindleNotebook
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 
   # The name this library is published and invoked under.
   PROGRAM = "nbk2pdf"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nbk2pdf
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Sergey Avseyev