Changelog

Copy Markdown View Source

All notable changes to this project are documented here.

The format follows Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Fixed

  • Embedded fonts could not be laid out. Font embedding and the typography engine — the library's two headline features — did not compose. Every layout entry point measured through Font.text_width/3, which resolves only the standard 14 fonts and AFM files on disk. An embedded TrueType font has no AFM; its metrics are parsed at registration and live on the document, so a pure function could never see them. text_paragraph/6, Layout.Box.flow_text/7, Layout.Table.render/6 with :auto columns and text_link/6 all raised unknown font for any embedded font. The metrics were parsed, correct, and sitting unused: the drawing path had its own private copy of the measurement code all along.

Added

  • Tincture.export/2 refuses a false PDF/A claim. set_pdf_a/2 writes a conformance assertion into the file, so a document that declares a level and breaks it lies about itself — and nothing discovers that until someone relies on it. Export now raises, naming every violation and the clause it breaks. Tincture.pdf_a_violations/1 returns the list without exporting, and export(pdf, enforce: false) exports anyway, logging what it let through.

    Every rule was confirmed against veraPDF rather than read off a specification. Refused: unembedded fonts, encryption, text and choice fields, signature fields, push buttons, and level A without tagging. Allowed: checkboxes, radio buttons and links, all verified compliant.

    This is not a conformance check and does not claim to be — Tincture sees the document it built, not the file a validator sees.

  • Digital signatures. Tincture.sign/3 produces a detached PKCS#7 signature covering the whole file, verified against OpenSSL rather than only against itself. Tincture.PDF.CMS builds the CMS SignedData structure in DER, since OTP ships no encoder for it; :crypto and :public_key are OTP applications, so there are still no third-party dependencies.

    Signing is the one thing in Tincture that is not a pure transformation: a signature covers the finished bytes, so export/2 reserves space, measures the real offsets, signs, and patches the result back without moving anything.

    No timestamp authority yet, so a signature proves the document has not changed — not when it was signed.

  • PDF/A, verified. Tincture.set_pdf_a/2 produces archival output: examples/output/archival.pdf passes veraPDF 1.30.2 at PDF/A-2b, 2u and 2a, and PDF/UA-1 simultaneously. Adds an sRGB output intent, XMP carrying the conformance claim, and a file identifier.

  • Tincture.PDF.ICC — a built-in sRGB ICC profile, generated from the published constants rather than read from the system or shipped from elsewhere, so archival output is reproducible on any machine. Uses the real sRGB tone curve including its linear segment, not the gamma 2.2 shortcut.

  • A file identifier on every document. /ID was emitted only for encrypted documents; PDF/A requires one always. Derived from the content rather than the clock, so building the same document twice produces identical bytes and an archived file can be checked against a rebuild.

  • Verified PDF/UA-1 conformance. examples/output/accessible.pdf passes veraPDF 1.30.2 against the PDF/UA-1 profile: 106 of 106 rules, 1701 of 1701 checks. Validating it found three real defects, all fixed below.

  • XMP metadata. The catalog now carries a /Metadata stream — Dublin Core title, creator and description, plus pdfuaid:part for a tagged document. The info dictionary alone satisfies neither PDF/UA nor PDF/A.

  • /ViewerPreferences << /DisplayDocTitle true >> on tagged documents, so a reader shows the document's title rather than its file name.

  • Tagged PDF, for accessibility. Tincture.tag/4 and Tincture.set_language/2 produce logical structure: a /StructTreeRoot, marked content bracketing the operators that draw each element, a parent tree linking the two, /MarkInfo, /Lang, alternative text, and /Scope on table header cells. An untagged PDF is a picture of a document — nothing records which glyphs are a heading or what order to read them in — so this is the layer assistive technology actually reads.

    This produces the structure; it does not certify PDF/UA. Conformance is a validation exercise against a checker such as veraPDF or PAC, which enforces further rules a library cannot check on your behalf.

  • Tincture.Layout.Table.render/6 tags itself. Inside a tagged document it emits /Table, /THead, /TBody, /TR and a /TH or /TD per cell, gives header cells a /Scope, and marks its own borders as artifacts. It could not be tagged by hand, because it draws the whole grid in one call. Controlled by :tag, which defaults to :auto — tagging only when the caller is already tagging, since a structure tree containing nothing but a table reads worse than none at all.

  • Tincture.artifact/2, marking decoration — rules, borders, page furniture — as content to skip. In a tagged document every operator must be either tagged or an artifact; anything that is neither is announced as stray noise.

  • Telemetry. Three spans — [:tincture, :export], [:tincture, :page] and [:tincture, :font, :embed] — covering document duration and size, per-page timing, and per-font embedding with source and embedded sizes so subsetting is measurable. :telemetry is an optional dependency: without it every event call compiles away, so Tincture still has no required runtime dependencies. See Tincture.Telemetry.

  • examples/compliant.exs, a PDF/UA template with every requirement annotated where it is satisfied — including list structure — validated at 106 of 106 rules and 2605 of 2605 checks.

  • examples/, with the produced PDFs committed. An invoice, an interactive form exercising every field type, and a telemetry report. mix examples runs them all. Font paths are resolved per platform, so they run outside macOS.

  • The remaining form field types. Tincture.radio_group/4, Tincture.push_button/7 and Tincture.signature_field/7 complete the field set. A radio group is the first field that is not a single object: the specification models it as a parent field holding the value with a kid widget per button, so the serialiser now emits multi-object fields.

  • Generated appearance streams for button-like fields. Radio buttons, checkboxes and push buttons now carry real /AP streams. Previously they relied entirely on /NeedAppearances, which only interactive viewers honour — so a checkbox was invisible when printed, thumbnailed or rasterised server-side, and a push button, whose face is nothing but appearance, showed nothing at all. A radio button additionally cannot work without one, since its export value is the name of its "on" appearance state.

  • Tincture.Font.Context — a measurement context pairing a document's embedded metrics with the static ones, so anything holding a document can measure any font that document can draw. The document-aware entry points build one themselves, so laying out an embedded font now needs nothing extra:

    Tincture.text_paragraph(pdf, 50, 700,
  RichText.from_plain(terms, font: "Body", size: 10), 400, align: :justified)

  • RichText.remeasure/2 and a :context option on RichText.from_plain/2 and from_runs/2, for laying text out through Tincture.Typography directly.

  • RichText.unmeasured_fonts/1, reporting which fonts are still estimates.

Changed

  • Link annotations omitted /F. Every annotation needs one, and a link without it is a link that vanishes when the page is printed. Failed ISO 19005-2 clause 6.3.2, which made external links impossible in an archival document. Now /F 4 (Print), and links are PDF/A-valid.
  • /NeedAppearances was set whenever a document had any form field, even ones that carry their own appearance streams. Only text and choice fields need it — a checkbox or radio button draws every state itself. It is now emitted only when something actually requires it, which makes checkbox and radio-button forms valid PDF/A where they previously were not.
  • Stream /Length was overstated by one byte on content streams, form XObjects and CMaps. The EOL before endstream is a delimiter rather than stream data, so a stream whose own last byte is a newline needs one of each — otherwise its final byte is consumed as the delimiter. Every content stream ends in a newline, so every one was affected. Failed ISO 19005-2 clause 6.1.7.1; found by validation.
  • /CIDSet is no longer emitted. It must identify exactly the CIDs present in the embedded program, and subsetting falls back to the whole font on several paths while the name keeps its subset tag — so an accurate one cannot be produced at that point. veraPDF rejects an inaccurate CIDSet (ISO 14289-1 clause 7.21.4.2) where an absent one is conformant; it is optional in PDF 1.7 and deprecated in PDF 2.0. Required only for PDF/A-1, which is not yet a target.
  • Table /Scope moved into an attribute dictionary. It was emitted as a direct key on the structure element, where a reader ignores it — leaving the table's structure undeterminable and failing ISO 14289-1 clause 7.5. It now reads /A << /O /Table /Scope /Column >>. Found by validation.
  • Form fields now reject a non-standard font. A field's value is rendered by the viewer from its /DA string, which resolves against the AcroForm resource dictionary — and that can only carry the standard 14. Naming an embedded font there emitted a font dictionary no viewer could resolve, so the value silently did not render. Static text is unaffected.
  • Rich text no longer raises on an unknown font at construction. It cannot: an embedded font is unresolvable until a document is known, and at that point indistinguishable from a typo. Tokens whose font could not be resolved carry an estimated width and measured?: false, and Typography.layout_paragraph/3 refuses to lay those out — so a mistyped font name still fails loudly, with a better message, at the point where the answer is actually knowable rather than silently producing a plausible-looking but wrong paragraph.

0.1.0 — 2026-07-26

First release under the Tincture name.

Tincture is a fork of ex_guten by Hugh Watkins (MIT), which is itself an Elixir port of Joe Armstrong's Erlang erlguten. Most of the engine — the TrueType/OpenType parser, the Knuth-Plass line breaker, the TeX hyphenation port, the PDF object serialiser — is his work, carried forward here. See NOTICE for the full attribution chain.

0.1.0 rather than a higher number is deliberate. The engine is mature, but the public API under this name is new and may still move before 1.0.

Added

  • Hyperlinks and annotations — external URLs and internal page targets, via Tincture.link/6 and Tincture.text_link/5. Previously the library emitted no /Annot objects at all.
  • Interactive forms (AcroForm) — text fields, checkboxes and choice fields, via Tincture.text_field/7, Tincture.checkbox/6 and Tincture.choice_field/7. Supports field flags (multiline, password, read-only, required, dropdown, editable, sort), maximum length, tooltips and initial values.
  • AES-256 encryption — Tincture.encrypt/2, standard security handler revision 6 (/V 5 /R 6, PDF 2.0). User and owner passwords, permission flags, optional metadata encryption. Note that an owner password alone is advisory: the document is then encrypted under the empty user password and any reader can open it. Only a user password is real protection.
  • Tincture.Font.UnicodeRanges — the complete OpenType OS/2 ulUnicodeRange bit table.
  • mix check, which runs every gate CI runs, in the same order.

Changed

  • Font subsetting is now on by default (subset: :used_text). Only the glyphs a document draws are embedded, which typically cuts an embedded font by 70–90%. Previously it defaulted to :none and was undocumented. Pass subset: :none for the old behaviour.
  • Decomposed the two modules that held most of the library. Font.TTF went from 4,530 lines with a single public function to a coordinator delegating to TTF.Cmap, TTF.Glyf, TTF.Name, OpenType.GPOS, OpenType.GSUB, OpenType.Common, Font.CFF and Font.Binary. PDF.Serialize went from 3,491 lines to 516, with font embedding extracted to PDF.FontEmbed and PDF syntax primitives to PDF.Object.
  • Documentation. The layout and typography API — 15 public functions across five modules — was @moduledoc false and invisible in generated docs.

Fixed

  • Subsetting silently fell back to embedding the whole font for any text containing a space. A glyph with no outline is encoded as zero bytes, which the subsetter treated as malformed, aborting the subset. Since almost every string contains a space, subsetting was effectively never applied.
  • A malformed name table crashed the parse. :unicode.characters_to_binary/3 signals bad input by returning a tuple rather than raising, so a rescue never fired and the tuple reached a function expecting a binary. A truncated UTF-16BE font name — what a bad subsetter produces — raised FunctionClauseError instead of being skipped.
  • The OS/2 Unicode range table was 91% missing. Only 11 of ~123 ulUnicodeRange bits were mapped, all below 32, so div(bit, 32) was always 0 and the font's ulUnicodeRange2/3/4 words were parsed and then ignored. Any CJK, Hangul, punctuation, currency or math codepoint was reported as unsupported.
  • Typography.Hyphen called File.stream!/3 with the argument order deprecated in Elixir 1.16 — on the :en_gb path, the default locale.
  • The Tincture.rich_text/0 type was declared as a plain map while every caller requires a %RichText{} struct.
  • A divide-by-zero in Benchmark.Document when :timer.tc reports 0µs on a fast machine.

Infrastructure

  • CI now passes. Upstream's 13 workflow runs all failed at mix format --check-formatted, so its test suite had never executed in CI. Tincture runs format, warnings-as-errors, Credo, Dialyzer and coverage, with the test suite on Elixir 1.16, 1.17, 1.18 and 1.19.
  • 1,011 tests, up from 444 (one of which failed).
  • Coverage measured and gated at 80%; currently 88.3%.
  • Credo at --strict with zero issues, down from 174.
  • Dialyzer passing, with a documented ignore file for defensive clauses that keep functions total.