docpdf 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52751516c7b9baebff20d8f3f9bfae0f9b50753497bedd37a0b690da45b5e22d
-  data.tar.gz: 211a5c562468626013b8427963c28cd4d2b410b24b688fe7ad5dd994566b8aba
+  metadata.gz: b68eda5d7355d1d3a227ef71f44d41f95dc7ccbfe7b08af17739e629c9ab26dc
+  data.tar.gz: 23e0ab911eb89df49eeac3634b50ef6d8bf8f7b74a8861067e2a0e44f3946e82
 SHA512:
-  metadata.gz: dd27677faa12f3ed9e21e66282e8efac2c8e2abbf232a9dc4fd5cc6927da1a7eb0c85ba992ac2672035f7eb01a9c4232fd060ff1113c3a2ebc66b0722c19ac0f
-  data.tar.gz: 969269269d255c41d6364f6650154a3dfa6c4ba9919e4a5492b9c35e8c74d3277c3aa1d3c0dfd4a8cf4e02cd19cc7b8f895f16d2ff90121b6d342830a113456d
+  metadata.gz: 14aff5944d6ac087f241b078c557e480974f322ca2cbcf3c9d08136e6b37f6598ca1bbd17e14267b060632e83e54491dbb5dc6a42b15768eb64883bbe3fd7838
+  data.tar.gz: cb43492ce6e3b7257e3c6cc01281904c509dcb473f77e932361ae986f0f39cda9af3bc0a4080b2e8c7d24e2c13adf6d4a8b93230ed455eef6b6ed74ede98e301

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.1.6] - 2026-09-18
+
+### Added
+- `font_file` registers a TrueType font for text conversion (`config.text_options`) and text watermarks (`config.watermark_options`, or per stamp). PDF's built-in fonts are limited to Windows-1252, so Cyrillic, Greek and other non-Latin text previously raised `ConversionError` with no way around it. Takes a path for the regular weight or a hash of `normal`/`bold`/`italic`/`bold_italic`, and is supported by both text converters and both stampers.
+
+## [0.1.5] - 2026-09-18
+
+### Added
+- `config.converter` selects a preferred converter adapter, mirroring `config.stamper`. It only claims the mime types that adapter registered for, so everything else still resolves in registration order and `config.converter = :hexapdf` does not disturb Word or image conversion.
+
+### Fixed
+- Watermarking a structurally valid PDF with an empty page tree raised `NoMethodError` instead of a `DocPDF::ConversionError`. Both stampers and the per-page watermark path now raise `ConversionError` with a clear message.
+- Plain text containing U+2028 LINE SEPARATOR or U+2029 PARAGRAPH SEPARATOR crashed the Prawn converter, since Windows-1252 has no room for them. Both are now translated to a newline, which is what they mean, so text pasted out of word processors and web pages converts cleanly.
+- Adapters no longer leak third-party exceptions to callers rescuing `DocPDF::Error`. The Prawn converter wraps every `Prawn::Errors` class plus `Encoding::UndefinedConversionError`, and both stampers wrap a missing watermark image file.
+
 ## [0.1.4] - 2026-04-08
 
 ### Fixed

data/README.md

@@ -9,7 +9,7 @@
 Convert documents from any common format to PDF, with optional watermarking. Zero hard dependencies; bring your own PDF library.
 
 [![CI](https://github.com/velocity-labs/docpdf/actions/workflows/ci.yml/badge.svg)](https://github.com/velocity-labs/docpdf/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/docpdf.svg)](https://rubygems.org/gems/docpdf)
+[![Gem Version](https://img.shields.io/gem/v/docpdf?label=gem%20version&color=D3AF37&cacheSeconds=3600)](https://rubygems.org/gems/docpdf)
 
 <br clear="left">
 
@@ -197,12 +197,18 @@ DocPDF.configure do |config|
   # Stamper adapter for watermarking (default: nil, auto-detects hexapdf then combine_pdf)
   config.stamper = :hexapdf  # or :combine_pdf
 
+  # Preferred converter adapter (default: nil, uses registration order)
+  # Only applies to the MIME types that adapter registered for; everything else
+  # still resolves normally, so this will not affect Word or image conversion.
+  config.converter = :hexapdf  # or :prawn, :rmagick, :mini_magick, ...
+
   # Page size (default: "LETTER")
   config.page_size = "A4"
 
   # Plain text file conversion defaults
   config.text_options = {
     font: "Helvetica",          # default: "Courier"
+    font_file: nil,             # default: nil (see "Non-Latin text" below)
     font_size: 12,              # default: 10
     margins: [72, 72, 72, 72],  # default: [50, 50, 50, 50] (points: top, right, bottom, left)
     color: "000000",            # default: "333333" (hex)
@@ -211,6 +217,7 @@ DocPDF.configure do |config|
   # Text watermark defaults (per-stamp options override these)
   config.watermark_options = {
     font: "Times",       # default: "Helvetica"
+    font_file: nil,      # default: nil (see "Non-Latin text" below)
     font_size: 96,       # default: 72
     color: "FF0000",     # default: "AAAAAA" (hex)
     rotation: 30,        # default: 45 (degrees counter-clockwise)
@@ -220,12 +227,49 @@ end
 
 Converter adapters (for format-to-PDF conversion) are auto-detected based on MIME type and gem availability. The first available adapter wins, in registration order:
 
-- **text/plain**: Prawn, then HexaPDF
+- **text/plain**: Prawn, then HexaPDF (set `config.converter` to reverse this)
 - **image/\***: RMagick, then MiniMagick
 - **Office formats**: LibreOffice (always available if installed)
 - **application/pdf**: Passthrough (returned unchanged)
 - **Unknown formats**: Fallback (tries LibreOffice, then returns raw data)
 
+### Non-Latin text
+
+PDF's built-in fonts only cover the Windows-1252 character set, so text outside it
+(Cyrillic, Greek, CJK, emoji, and many accented forms) cannot be rendered and raises
+`DocPDF::ConversionError`. Point `font_file` at a TrueType font to lift that limit:
+
+```ruby
+DocPDF.configure do |config|
+  config.text_options = config.text_options.merge(
+    font: "DejaVuSans",
+    font_file: "/path/to/DejaVuSans.ttf"
+  )
+end
+
+DocPDF.convert("resume.txt")  # renders Cyrillic, Greek, and more
+```
+
+`font_file` takes a path for the regular weight, or a hash to register several styles:
+
+```ruby
+font_file: {
+  normal:      "/fonts/DejaVuSans.ttf",
+  bold:        "/fonts/DejaVuSans-Bold.ttf",
+  italic:      "/fonts/DejaVuSans-Oblique.ttf",
+  bold_italic: "/fonts/DejaVuSans-BoldOblique.ttf"
+}
+```
+
+The same option works for text watermarks, via `config.watermark_options` or per stamp:
+
+```ruby
+DocPDF.watermark("doc.pdf", { text: "ЧЕРНОВИК", font: "DejaVuSans", font_file: "/fonts/DejaVuSans.ttf" })
+```
+
+A font only renders the characters it actually contains. DejaVu covers Latin, Cyrillic
+and Greek but not CJK, so pick a font that covers the scripts you expect.
+
 ## Adapters
 
 DocPDF has two types of adapters:
@@ -235,8 +279,8 @@ DocPDF has two types of adapters:
 | Adapter | Gem | Formats |
 |---------|-----|---------|
 | Soffice | None (system) | Word, Excel, PowerPoint, ODF, CSV, HTML, RTF |
-| Prawn | `prawn` | Plain text |
-| HexaPDF | `hexapdf` | Plain text |
+| Prawn | `prawn` | Plain text (wraps long lines; built-in fonts are Windows-1252 only) |
+| HexaPDF | `hexapdf` | Plain text (wider character support; does not wrap long lines) |
 | RMagick | `rmagick` | JPEG, PNG, HEIC, WebP |
 | MiniMagick | `mini_magick` | JPEG, PNG, HEIC, WebP |
 | Passthrough | None | PDF (returned unchanged) |

data/lib/docpdf/adapters/converters/hexapdf.rb

@@ -1,5 +1,6 @@
 require "hexapdf"
 require_relative "base"
+require_relative "../../font_files"
 
 module DocPDF
   module Adapters
@@ -22,6 +23,7 @@ module DocPDF
             page_size = normalize_page_size(config.page_size)
 
             doc = HexaPDF::Document.new
+            register_font(doc, opts[:font], opts[:font_file])
             page = doc.pages.add(page_size)
             canvas = page.canvas
 
@@ -51,6 +53,13 @@ module DocPDF
 
           private
 
+          def register_font(doc, name, font_file)
+            map = FontFiles.for_hexapdf(font_file)
+            return unless map
+
+            doc.config["font.map"] = (doc.config["font.map"] || {}).merge(name => map)
+          end
+
           def normalize_page_size(size)
             return size if size.is_a?(Symbol)
 

data/lib/docpdf/adapters/converters/prawn.rb

@@ -1,5 +1,7 @@
 require "prawn"
 require_relative "base"
+require_relative "../../prawn_errors"
+require_relative "../../font_files"
 
 module DocPDF
   module Adapters
@@ -7,18 +9,38 @@ module DocPDF
       class Prawn < Base
         MIME_TYPES = %w[text/plain].freeze
 
+        # U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR mean "break the
+        # line", but Windows-1252 has no room for them, so Prawn's built-in fonts
+        # reject them. Text pasted out of word processors and web pages carries
+        # them routinely, so translate to a newline instead of failing on it.
+        LINE_SEPARATORS = /[

]/
+
         class << self
           def convert(data, _source_filename)
             config = DocPDF.configuration
             opts = config.text_options
-            content = data.dup.force_encoding("UTF-8")
+            content = normalize(data)
             pdf = ::Prawn::Document.new(page_size: config.page_size, margin: opts[:margins])
+            register_font(pdf, opts[:font], opts[:font_file])
             pdf.font(opts[:font], size: opts[:font_size])
             pdf.text content, color: opts[:color]
             pdf.render
-          rescue ::Prawn::Errors::UnknownFont, ::Prawn::Errors::CannotFit => e
+          rescue *PRAWN_ERRORS, ::Encoding::UndefinedConversionError => e
             raise ConversionError, "Prawn failed to render text to PDF: #{e.message}"
           end
+
+          private
+
+          def register_font(pdf, name, font_file)
+            families = FontFiles.for_prawn(font_file)
+            return unless families
+
+            pdf.font_families.update(name => families)
+          end
+
+          def normalize(data)
+            data.dup.force_encoding("UTF-8").gsub(LINE_SEPARATORS, "\n")
+          end
         end
       end
     end

data/lib/docpdf/adapters/stampers/combine_pdf.rb

@@ -1,6 +1,8 @@
 require "combine_pdf"
 require "prawn"
 require_relative "base"
+require_relative "../../prawn_errors"
+require_relative "../../font_files"
 
 module DocPDF
   module Adapters
@@ -10,6 +12,7 @@ module DocPDF
           def stamp(data, stamps, page_indices: nil)
             source = ::CombinePDF.parse(data)
             source_page = source.pages.first
+            raise ConversionError, "Cannot stamp a PDF with no pages" unless source_page
             page_w = source_page[:MediaBox][2].to_f
             page_h = source_page[:MediaBox][3].to_f
 
@@ -20,7 +23,7 @@ module DocPDF
               page << stamp_page if page_indices.nil? || page_indices.include?(idx)
             end
             source.to_pdf
-          rescue ::CombinePDF::ParsingError => e
+          rescue ::CombinePDF::ParsingError, *PRAWN_ERRORS, Errno::ENOENT => e
             raise ConversionError, "CombinePDF failed to stamp PDF: #{e.message}"
           end
 
@@ -60,6 +63,13 @@ module DocPDF
             [img_w, img_h]
           end
 
+          def register_font(pdf, name, font_file)
+            families = FontFiles.for_prawn(font_file)
+            return unless families
+
+            pdf.font_families.update(name => families)
+          end
+
           def render_image_stamp(pdf, stamp)
             page_w = pdf.bounds.width
             page_h = pdf.bounds.height
@@ -86,6 +96,7 @@ module DocPDF
             page_w = pdf.bounds.width
             page_h = pdf.bounds.height
 
+            register_font(pdf, stamp[:font], stamp[:font_file])
             pdf.font(stamp[:font])
             font_size = fit_font_size(stamp[:font_size], stamp[:text], pdf, page_w, page_h)
             text_w = pdf.width_of(stamp[:text], size: font_size)

data/lib/docpdf/adapters/stampers/hexapdf.rb

@@ -1,5 +1,6 @@
 require "hexapdf"
 require_relative "base"
+require_relative "../../font_files"
 
 module DocPDF
   module Adapters
@@ -9,6 +10,7 @@ module DocPDF
           def stamp(data, stamps, page_indices: nil)
             doc = HexaPDF::Document.new(io: StringIO.new(data))
             source_page = doc.pages[0]
+            raise ConversionError, "Cannot stamp a PDF with no pages" unless source_page
             page_w = source_page.box.width
             page_h = source_page.box.height
 
@@ -21,7 +23,7 @@ module DocPDF
             end
 
             write_to_string(doc)
-          rescue HexaPDF::Error => e
+          rescue HexaPDF::Error, Errno::ENOENT => e
             raise ConversionError, "HexaPDF failed to stamp PDF: #{e.message}"
           end
 
@@ -87,6 +89,7 @@ module DocPDF
             page_w = page.box.width
             page_h = page.box.height
 
+            register_font(doc, stamp[:font], stamp[:font_file])
             font = doc.fonts.add(stamp[:font])
             glyph_units = font.decode_utf8(stamp[:text]).sum { |g| g.width }
             font_size = fit_font_size(stamp[:font_size], glyph_units, page_w, page_h)
@@ -115,6 +118,13 @@ module DocPDF
             end
           end
 
+          def register_font(doc, name, font_file)
+            map = FontFiles.for_hexapdf(font_file)
+            return unless map
+
+            doc.config["font.map"] = (doc.config["font.map"] || {}).merge(name => map)
+          end
+
           def write_to_string(doc)
             io = StringIO.new
             doc.write(io)

data/lib/docpdf/configuration.rb

@@ -1,6 +1,7 @@
 module DocPDF
   class Configuration
     attr_accessor :soffice_path,
+                  :converter,
                   :stamper,
                   :page_size,
                   :text_options,
@@ -8,6 +9,7 @@ module DocPDF
 
     TEXT_DEFAULTS = {
       font: "Courier",
+      font_file: nil,
       font_size: 10,
       margins: [50, 50, 50, 50],
       color: "333333",
@@ -15,6 +17,7 @@ module DocPDF
 
     WATERMARK_DEFAULTS = {
       font: "Helvetica",
+      font_file: nil,
       font_size: 72,
       color: "AAAAAA",
       rotation: 45,
@@ -22,6 +25,7 @@ module DocPDF
 
     def initialize
       @soffice_path      = "soffice"
+      @converter          = nil
       @stamper            = nil
       @page_size          = "LETTER"
       @text_options       = TEXT_DEFAULTS.dup

data/lib/docpdf/converter_resolver.rb

@@ -8,12 +8,44 @@ module DocPDF
       end
 
       def resolve(mime_type)
+        configured = DocPDF.configuration.converter
+        return resolve_configured(configured, mime_type) if configured
+
+        resolve_registered(mime_type)
+      end
+
+      private
+
+      def load_adapter(entry)
+        require entry[:require_name] if entry[:require_name]
+        entry[:loader].call
+      end
+
+      # A configured converter only claims the mime types it registered for, so
+      # anything else still falls through to the normal registration order. That
+      # keeps config.converter = :hexapdf from breaking Word conversion.
+      def resolve_configured(name, mime_type)
+        entry = @adapters.find { |e| e[:name] == name }
+        unless entry
+          valid_names = @adapters.map { |e| e[:name].inspect }.join(", ")
+          raise AdapterNotFoundError, "Unknown converter: #{name.inspect}. Valid converters are: #{valid_names}."
+        end
+
+        return resolve_registered(mime_type) unless entry[:mime_types].include?(mime_type)
+
+        begin
+          load_adapter(entry)
+        rescue LoadError => e
+          raise AdapterNotFoundError, "Converter #{name.inspect} requires gems that are not installed: #{e.message}"
+        end
+      end
+
+      def resolve_registered(mime_type)
         missing_gems = []
 
         @adapters.each do |entry|
           next unless entry[:mime_types].include?(mime_type)
-          require entry[:require_name] if entry[:require_name]
-          return entry[:loader].call
+          return load_adapter(entry)
         rescue LoadError
           missing_gems << entry[:require_name]
           next
@@ -27,8 +59,6 @@ module DocPDF
         resolve_fallback
       end
 
-      private
-
       def resolve_fallback
         entry = @adapters.find { |e| e[:name] == :fallback }
         raise AdapterNotFoundError, "No converter found and no fallback registered." unless entry

data/lib/docpdf/font_files.rb

@@ -0,0 +1,35 @@
+module DocPDF
+  # Prawn's built-in AFM fonts only cover Windows-1252, so any text outside it
+  # fails to render. Pointing an adapter at a TrueType file lifts that limit.
+  # Each backend wants the styles keyed differently, so normalize once here.
+  module FontFiles
+    STYLES = %i[normal bold italic bold_italic].freeze
+
+    # HexaPDF calls the unstyled variant :none where Prawn calls it :normal.
+    HEXAPDF_STYLES = { normal: :none, bold: :bold, italic: :italic, bold_italic: :bold_italic }.freeze
+
+    class << self
+      # Accepts a path for the regular weight, or a hash of styles:
+      #   "DejaVuSans.ttf"
+      #   { normal: "...", bold: "...", italic: "...", bold_italic: "..." }
+      def normalize(font_file)
+        return if font_file.nil?
+        return { normal: font_file.to_s } if font_file.is_a?(String) || font_file.is_a?(Pathname)
+
+        styles = font_file.to_h.transform_keys(&:to_sym).slice(*STYLES)
+        styles.empty? ? nil : styles.transform_values(&:to_s)
+      end
+
+      def for_hexapdf(font_file)
+        styles = normalize(font_file)
+        return unless styles
+
+        styles.each_with_object({}) { |(style, path), map| map[HEXAPDF_STYLES.fetch(style)] = path }
+      end
+
+      def for_prawn(font_file)
+        normalize(font_file)
+      end
+    end
+  end
+end

data/lib/docpdf/prawn_errors.rb

@@ -0,0 +1,14 @@
+require "prawn"
+
+module DocPDF
+  # Prawn defines every error class directly under StandardError with no shared
+  # ancestor, so there is no namespace to rescue. Collecting them lets adapters
+  # wrap the whole family in DocPDF::ConversionError rather than leaking Prawn's
+  # exceptions to callers who only rescue DocPDF::Error.
+  #
+  # Only require this from files that already require "prawn"; prawn is optional.
+  PRAWN_ERRORS = ::Prawn::Errors.constants
+                                .map { |name| ::Prawn::Errors.const_get(name) }
+                                .select { |const| const.is_a?(Class) && const <= StandardError }
+                                .freeze
+end

data/lib/docpdf/version.rb

@@ -1,3 +1,3 @@
 module DocPDF
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

data/lib/docpdf/watermarker.rb

@@ -46,7 +46,7 @@ module DocPDF
         merged = STAMP_DEFAULTS.merge(stamp)
         if merged[:text]
           wm = DocPDF.configuration.watermark_options
-          { font: wm[:font], font_size: wm[:font_size], color: wm[:color], rotation: wm[:rotation] }.merge(merged)
+          { font: wm[:font], font_file: wm[:font_file], font_size: wm[:font_size], color: wm[:color], rotation: wm[:rotation] }.merge(merged)
         else
           merged
         end
@@ -138,6 +138,8 @@ module DocPDF
 
     def stamp_per_page(stamper)
       page_count = pdf_page_count
+      raise ConversionError, "Cannot stamp a PDF with no pages" if page_count.zero?
+
       result = @pdf_bytes
 
       build_page_stamp_map(page_count).each do |page_indices, stamps_for_pages|

data/lib/docpdf.rb

@@ -1,6 +1,7 @@
 require "docpdf/version"
 require "docpdf/configuration"
 require "docpdf/errors"
+require "docpdf/font_files"
 require "docpdf/result"
 require "docpdf/input_normalizer"
 require "docpdf/mime_detector"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docpdf
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Velocity Labs, LLC
@@ -38,8 +38,10 @@ files:
 - lib/docpdf/converter.rb
 - lib/docpdf/converter_resolver.rb
 - lib/docpdf/errors.rb
+- lib/docpdf/font_files.rb
 - lib/docpdf/input_normalizer.rb
 - lib/docpdf/mime_detector.rb
+- lib/docpdf/prawn_errors.rb
 - lib/docpdf/result.rb
 - lib/docpdf/stamper_resolver.rb
 - lib/docpdf/version.rb