docpdf 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43cbb73b198ee9a4c207afbdf359ffa4ce79b2c66e372169049fe622cce4f562
-  data.tar.gz: f08f6d9e7fd5b82a9b69f4e5402b94c4ab8a627c7468ad36373d6842458f2299
+  metadata.gz: 4fa01d67dead11a1f62eb4ff7f6f387599b97ec99d0c91bd5644e60e98fd26a6
+  data.tar.gz: 1dc447f55133af1a3ff94ad3aaaeca8014a1560cdd6db5cf2d85ab30220afa1e
 SHA512:
-  metadata.gz: 3612856e07798bbee41cd5a2dea00dd21ea67aadd2b4c8412fe2afd4c13dc9f91a334833373ba8f099b7bae1392e6756736da848085a2f2e3a3a04ef962568f0
-  data.tar.gz: 53b3025fab9d38dc1bf0d8b960b42088d49b73e4a05f79b6025b18bb9f912bde8da2d0dfacf571bc2b11f12e6c47b9266ef3f30d637e4c1fe1ae59ec937699e4
+  metadata.gz: 3cfa330a65d41f8c24866b04da28d15a795df5c826f2459a9ae1c46c86c470147e92c6ff75952579d3bfd3b6fd4804747a712b868fc829102fab3ece963d0a2d
+  data.tar.gz: aa22481e4dfbb0966c9f95b1ecd5924680c491729a3c0ac8b873d2aca03c49b4889a936ce57400a3681594c5ac18078da66c8fa78b20cbed9da211316115f883

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.7] - 2026-10-08
+
+### Fixed
+- The HexaPDF stamper raised `ConversionError` on PDFs with spec violations HexaPDF cannot correct, even though viewers render them fine. One example is a tagged PDF exported from Canva with a structure element missing its parent. The stamper now corrects what HexaPDF can and writes the rest as it came in, the way the `hexapdf` CLI does.
+- `DocPDF.convert` raised `NameError: uninitialized constant DocPDF::InputNormalizer::Pathname` on Ruby 3.3 and 3.4 when nothing else had loaded `pathname`. Bundler and Rails both load it, so only plain Ruby scripts were affected. `DocPDF.watermark` with a file path and `font_file` given as a hash hit the same error. DocPDF now requires `pathname` itself.
+
+## [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

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">
 
@@ -208,6 +208,7 @@ DocPDF.configure do |config|
   # 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)
@@ -216,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)
@@ -231,6 +233,43 @@ Converter adapters (for format-to-PDF conversion) are auto-detected based on MIM
 - **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:

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,6 +1,7 @@
 require "prawn"
 require_relative "base"
 require_relative "../../prawn_errors"
+require_relative "../../font_files"
 
 module DocPDF
   module Adapters
@@ -20,6 +21,7 @@ module DocPDF
             opts = config.text_options
             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
@@ -29,6 +31,13 @@ module DocPDF
 
           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

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

@@ -2,6 +2,7 @@ require "combine_pdf"
 require "prawn"
 require_relative "base"
 require_relative "../../prawn_errors"
+require_relative "../../font_files"
 
 module DocPDF
   module Adapters
@@ -62,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
@@ -88,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
@@ -21,7 +22,7 @@ module DocPDF
               page.canvas(type: :overlay).xobject(stamp_form, at: [0, 0]) if page_indices.nil? || page_indices.include?(idx)
             end
 
-            write_to_string(doc)
+            write_to_string_leniently(doc)
           rescue HexaPDF::Error, Errno::ENOENT => e
             raise ConversionError, "HexaPDF failed to stamp PDF: #{e.message}"
           end
@@ -88,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)
@@ -116,11 +118,30 @@ module DocPDF
             end
           end
 
-          def write_to_string(doc)
+          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, **write_options)
             io = StringIO.new
-            doc.write(io)
+            doc.write(io, **write_options)
             io.string
           end
+
+          # The caller's PDF may break the spec in ways HexaPDF cannot repair, like a
+          # tagged PDF whose structure elements have no parent. Viewers open those
+          # fine, so correct what can be corrected and write the rest as it came in,
+          # the way the hexapdf CLI does. Objects are validated one at a time because
+          # Document#validate stops at the first one it cannot correct, and the stamp
+          # form only becomes an indirect object when validation reaches its page.
+          def write_to_string_leniently(doc)
+            doc.trailer.validate(auto_correct: true)
+            doc.each { |obj| obj.validate(auto_correct: true) }
+            write_to_string(doc, validate: false)
+          end
         end
       end
     end

data/lib/docpdf/configuration.rb

@@ -9,6 +9,7 @@ module DocPDF
 
     TEXT_DEFAULTS = {
       font: "Courier",
+      font_file: nil,
       font_size: 10,
       margins: [50, 50, 50, 50],
       color: "333333",
@@ -16,6 +17,7 @@ module DocPDF
 
     WATERMARK_DEFAULTS = {
       font: "Helvetica",
+      font_file: nil,
       font_size: 72,
       color: "AAAAAA",
       rotation: 45,

data/lib/docpdf/font_files.rb

@@ -0,0 +1,37 @@
+require "pathname"
+
+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/input_normalizer.rb

@@ -1,3 +1,5 @@
+require "pathname"
+
 module DocPDF
   class InputNormalizer
     attr_reader :data, :filename, :source_filename, :mime_type

data/lib/docpdf/version.rb

@@ -1,3 +1,3 @@
 module DocPDF
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/docpdf/watermarker.rb

@@ -1,3 +1,5 @@
+require "pathname"
+
 module DocPDF
   class Watermarker
     POSITIONS = %i[center top bottom left right top_left top_right bottom_left bottom_right].freeze
@@ -46,7 +48,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

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.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Velocity Labs, LLC
@@ -38,6 +38,7 @@ 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