hexapdf 0.46.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9c1a35d4ad93b48faa1f728bcddc91778da584c8d673e2f15557bd22050a438
-  data.tar.gz: 2ef8ca70891723643080a402f0808882f66f01a816c422477cc03fad34774859
+  metadata.gz: 35bbb5d1780d07ecf6098cc40359ff2cc02cd89231a124b6ff1a0a13c760d116
+  data.tar.gz: 8664f2ac8a6651ee83e7292d005ea10d89b7ea738de47cc62dbf219f4eae0cb4
 SHA512:
-  metadata.gz: 87c109bd8a6711b4df27a40c689a025d816075d6c68c21a1cc22924b5ae827cd44d98e45bff8f43c85403dd82d6a6e54b66c99bfe135298cba33292e9511a1fc
-  data.tar.gz: e0529e3e244be8366e722ea29ab06a8b922f18698526c79a28d5d11f02da5ee103cba71ecbc6882fefe3de27f02d38f8ce8b505fefbb45839069c74aefaed9ae
+  metadata.gz: 232aefc90eb4f9f9a913d27affa95a0c9eff43a72e04eeb1adc0fbe11e865033c6fd0b7779930b15a982afdd909d6ffa98640db6db668f95ce0c26332749cfae
+  data.tar.gz: e1b836a23d58e92ceb70f5b892d023edcf585288583f2254d35394688204bfdbf4401edea6562a96d1583a71a302d8d50e8a175262ff5077a3b4a2200ec922a4

data/CHANGELOG.md

@@ -1,3 +1,329 @@
+## 1.6.0 - 2026-02-10
+
+### Added
+
+* CLI command `hexapdf debug-info` for creating debugging information,
+  especially for malformed files
+
+### Changed
+
+* Optimized decoding character codes with a CMap to drastically lower memory
+  usage
+* CLI command `hexapdf inspect rev` to show whether the cross-reference table
+  was reconstructed
+
+### Fixed
+
+* Path generation for image extraction in CLI command `hexapdf images`
+* Handling of certain invalid PDFs where the generation number for object
+  identifiers don't match their cross-reference section value
+* AES 256bit encryption to include unnecessary field /Length in encryption
+  dictionary to work around buggy PDF libraries
+* Parsing of invalid /Filter and /DecodeParms stream keys in case they resolve
+  to a recursive structure
+* [HexaPDF::Type::AcroForm::Field#each_widget] to only yield widget objects
+
+
+## 1.5.0 - 2025-12-08
+
+### Added
+
+* Support for basic authentication to
+  [HexaPDF::DigitalSignature::Signing::TimestampHandler]
+
+### Changed
+
+* Dictionary validation to delete field entries that have an invalid type
+* CLI command `hexapdf images` to create directories specified in the `--prefix`
+* CLI command `hexapdf images` to omit the dash in the file names if `--prefix`
+  points to a directory
+
+## Fixed
+
+* [HexaPDF::Type::Annotation#appearance] to work in case /AP contains a value of
+  an invalid type
+* [HexaPDF::DigitalSignature::CMSHandler] to throw an appropriate error when
+  encountering invalid signature contents
+
+
+## 1.4.1 - 2025-09-23
+
+### Added
+
+* [HexaPDF::Font::Encoding::Base#to_compact_array] for creating a compact array
+  representation of the encoding
+
+### Changed
+
+- CLI to handle missing file errors better
+
+### Fixed
+
+* Serialization of strings that need to be UTF-16 encoded when using encryption
+* [HexaPDF::Document#write_to_string] to pass on arguments to `#write`
+* [HexaPDF::Type::FontType1] validation to handle PDFs with an invalid value of
+  /SymbolEncoding for the /Encoding key
+* [HexaPDF::Type::FontType1] validation to handle PDFs with an invalid value of
+  /StandardEncoding for the /Encoding key
+* CLI command `hexapdf form` to ignore widgets that don't belong to any field
+* Validation of invalid sorted tree root nodes with odd number of direct entries
+
+
+## 1.4.0 - 2025-08-03
+
+### Added
+
+* [HexaPDF::Type::Annotations::Polygon] for polygon annotations as well as
+  [HexaPDF::Document::Annotations#create_polygon]
+* [HexaPDF::Type::Annotations::Polyline] for polyline annotations as well as
+  [HexaPDF::Document::Annotations#create_polyline]
+* [HexaPDF::Layout::ContainerBox#splitable] for specifying whether the container
+  box may be split
+* [HexaPDF::Layout::Style::Layers#layers] for retrieving the list of defined
+  layers
+* [HexaPDF::Document::Layout#resolve_font] for resolving the font style property
+* [HexaPDF::Type::Measure] for representing the measure dictionary
+* [HexaPDF::Layout::Box::FitResult#failure!] for setting the result status to
+  failure
+
+### Changed
+
+* **Breaking change**: Extracted `#line_ending_style` and associated data class
+  from [HexaPDF::Type::Annotations::Line] into
+  [HexaPDF::Type::Annotations::LineEndingStyling]
+* [HexaPDF::Layout::TableBox] implementation to allow setting the minimum height
+  of a table cell
+* [HexaPDF::Layout::Style::Quad#set] to allow setting a subset of values using a
+  hash
+* CLI command `hexapdf form` to show the names of radio button widgets
+* CLI command `hexapdf form` to show position and size of widgets in easier to
+  understand form
+* Default signing handler to not set /DigestMethod entry on signature reference
+  dictionary anymore
+
+### Fixed
+
+* Parsing and writing the /ModDate and /CreationDate trailer info fields in case
+  of string values when using the XMP metadata handler
+* [HexaPDF::Layout::Style] to not accidentally set subscript or superscript
+  values
+* [HexaPDF::DictionaryFields::DateConverter] to handle invalid dates with two
+  trailing apostrophes
+* [HexaPDF::Document::Layout::CellArgumentCollector#retrieve_arguments_for] to
+  not change the stored data
+* Encryption when using AES with 256bits and an owner password
+
+
+## 1.3.0 - 2025-04-23
+
+### Added
+
+* [HexaPDF::Type::Annotations::Square] for rectangle annotations as well as
+  [HexaPDF::Document::Annotations#create_rectangle]
+* [HexaPDF::Type::Annotations::Circle] for ellipse annotations as well as
+  [HexaPDF::Document::Annotations#create_ellipse]
+* Basic appearance generation for push button fields
+* [HexaPDF::Type::Annotation::BorderEffect] type class
+* [HexaPDF::Type::Annotations::BorderEffect] module that provides convenience
+  access to the border effect dictionary
+* [HexaPDF::Document::Layout#style?] and [HexaPDF::Composer#style?] for checking
+  whether a given style (name) exists
+* [HexaPDF::Layout::Style#each_property] for iterating over all set properties
+* [HexaPDF::Layout::Style#merge] for merging another style instance
+* [HexaPDF::Layout::Style#box_options] for specifying box initialization options
+* [HexaPDF::Layout::Style#font_bold] and [HexaPDF::Layout::Style#font_italic]
+  for setting bold and/or italic variants independently of the font name
+* [HexaPDF::PDFArray#map!] for mapping elements in-place
+* [HexaPDF::PDFArray#compact!] for removing `nil` elements
+
+### Changed
+
+* **Breaking change**: [HexaPDF::Type::Annotations::Widget::MarkerStyle::new]
+  got a new positional argument
+* [HexaPDF::Type::Annotations::Widget#marker_style] to allow setting and
+  retrieving the font for push buttons
+* Extracted `#interior_color` from [HexaPDF::Type::Annotations::Line] into
+  [HexaPDF::Type::Annotations::InteriorColor]
+* CLI command `hexapdf inspect` to support decoding Form XObject streams
+* [HexaPDF::Layout::Style#line_spacing] to accept a `LineSpacing` object when
+  setting the value
+
+### Fixed
+
+* Text extraction with macOS Preview due a bug in Preview
+* [HexaPDF::PDFArray#reject!] to work according to documented method signature
+* [HexaPDF::Type::AcroForm::Field#create_widget] to ensure the proper type
+  class is stored in the document in case an embedded widget is extracted
+* [HexaPDF::Type::AcroForm::Form] validation to ensure that all field objects in
+  the field hierarchy are using a field type class
+* [HexaPDF::Type::AcroForm::Form] validation to delete merged fields
+
+
+## 1.2.0 - 2025-02-10
+
+### Added
+
+* **Breaking change**: Argument `compact` to [HexaPDF::Document#write] to
+  automatically run the 'compact' optimization task
+* [HexaPDF::Document::Annotations], accessible via
+  [HexaPDF::Document#annotations], as convenience interface for working with
+  annotations
+* [HexaPDF::Type::Annotations::AppearanceGenerator] as central class for
+  generating appearance streams
+* [HexaPDF::Type::Annotations::Line] for line annotations
+* [HexaPDF::Type::Annotation#opacity] for setting the opacity values when
+  regenerating the appearance stream
+* [HexaPDF::Type::Annotation#contents] for setting the text of the annotation
+* Configuration option 'acro_form.text_field.on_max_len_exceeded' to allow
+  custom handling of too long values
+
+### Changed
+
+* **Breaking change**: Extracted `#border_style` and associated data class from
+  [HexaPDF::Type::Annotations::Widget] into
+  [HexaPDF::Type::Annotations::BorderStyling]
+* [HexaPDF::Type::Form#canvas] to allow getting the canvas without the initial
+  translation
+
+### Fixed
+
+* AcroForm Javascript actions to gracefully handle the special values infinity
+  and NaN
+* Type1 and TrueType font wrappers to handle the case where fonts are first
+  added and later deleted
+
+
+## 1.1.1 - 2025-01-08
+
+### Fixed
+
+* Missing require statements leading to problems loading type classes
+
+
+## 1.1.0 - 2025-01-08
+
+### Added
+
+* Basic type classes for logical structure support
+
+### Changed
+
+* Optimized output of simple borders to avoid unnecessary drawing operations
+
+### Fixed
+
+* Type of field /DW for CIDFont which used to be Integer in PDF 1.7 but now is
+  Numeric inf 2.0
+* Validation of /ProcSet entry in resources dictionary to correctly handle the
+  case of /ProcSet having a Symbol value
+
+
+## 1.0.3 - 2024-12-04
+
+### Fixed
+
+* Offsets and lengths of revisions shown using the `inspect rev` CLI command for
+  linearized PDF files
+* [HexaPDF::Type::AcroForm::Form#recalculate_fields] to only consider real
+  fields
+
+
+## 1.0.2 - 2024-11-05
+
+### Added
+
+* [HexaPDF::Type::CMap] for representing CMap streams
+
+### Fixed
+
+* Checksum calculation for TrueType tables
+* Automatic wrapping of dictionary entry /CIDToGIDMap for CID fonts
+* Performance regression when encoding char codes for TrueType fonts
+* PDF/A validation regression for PDFs using TrueType fonts
+
+
+## 1.0.1 - 2024-11-04
+
+### Changed
+
+* Informational output on errors when running CLI commands to provide more
+  details
+
+### Fixed
+
+* Parsing of indirect objects the value of which is an indirect reference
+* Writing of the initial cross-reference section to ensure a single subsection
+* [HexaPDF::Utils::SortedTreeNode] to wrap all /Kids entries with the correct
+  type class
+
+
+## 1.0.0 - 2024-10-26
+
+### Added
+
+* [HexaPDF::Task::MergeAcroForm] for merging AcroForm information for imported
+  pages
+* [HexaPDF::Document#write_to_string] and [HexaPDF::Composer#write_to_string]
+  for easily writing a document to a String
+* [HexaPDF::Font::CMap::Writer#create_cid_cmap] for creating a character code to
+  CID CMap file
+
+### Changed
+
+* [HexaPDF::Type::AcroForm::Form] text-like field creation methods to always set
+  a default appearance string and the quadding
+* Convenience methods for accessing resources to not add the deprecated /ProcSet
+  entry by default
+* [HexaPDF::DigitalSignature::CMSHandler] to add informational output regarding
+  the certificate chain on verification
+* Validation of [HexaPDF::Type::FontType1] to ensure correct /Encoding value
+
+### Fixed
+
+* [HexaPDF::DigitalSignature::Signature#signed_data] to work for invalid offsets
+* [HexaPDF::DigitalSignature::Signing::DefaultHandler] to update the document's
+  version to 2.0 when using PAdES
+* Parsing of invalid `)` character in PDF objects and content streams
+* Handling of files that contain stream length values that are indirect objects
+  that do not exist
+* [HexaPDF::Font::TrueTypeWrapper] to correctly handle the situation when
+  multiple codepoints refer to the same glyph ID
+* [HexaPDF::Type::Page#contents] to handle null values in /Contents array
+
+
+## 0.47.0 - 2024-09-07
+
+### Added
+
+* Configuration option 'acro_form.fallback_default_appearance' to allow setting
+  a standard default appearance string for a variable text field if none is
+  found
+* Support for decrypting files with the proprietary algorithm /R 5
+
+### Changed
+
+* [HexaPDF::Task::Optimize] to not remove optional /Type entries containing
+  default values
+* Validation of [HexaPDF::Type::AcroForm::Form] to not add a /DA entry
+
+### Fixed
+
+* [HexaPDF::Layout::TableBox] to correctly calculcate and distribute row
+  heights when row spans are involved
+* [HexaPDF::Type::AcroForm::AppearanceGenerator] to work for files where check
+  boxes don't define the name of the on state
+* [HexaPDF::Importer#import] to handle null values in all cases
+* [HexaPDF::Type::AcroForm::VariableTextField] to handle parsing of invalid PDFs
+  with symbolic appearance strings
+* [HexaPDF::Type::Annotations::Widget#marker_style] to handle invalid /DA values
+  with missing font size or color information
+* [HexaPDF::Type::AcroForm::SignatureField#field_value] to always return a
+  correctly wrapped object
+* [HexaPDF::Writer] to remove /Type entry from trailer
+* [HexaPDF::Type::AcroForm::AppearanceGenerator#create_text_appearances] to
+  handle invalid appearance streams that are not correct Form XObjects
+
+
 ## 0.46.0 - 2024-08-11
 
 ### Added
@@ -20,7 +346,7 @@
   signatures
 * [HexaPDF::DigitalSignature::CMSHandler#signing_time] to use time from an
   embedded timestamp authority signature if possible
-* [HexaPDF::Layout::Box#fit] to return success for boxes with content
+* HexaPDF::Layout::Box#fit to return success for boxes with content
   width/height of zero
 * [HexaPDF::Importer::copy] to optionally allow copying the catalog and page
   tree nodes
@@ -28,7 +354,7 @@
 ### Fixed
 
 * Setting of correct x-position in fit result for boxes with flow positioning
-* [HexaPDF::Layout::ListBox#fit] to respect the set height
+* HexaPDF::Layout::ListBox#fit to respect the set height
 * CLI command `hexapdf inspect` to work in case of missing Unicde mappings
 * [HexaPDF::Type::AcroForm::Form#delete_field] to correctly work for fields with
   an embedded widget
@@ -47,7 +373,7 @@
 
 ### Changed
 
-* [HexaPDF::Layout::Box#fit] to set width/height correctly for boxes with
+* HexaPDF::Layout::Box#fit to set width/height correctly for boxes with
   position `:flow`
 
 ### Fixed
@@ -93,9 +419,9 @@
 
 ### Fixed
 
-* [HexaPDF::Layout::TextBox#fit] to correctly calculate width in case of flowing
+* HexaPDF::Layout::TextBox#fit to correctly calculate width in case of flowing
   text around other boxes
-* [HexaPDF::Layout::TextBox#draw] to correctly draw border, background... on
+* HexaPDF::Layout::TextBox#draw to correctly draw border, background... on
   boxes using position 'flow'
 * Comparison of Hash with [HexaPDF::Dictionary] objects by implementing
   `#to_hash`
@@ -149,7 +475,7 @@
   JavaScript action that formats the field's value
 * [HexaPDF::Type::AcroForm::TextField#set_calculate_action] for setting a
   JavaScript action that calculates the field's value
-* [HexaPDF::Type::AcroForm#recalculate_fields] for recalculating fields
+* [HexaPDF::Type::AcroForm::Form#recalculate_fields] for recalculating fields
 
 ### Changed
 
@@ -206,7 +532,7 @@
 
 ### Changed
 
-* [HexaPDF::Layout::Frame::FitResult#draw] to provide better optional content
+* HexaPDF::Layout::Frame::FitResult#draw to provide better optional content
   group names
 
 ### Fixed
@@ -285,8 +611,8 @@
 
 ### Changed
 
-* [HexaPDF::Layout::Frame::FitResult#draw] to allow drawing at an offset
-* [HexaPDF::Layout::Box#fit] to delegate the actual content fitting to the
+* HexaPDF::Layout::Frame::FitResult#draw to allow drawing at an offset
+* HexaPDF::Layout::Box#fit to delegate the actual content fitting to the
   `#fit_content` method
 * [HexaPDF::Document::Layout#box] to allow using the block as drawing block for
   the base box class
@@ -363,8 +689,8 @@
 
 ### Fixed
 
-* [HexaPDF::Layout::ColumnBox#fit] to correctly take initial height into account
-* [HexaPDF::Layout::ColumnBox#fit] to ensure correct results in case the
+* HexaPDF::Layout::ColumnBox#fit to correctly take initial height into account
+* HexaPDF::Layout::ColumnBox#fit to ensure correct results in case the
   requested dimensions are larger than the current region
 * [HexaPDF::Document::Layout#formatted_text_box] to correctly handle properties
 * [HexaPDF::Layout::Frame#fit] to raise an error if an invalid value for the
@@ -410,7 +736,7 @@
   context argument (a page or Form XObject instance)
 * [HexaPDF::Layout::ListBox] to use its 'fill_color' style property for the item
   marker color
-* [HexaPDF::Layout::Frame::FitResult#draw] to use optional content groups for
+* HexaPDF::Layout::Frame::FitResult#draw to use optional content groups for
   debug output
 
 ### Fixed
@@ -419,7 +745,7 @@
   default range starting at page 1
 * [HexaPDF::Type::Page#flatten_annotations] to correctly handle scaled
   appearances
-* Using an unknown style name in [HexaPDF:Document::Layout] method by providing
+* Using an unknown style name in [HexaPDF::Document::Layout] method by providing
   a useful error message
 * [HexaPDF::Layout::Box::new] to ensure that the properties attribute is always
   a hash
@@ -480,7 +806,7 @@
   final box positions into account
 * [HexaPDF::Content::Canvas#text] to set the leading only when multiple lines
   are drawn
-* [HexaPDF::Layout::TextBox#split] to use float comparison
+* HexaPDF::Layout::TextBox#split to use float comparison
 * Validation of standard encryption dictionary to auto-correct invalid /U and /O
   fields in case they are padded with zeros
 * [HexaPDF::Document#wrap] handling of sub-type mapping in case of missing type
@@ -897,7 +1223,7 @@
 * [HexaPDF::Layout::WidthFromPolygon] to work correctly in case of very small
   floating point errors
 * HexaPDF::Layout::TextFragment#inspect to work in case of interspersed numbers
-* [HexaPDF::Layout::TextBox#split] to work for position :flow when box is wider
+* HexaPDF::Layout::TextBox#split to work for position :flow when box is wider
   than the initial available width
 * [HexaPDF::Layout::Frame#fit] to create minimally sized mask rectangles
 * [HexaPDF::Content::GraphicObject::Geom2D] to close the path when drawing
@@ -1833,7 +2159,7 @@
   objects
 * [HexaPDF::Revision#each_modified_object] for iterating over all modified
   objects of a revision
-* [HexaPDF::Layout::Box#split] and [HexaPDF::Layout::TextBox#split] for
+* [HexaPDF::Layout::Box#split] and HexaPDF::Layout::TextBox#split for
   splitting a box into two parts
 * [HexaPDF::Layout::Frame#full?] for testing whether the frame has any space
   left

data/LICENSE

@@ -1,5 +1,5 @@
 HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-Copyright (C) 2014-2024 Thomas Leitner
+Copyright (C) 2014-2025 Thomas Leitner
 
 HexaPDF is free software: you can redistribute it and/or modify it
 under the terms of the GNU Affero General Public License version 3 as

data/README.md

@@ -13,7 +13,7 @@ In short, it allows
 * **securing** PDF files by encrypting or signing them and
 * **optimizing** PDF files for smaller file size or other criteria.
 
-HexaPDF is available under two license, the AGPL and a commercial license, see the [License
+HexaPDF is available under two licenses, the AGPL and a commercial license, see the [License
 section](#License) for details.
 
 
@@ -82,7 +82,7 @@ canvas.text("Hello World!", at: [20, 400])
 doc.write("hello-world.pdf")
 ~~~
 
-For detailed information have a look at the [HexaPDF website][website] where you will the API
+For detailed information have a look at the [HexaPDF website][website] where you will find the API
 documentation, example code and more.
 
 It is recommend to use the HTML API documentation provided by the HexaPDF website as it is enhanced
@@ -93,12 +93,13 @@ with example graphics and PDF files and tightly integrated into the rest of the
 
 ## Requirements and Installation
 
-Since HexaPDF is written in Ruby, a working Ruby installation is needed - see the
-[official installation documentation][rbinstall] for details. Note that you need Ruby version 2.6 or
-higher as prior versions are not supported!
+Since HexaPDF is written in Ruby, a working Ruby installation is needed - see the [official
+installation documentation][rbinstall] for details. Note that you need Ruby version 3.0 or higher as
+prior versions are not supported!
 
-HexaPDF works on all Ruby implementations that are CRuby compatible, e.g. TruffleRuby, and on any
-platform supported by Ruby (Linux, macOS, Windows, ...).
+HexaPDF works on all Ruby implementations that are CRuby compatible and on any platform supported by
+Ruby (Linux, macOS, Windows, ...). Implementations like JRuby and TruffleRuby should work but
+HexaPDF is not actively tested against them.
 
 Apart from Ruby itself the HexaPDF library has only one external dependency `geom2d` which is
 written and provided by the HexaPDF authors. The `hexapdf` application has an additional dependency
@@ -117,7 +118,7 @@ Prawn is a **library for generating content**.
 
 To be more specific, it is easily possible to read an existing PDF with HexaPDF and modify parts of
 it before writing it out again. The modifications can be to the PDF object structure like removing
-superfluous annotations or the the content itself.
+superfluous annotations or the content itself.
 
 Prawn has no such functionality. There is basic support for using a PDF as a template using the
 `pdf-reader` and `prawn-template` gems but support is very limited. However, Prawn has a very

data/examples/009-text_layouter_alignment.rb

@@ -4,6 +4,10 @@
 # inside a rectangular area, with various horizontal and vertical alignment
 # options.
 #
+# It is not advised to use the `TextLayouter` class directly but instead via the
+# [HexaPDF::Layout::TextBox] class and the general document layout
+# functionality.
+#
 # The text can be aligned horizontally by setting
 # [HexaPDF::Layout::Style#text_align] and vertically by
 # [HexaPDF::Layout::Style#text_valign]. In this example, a sample text is laid

data/examples/010-text_layouter_inline_boxes.rb

@@ -3,6 +3,10 @@
 # The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text
 # mixed with inline boxes.
 #
+# It is not advised to use the `TextLayouter` class directly but instead via the
+# [HexaPDF::Layout::TextBox] class and the general document layout
+# functionality.
+#
 # Inline boxes are used for showing graphics that follow the flow of the text.
 # This means that their horizontal and their general vertical position is
 # determined by the text layout functionality. However, inline boxes may be

data/examples/011-text_layouter_line_wrapping.rb

@@ -3,6 +3,10 @@
 # The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text,
 # automatically wrapping it appropriately.
 #
+# It is not advised to use the `TextLayouter` class directly but instead via the
+# [HexaPDF::Layout::TextBox] class and the general document layout
+# functionality.
+#
 # Text is broken only at certain characters:
 #
 # * The most important break points are **spaces**.

data/examples/012-text_layouter_styling.rb

@@ -1,10 +1,15 @@
 # # Text Layouter - Styling
 #
 # The text used as part of a [HexaPDF::Layout::TextLayouter] class can be styled
-# using [HexaPDF::Layout::Style]. To do this [HexaPDF::Layout::TextFragment]
-# objects have to be created with the needed styling and then added to a text
-# layout object. In addition the style objects can be used for customizing the
-# text layouts themselves.
+# using [HexaPDF::Layout::Style].
+#
+# It is not advised to use the `TextLayouter` class directly but instead via the
+# [HexaPDF::Layout::TextBox] class and the general document layout
+# functionality.
+#
+# To style [HexaPDF::Layout::TextFragment] objects, they have to be created with
+# the needed styling and then added to a text layout object. In addition, the
+# style objects can be used for customizing the text layouts themselves.
 #
 # This example shows how to do this and shows off the various styling option,
 # including using callbacks to further customize the appearance.

data/examples/013-text_layouter_shapes.rb

@@ -5,6 +5,11 @@
 # restriction: In the case of arbitrary shapes the vertical alignment has to be
 # "top".
 #
+# Note that using [HexaPDF::Layout::TextBox] is preferred over
+# `TextLayouter`. However, it is currently not possible to flow text into
+# arbitrary shapes with `TextBox`. So if this functionality is required, the
+# `TextLayouter` class needs to be used directly.
+#
 # Arbitrary shapes boil down to varying line widths and horizontal offsets from
 # left. Imagine a circle: If text is fit in a circle, the line widths start at
 # zero, getting larger and larger until the middle of the cirle. And then they

data/examples/015-boxes.rb

@@ -3,6 +3,9 @@
 # The [HexaPDF::Layout::Box] class is used as the basis for all document layout
 # features.
 #
+# While it is possible to use boxes in this manual way, the preferred way is to
+# use them through the [Composer class](composer.html).
+#
 # This example shows the basic properties that are available for all boxes, like
 # paddings, borders and and background color. It is also possible to use the
 # underlay and overlay callbacks with boxes.

data/examples/016-frame_automatic_box_placement.rb

@@ -2,6 +2,9 @@
 #
 # The [HexaPDF::Layout::Frame] class is used for placing rectangular boxes.
 #
+# While it is possible to use frames in this manual way, the preferred way is to
+# use them through the [Composer class](composer.html).
+#
 # This example shows how to create a frame and how different box styles can be
 # used to specify where a box should be placed. After each box is drawn, the
 # frame's shape is drawn and then a new page is started. This is done to easily

data/examples/017-frame_text_flow.rb

@@ -3,6 +3,9 @@
 # This example shows how [HexaPDF::Layout::Frame] and [HexaPDF::Layout::TextBox]
 # can be used to flow text around objects.
 #
+# While it is possible to use frames and boxes in this manual way, the preferred
+# way is to use them through the [Composer class](composer.html).
+#
 # Three boxes are placed repeatedly onto the frame until it is filled: two
 # floating boxes (one left, one right) and a text box. The text box is styled to
 # flow its content around the other two boxes.

data/examples/022-outline.rb

@@ -10,7 +10,11 @@
 require 'hexapdf'
 
 doc = HexaPDF::Document.new
-6.times { doc.pages.add }
+6.times do |i|
+  doc.pages.add.canvas.
+    font("Helvetica", size: 150).
+    text("Page #{i + 1}", at: [10, 660])
+end
 
 doc.outline.add_item("Main") do |main|
   main.add_item("Page 1", destination: 0)

data/examples/{028-frame_mask_mode.rb → 028-composer_mask_mode.rb}

@@ -1,15 +1,15 @@
-# # Frame - Mask Mode
+# # Composer - Mask Mode
 #
 # This example shows how to use the style property 'mask_mode' to achieve
 # certain effects like overlaying boxes on each other or using multiple
 # horizontal alignments on one line.
 #
 # Usage:
-# : `ruby frame_mask_mode.rb`
+# : `ruby composer_mask_mode.rb`
 #
 require 'hexapdf'
 
-HexaPDF::Composer.create('frame_mask_mode.pdf') do |composer|
+HexaPDF::Composer.create('composer_mask_mode.pdf') do |composer|
   box = composer.image(File.join(__dir__, 'machupicchu.jpg'),
                        border: {width: 1}, mask_mode: :none)
   composer.text('Text overlaid over image', height: box.height, text_align: :center,

data/lib/hexapdf/cli/batch.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as