Hello
'.b) # the first call downloads PD4ML (once) ``` **Ahead of time, with the `pd4ml` command.** This is better for servers, CI and container images, where a download in the middle of a request is unwelcome: ``` pd4ml install # with Bundler: bundle exec pd4ml install ``` Either way, the gem: - downloads PD4ML 4.2 ([which build](#which-build)); - downloads the Bouncy Castle jars PD4ML needs for encryption and signing, from Maven Central; - checks every file against its published SHA-1 checksum; - stores them in a per-user cache directory: `%LOCALAPPDATA%\pd4ml-ruby` on Windows, `~/.cache/pd4ml-ruby` elsewhere, or `PD4ML_HOME`. The gem then uses that build. Later runs do not check for newer PD4ML releases: run `pd4ml install` again to update. Updating the gem does not change the PD4ML build. **Which build.** The gem needs PD4ML 4.2 for its 4.2 API: `read_eml` and `read_mht`, `add_allowed_resource_location`, `add_metadata` (XMP), and the DOM API (`get_document`, `layout`), as well as for the v42 layout engine ([4.3](#4.3-layout-engines)). So a plain `pd4ml install` (and the first use) takes: - the most recent PD4ML release from 4.2.0 on; - while 4.2.0 is not released yet, the most recent 4.2.x **development snapshot** (today 4.2.0-SNAPSHOT), because no release has the 4.2 API yet. Once 4.2.0 is released, new installs take it by themselves, and `pd4ml install` updates an existing snapshot install to it. Snapshots of later versions (4.3, 5.0) are never taken by default; `--snapshots` asks for them. The rest of the API works with older builds too: to stay on the current 4.1 release, install it explicitly (`pd4ml install 4.1.2`); the 4.2 methods then raise `Pd4ml::JavaError` (`NoSuchMethodException`). | Option | | |---|---| | *(none)* | the most recent release from 4.2.0 on, else the most recent 4.2.x snapshot ([which build](#which-build)), or an update to it | | `--snapshots` | the most recent 4.x build, including development snapshots | | `pd4ml install 4.1.2` | an exact version (any release or snapshot the repository lists) | | `--jakarta` | for Jakarta EE / Servlet 6 environments: a `-jakarta` variant if one fits; PD4ML 4.2 has none (its builds contain the Jakarta tag library), so the same 4.2 build (an older `-jakarta` build by version, e.g. `pd4ml install 4.0.20fx3-jakarta`) | | `--home DIR` | install into `DIR` (default: `PD4ML_HOME`, else the cache directory) | | `--force` | download again | | `--no-bouncycastle` | skip the Bouncy Castle jars (encryption and signing will not work) | | `pd4ml list` | list the available versions | The same is available from Ruby, which suits an application's boot (a Rails initializer): ```ruby require 'pd4ml' Pd4ml.install # downloads only when that build is not there yet puts Pd4ml.installed_version, Pd4ml.installed_classpath ``` To check the installation, run `pd4ml version`. **Turning the automatic download off.** Set `PD4ML_AUTO_INSTALL=0`, for example on servers that must not reach the internet, or where the build is provisioned separately. The gem then raises `Pd4ml::BridgeError` until a build is installed or configured. The automatic download never runs when a build is configured through [2.3](#2.3-other-ways-to-provide-pd4ml). > **Services and containers**: the account the application runs as must see the installed > build. Install it as that account, or install into a shared directory and set `PD4ML_HOME` > for the application too. In a Dockerfile: > > ``` > RUN bundle install && PD4ML_HOME=/opt/pd4ml bundle exec pd4ml install > ENV PD4ML_HOME=/opt/pd4ml PD4ML_AUTO_INSTALL=0 > ``` ### 2.3 Other ways to provide PD4ML The gem looks for PD4ML in this order: 1. `Pd4ml.configure(classpath: [...])`, called before the first conversion; 2. the `PD4ML_CLASSPATH` environment variable: jars and class directories separated by `;` (Windows) or `:` (elsewhere), with `dir/*` for all jars of a directory; 3. the `PD4ML_CLASSPATH_FILE` environment variable: a file with one entry per line; 4. the build `pd4ml install` (or the first use) downloaded. Typical reasons to use them: - **Offline or air-gapped servers**: run `pd4ml install --home ./pd4ml-libs` on a machine with network access, copy the directory, and set `PD4ML_HOME` and `PD4ML_AUTO_INSTALL=0` on the target. - **A licensed or specific jar**: `PD4ML_CLASSPATH=/opt/pd4ml/pd4ml.jar:/opt/pd4ml/lib/*`. - **A PD4ML development build** (for the v42 layout engine, see [4.3](#4.3-layout-engines)): a classpath file listing the build's classes and its Maven dependencies, in `PD4ML_CLASSPATH_FILE`. ## 3. Quick start ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.set_page_size(Pd4ml::PageSize::A4) pd.read_html_string('Hello, PDF
Generated with PD4ML.
') pd.write_pdf('hello.pdf') ``` Or in one call: ```ruby require 'pd4ml' pdf = Pd4ml.html_to_pdf('Invoice 42
'.b) puts pdf[0, 5] # %PDF- ``` ## 4. How it works ### 4.1 The two-phase model A document is **read once and written any number of times**: - `read_html` parses the document and lays it out; - each `write_pdf`, `write_docx`, `write_rtf` or `render_as_images` call then produces one output from that same layout. Settings (page size, headers, fonts...) go before `read_html`. See [the two-phase model](https://pd4ml.com/docs/#6.1-the-two-phase-model). ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.read_html_string('Quarterly report
') pd.write_pdf('report.pdf') pd.write_docx('report.docx') thumbnails = pd.render_png # PNG images, one binary String per page ``` ### 4.2 The bridge and threads - **One bridge per process.** The first use of PD4ML starts a Java bridge process. It serves every conversion of the Ruby process, from any thread, and ends with it. Starting Java takes a fraction of a second; after that, converting an ordinary document takes milliseconds. - **Threads.** The bridge is thread-safe: use one `Pd4ml::PD4ML` per document (each thread its own) and convert from as many threads as you like (Puma, Sidekiq). The conversions themselves run one at a time, so for parallel throughput use several processes, or point them all at one bridge server (next item). Each Puma or Unicorn worker process starts its own bridge on first use; there is nothing to set up before forking. - **Shared bridge server.** Several processes, or short-lived ones (rake tasks, CLI tools), can use one long-running bridge instead of each starting Java: ``` pd4ml serve --port 8723 # keep it running (systemd, a sidecar container, foreman) ``` Then set `PD4ML_BRIDGE=tcp://127.0.0.1:8723`, or call `Pd4ml.configure(server: 'tcp://127.0.0.1:8723')`. The server listens on the loopback interface only, and each connection has its own objects. - **JVM options** (memory, system properties): set `PD4ML_JVM_OPTIONS="-Xmx2g"`, or call `Pd4ml.configure(jvm_options: ['-Xmx2g'])` before the first use. Java runs headless. - **The bridge's console output** is discarded unless `PD4ML_BRIDGE_LOG=path` (or `Pd4ml.configure(log_file: ...)`) keeps it. `Pd4ml.shutdown` stops the bridge; the next use starts it again. ### 4.3 Layout engines PD4ML 4.2 introduces a second HTML layout engine, **v42**, written to match current browsers closely (flexbox, grid, modern CSS). `Pd4ml::PD4ML.new` uses it by default: ```ruby require 'pd4ml' if Pd4ml.layout_engines? pd = Pd4ml::PD4ML.new # v42 legacy = Pd4ml::PD4ML.new(engine: 'v40') # the previous engine puts pd.engine, legacy.engine end ``` Builds before 4.2 have one engine only; this includes the current public release, 4.1.x. With such a build: - the gem uses that build's engine and warns once; - `Pd4ml.layout_engines?` returns false; - asking for an engine explicitly raises. ### 4.4 Ruby and Java values - **Method names**: Java methods can be called by their Java names (`setPageSize`, `readHTML`) or Ruby-style: `set_page_size`, `use_ttf` (for `useTTF`), `demo_mode?` (for `isDemoMode`). Ruby-style names are matched to the real Java names, acronyms included. - **Classes**: the PD4ML classes are Ruby classes in the `Pd4ml` module. Constants are Ruby constants (`Pd4ml::PageSize::A4`, `Pd4ml::Constants::AllowPrint`); lower-case static fields and static methods are class methods (`Pd4ml::LayoutEngine.v42`, `Pd4ml::PdfSpec.get_instance('pdf/a-2b')`); constructors use `new`. Any other Java class: `Pd4ml::Java.type('java.util.Locale')`. - **Objects**: a Java object comes back as a `Pd4ml::JavaObject` with all its Java methods. Public fields: `obj[:width]` and `obj[:width] = value`. `to_s` is Java's `toString()`, `enum_name` an enum constant's name, `java_class` the class name. - **Collections**: a Java `List` or `Map` generally comes back as a `JavaObject` (`size`, `get(i)`). The DOM API ([5.18](#5.18-modifying-the-document-before-conversion-dom-api)) is the exception: its lists and sets come back as Ruby Arrays and its maps as Hashes. `call_java` returns them as Java objects. - **Values**: Strings, Integers, Floats (`100.0` goes to Java as a float), `true`/`false`, `nil`, Symbols (as strings: `engine: :v40`), Arrays, Hashes (as Java `Map`s). - **Binary data**: a binary String (`File.binread`, `"...".b`, encoding ASCII-8BIT) goes to Java as `byte[]`; an IO is read. Java's `byte[]` comes back as a binary String. Text Strings (UTF-8) go to Java as text. - Java objects are released when Ruby garbage-collects them. ### 4.5 Exceptions Java exceptions are raised as `Pd4ml::JavaError`, which knows the Java class and its superclasses: ```ruby require 'pd4ml' begin pd = Pd4ml::PD4ML.new pd.read_html('file:///no/such/document.html') pd.write_pdf rescue Pd4ml::JavaError => e raise unless e.instance_of_java?('java.io.IOException') puts "cannot read the document: #{e.java_message}" end ``` `e.java_class`, `e.causes` and `e.java_trace` hold the details. Other errors: | Error | Raised when | |---|---| | `Pd4ml::BridgeError` | the bridge itself fails: no Java, no PD4ML build, or the process ended | | `Pd4ml::CallbackError` | a Ruby block raised, such as a progress listener; the original error is `cause` | | `Pd4ml::InstallError` | downloading PD4ML fails | --- ## 5. Use cases The snippets below are complete and runnable. Files they read (`report.html`...) are assumed to exist in the working directory. ### 5.1 HTML string to PDF This is the common case for web applications: render HTML with your template engine (ERB, Haml, Slim, a Rails view) and convert it in memory. ```ruby require 'pd4ml' html = 'Order 1001
Thank you for your order.
' pd = Pd4ml::PD4ML.new pd.read_html_string(html) pdf = pd.write_pdf # the PDF as a binary String ``` `write_pdf`, `write_docx` and `write_rtf` return the document as a binary String when given no target. Given a path (a String or Pathname) they write the file, given an IO (a `File`, a `StringIO`, a Rack body) they write into it. ### 5.2 Files and URLs ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.read_html('report.html') # also: 'https://example.com/report', a Pathname, a URI pd.write_pdf('report.pdf') ``` **Relative links** (`
`, ``) resolve against the
document's own location when it is read from a path or URL. When the HTML comes from a string,
binary String or IO, pass the base location. Otherwise images and stylesheets go missing without
an error (see [reading the source](https://pd4ml.com/docs/#6.2-reading-the-source)):
```ruby
require 'pd4ml'
html = 'Styled
' pd = Pd4ml::PD4ML.new pd.read_html_string(html, '.') # a directory, file path or URL pd.write_pdf('styled.pdf') ``` A text String that does not start with `<` is taken as a path or URL; content always goes in as a binary String (`File.binread`), an IO, or through `read_html_string`. For a document in a known encoding other than UTF-8, call `pd.read_html(File.binread(path), base, 'windows-1251')`. ### 5.3 Page size, orientation, margins and scaling ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.set_page_size(Pd4ml::PageSize::LETTER.rotate) # landscape pd.set_page_margins(Pd4ml::PageMargins.new(15, 20, 15, 20, Pd4ml::Units::MM)) # left, top, right, bottom pd.set_html_width(1000) # the virtual browser width the page is laid out in pd.read_html_string("| wide content |
$[title]
", 30, '1+')
pd.set_page_footer(
"" \
'Invoice $[invoice] — $[customer] — page $[page] of $[total]
',
24, '1+'
)
pd.read_html_string("Invoice
#{'Line item
' * 80}") pd.write_pdf('invoice.pdf') ``` The second argument is the area height in pixels. The third is the page scope: `'1'` (first page), `'2+'` (all but the first), `'odd'`, `'even'`, `'3-7'`... You can also write headers and footers inline in the HTML with PD4ML's extension tags. See [headers, footers, watermarks and backgrounds](https://pd4ml.com/docs/#8.-headers-footers-watermarks-and-backgrounds) and the [usage examples](https://pd4ml.com/docs/usage-examples.html#set-page-header-and-footer). ### 5.5 Watermarks and page backgrounds ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.set_watermark("DRAFT", 120.0, 350.0, # left, top (px) 0.15, # opacity 45.0, # rotation, degrees 1.0, # scale true, true, # visible on screen, in print '1+') # pages pd.set_page_background("", '1+') pd.read_html_string('Proposal
') pd.write_pdf('draft.pdf') ``` ### 5.6 Fonts PD4ML's built-in fonts cover Unicode broadly. For a specific typeface (a corporate font, CJK coverage), give it a font directory: ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.use_ttf('/opt/fonts', true) # a directory of TTF/OTF fonts (indexed: see below) pd.embed_ttfs(true, false) # embed only the glyphs used pd.apply_kerning(true) pd.enable_ligatures(true) ``` Index a font directory once, ahead of time. PD4ML then reads the index (`pd4fonts.properties`) instead of scanning all the fonts on every conversion ([font indexing](https://pd4ml.com/docs/#4.3-font-indexing)): ``` java -jar..
pd.enable_hyperlinks(true) # become clickable links (the default)
pd.read_html_string("Introduction
...
Details
")
pd.write_pdf('bookmarked.pdf')
```
PD4ML's `` tag generates a table of contents with page numbers from the headings; see
the [usage examples](https://pd4ml.com/docs/usage-examples.html#add-toc). For explicit page
breaks, use CSS `page-break-before` / `break-before`, or ``.
### 5.8 PDF/A and PDF/UA
```ruby
require 'pd4ml'
pd = Pd4ml::PD4ML.new
pd.read_html_string("Annual report Annual report
")
pd.write_pdf('archive.pdf', spec: Pd4ml::PdfSpec::PDFA_3B) # archival
pd.write_pdf('accessible.pdf', spec: Pd4ml::PdfSpec::PDFUA_1) # accessible
pd.write_pdf('both.pdf', spec: Pd4ml::PdfSpec::PDF_1_7.combine(Pd4ml::PdfSpec::PDFA_2A))
pd.write_pdf('keyword.pdf', spec: 'pdf/a-2b') # by keyword
status = pd.get_last_render_info(Pd4ml::Constants::PD4ML_PDFA_STATUS) # after writing
```
`Pd4ml::PdfSpec.list_keywords` lists the keywords; an unknown one raises `ArgumentError`
(`PdfSpec.get_instance` alone would fall back to PDF 1.7 without an error).
- PDF/A embeds all fonts.
- PDF/UA needs well-structured HTML: real headings, `alt` texts, `lang`, table headers.
Combine it with `pd.set_error_policy(Pd4ml::ErrorPolicy::PEDANTIC)` to be told when the source
does not satisfy the standard.
Details: [PDF/A, PDF/UA and e-invoicing](https://pd4ml.com/docs/#11.2-pdfa-pdfua-and-e-invoicing-formats).
### 5.9 ZUGFeRD / Factur-X e-invoices
`PdfSpec::ZUGFeRD` and `PdfSpec::FacturX` select the PDF/A-3 container the standards require.
The HTML attaches the invoice XML with PD4ML's attachment tag. The
[ZUGFeRD and Factur-X page](https://pd4ml.com/docs/features/zugferd-and-factur-x-pdf-invoices.html)
has the complete recipe, including the required attachment names.
```ruby
require 'pd4ml'
pd = Pd4ml::PD4ML.new
pd.read_html('invoice.html') # contains the of factur-x.xml
pd.write_pdf('invoice.pdf', spec: Pd4ml::PdfSpec::FacturX)
```
### 5.10 Passwords and permissions
```ruby
require 'pd4ml'
c = Pd4ml::Constants
pd = Pd4ml::PD4ML.new
pd.set_permissions('owner-secret', c::AllowPrint | c::AllowCopy, c::AES_256BIT)
pd.read_html_string('Confidential
')
pd.write_pdf('protected.pdf')
```
Combine the `Allow*` flags with `|`, or start from `Constants::DefaultPermissions` and remove
flags with `& ~`. Encryption needs the Bouncy Castle jars, which the installation downloads. See
[permissions and encryption](https://pd4ml.com/docs/#11.1-permissions-and-encryption).
### 5.11 Word (DOCX, RTF) and images
```ruby
require 'pd4ml'
pd = Pd4ml::PD4ML.new
pd.read_html_string('Letter
Dear customer, ...
')
pd.write_docx('letter.docx')
pd.write_rtf('letter.rtf')
pages = pd.render_png # a PNG per page
tiffs = pd.render_as_images(Pd4ml::Constants::TIFF) # one TIFF per page
pd.render_as_images('pages', 'page', Pd4ml::Constants::PNG24) # page files in a directory
```
The image formats are `PNG8`, `PNG24`, `TIFF` and `TIFF_COMPRESSED` (constants in `Constants`).
The TIFF formats need Java 9 or later.
The v42 engine does not support the multi-page TIFF formats yet; use the v40 engine for them.
With the v42 engine, DOCX/RTF output is *editable*: positioned content becomes text boxes
and form fields, not pictures.
### 5.12 Interactive forms and multi-column layout
```ruby
require 'pd4ml'
pd = Pd4ml::PD4ML.new
pd.generate_forms(true, nil) # /
Introduction
...
Details
") pd.write_pdf('bookmarked.pdf') ``` PD4ML's `Annual report
") pd.write_pdf('archive.pdf', spec: Pd4ml::PdfSpec::PDFA_3B) # archival pd.write_pdf('accessible.pdf', spec: Pd4ml::PdfSpec::PDFUA_1) # accessible pd.write_pdf('both.pdf', spec: Pd4ml::PdfSpec::PDF_1_7.combine(Pd4ml::PdfSpec::PDFA_2A)) pd.write_pdf('keyword.pdf', spec: 'pdf/a-2b') # by keyword status = pd.get_last_render_info(Pd4ml::Constants::PD4ML_PDFA_STATUS) # after writing ``` `Pd4ml::PdfSpec.list_keywords` lists the keywords; an unknown one raises `ArgumentError` (`PdfSpec.get_instance` alone would fall back to PDF 1.7 without an error). - PDF/A embeds all fonts. - PDF/UA needs well-structured HTML: real headings, `alt` texts, `lang`, table headers. Combine it with `pd.set_error_policy(Pd4ml::ErrorPolicy::PEDANTIC)` to be told when the source does not satisfy the standard. Details: [PDF/A, PDF/UA and e-invoicing](https://pd4ml.com/docs/#11.2-pdfa-pdfua-and-e-invoicing-formats). ### 5.9 ZUGFeRD / Factur-X e-invoices `PdfSpec::ZUGFeRD` and `PdfSpec::FacturX` select the PDF/A-3 container the standards require. The HTML attaches the invoice XML with PD4ML's attachment tag. The [ZUGFeRD and Factur-X page](https://pd4ml.com/docs/features/zugferd-and-factur-x-pdf-invoices.html) has the complete recipe, including the required attachment names. ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.read_html('invoice.html') # contains theConfidential
') pd.write_pdf('protected.pdf') ``` Combine the `Allow*` flags with `|`, or start from `Constants::DefaultPermissions` and remove flags with `& ~`. Encryption needs the Bouncy Castle jars, which the installation downloads. See [permissions and encryption](https://pd4ml.com/docs/#11.1-permissions-and-encryption). ### 5.11 Word (DOCX, RTF) and images ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.read_html_string('Letter
Dear customer, ...
') pd.write_docx('letter.docx') pd.write_rtf('letter.rtf') pages = pd.render_png # a PNG per page tiffs = pd.render_as_images(Pd4ml::Constants::TIFF) # one TIFF per page pd.render_as_images('pages', 'page', Pd4ml::Constants::PNG24) # page files in a directory ``` The image formats are `PNG8`, `PNG24`, `TIFF` and `TIFF_COMPRESSED` (constants in `Constants`). The TIFF formats need Java 9 or later. The v42 engine does not support the multi-page TIFF formats yet; use the v40 engine for them. With the v42 engine, DOCX/RTF output is *editable*: positioned content becomes text boxes and form fields, not pictures. ### 5.12 Interactive forms and multi-column layout ```ruby require 'pd4ml' pd = Pd4ml::PD4ML.new pd.generate_forms(true, nil) # /