...` switches it from HTML conversion into edit mode:
```
# Keep only pages 2-3 and everything from page 5 onward
java -jar pd4ml.jar -tools file:/docs/source.pdf -pagerange 2-3,5+ -out subset.pdf
# Append another PDF after the source document
java -jar pd4ml.jar -tools file:/docs/source.pdf -merge file:/docs/appendix.pdf after -out combined.pdf
# Read back permission flags, author, title and page count
java -jar pd4ml.jar -tools file:/docs/source.pdf -printpermissions -printauthor -printtitle -printpagenum
```
For anything beyond these simple cases -- selecting page ranges from *two* independent source documents with accessibility-tag reconciliation, reachability-based cleanup and duplicate-content dedup, or arbitrary COS-level structural edits -- reach for the dedicated `pd4mergecli`, `pd4optimizecli` and `pd4coscli` tools instead (§15).
### 4.3 Font indexing
```
java -Xmx512m -jar pd4ml.jar -configure.fonts /path/to/fonts [pd4fonts.properties]
```
Scans a directory of TrueType/OpenType font files and writes (or updates) a font-mapping properties file PD4ML uses to resolve CSS `font-family` names to actual font files at conversion time -- run once per font directory, ahead of time, rather than paying the directory scan cost on every conversion.
## 5. GUI application: `PD4Browser`
A lightweight preview tool bundled in the same jar -- useful for iterating on CSS/layout without a full round trip through your application:
```
java -jar pd4ml.jar -gui
```
`[...]` opens an HTML or SVG file; `[GO]` re-renders it; `[PDF]`/`[RTF]`/ `[DOCX]` convert the current document to that format. Its own behavior (page format, margins, default fonts, proxy, bookmark generation, ...) is controlled by a `pd4browser.properties` file in the working directory -- the same settings a Java integration would set via the API in §6-9, exposed as plain properties for quick experimentation.
## 6. The Java API
### 6.1 The two-phase model
Every conversion is **read** once, then **written** one or more times: a `readHTML(...)` call parses and lays out the source; any number of subsequent `write*(...)`/`renderAsImages()` calls then serialize that same parsed document to different formats or destinations, without re-parsing.
```java
import com.pd4ml.PD4ML;
import java.io.*;
PD4ML pd4ml = new PD4ML();
String html = "Hello, World!
";
pd4ml.readHTML(new ByteArrayInputStream(html.getBytes("UTF-8")), null, "UTF-8");
try (FileOutputStream out = new FileOutputStream("hello.pdf")) {
pd4ml.writePDF(out);
}
```
### 6.2 Reading the source
```java
pd4ml.readHTML(inputStream); // encoding auto-detected
pd4ml.readHTML(inputStream, baseUrl); // relative links/images resolve against baseUrl
pd4ml.readHTML(inputStream, baseUrl, "windows-1251"); // explicit source encoding
pd4ml.readHTML(new URL("https://example.com/report")); // fetch directly
```
A relative-URL `baseUrl` matters whenever the source HTML references external images, stylesheets, or fonts by relative path -- omitting it (or getting it wrong) is the most common cause of a converted document missing images that render fine in a browser.
### 6.3 Writing the output
```java
pd4ml.writePDF(pdfOutputStream);
pd4ml.writeRTF(rtfOutputStream, false); // false: keep raster images as PNG/JPEG rather than converting to WMF
pd4ml.writeDOCX(docxOutputStream);
BufferedImage[] pages = pd4ml.renderAsImages(); // one image per page, in memory
byte[][] pngBytes = pd4ml.renderAsImages("png"); // ... or already PNG-encoded
File dir = pd4ml.renderAsImages(outDir, "page", "png"); // ... or written straight to disk
```
Because reading happens once, converting the same source to PDF *and* a page-image thumbnail set costs one HTML parse, not two:
```java
pd4ml.readHTML(new URL("https://example.com/report"));
pd4ml.writePDF(new FileOutputStream("report.pdf"));
BufferedImage[] thumbnails = pd4ml.renderAsImages();
```
## 7. Page layout: size, margins, and scaling
Three settings govern how source content maps onto printed pages:
| Setting | Meaning | Default |
| ------------- | ---------------------------------------------------------- | --------------- |
| `pageSize` | Target paper format | A4, portrait |
| `pageMargins` | Blank border reserved on every page | 10 mm all sides |
| `htmlWidth` | Virtual viewport width (px) the source is laid out against | 727 px |
```java
import com.pd4ml.PageSize;
import com.pd4ml.PageMargins;
import com.pd4ml.Dimensions.Units;
pd4ml.setPageSize(PageSize.LETTER);
pd4ml.setPageMargins(new PageMargins(15, 20, 15, 20, Units.MM));
pd4ml.setHtmlWidth(1000);
```
Content is scaled uniformly to fit the printable area:
```
scale = (pageWidth - marginLeft - marginRight) / htmlWidth
```
A narrower `htmlWidth` means a larger scale factor -- text and images appear bigger on the page, at the cost of how much content fits horizontally before wrapping. `pd4ml.adjustHtmlWidth(true)` (or the CLI's `-adjustwidth`) instead measures the document's own natural width and uses that, useful for source HTML that isn't already responsive-width-aware.
`setPageSize(...)`/`setPageMargins(...)` also accept an optional **scope** string (`"1"`, `"2+"`, `"3-7,odd"`, ...) to vary page size or margins across the document -- the same scope grammar used by headers/footers (§8) and by `Pd4Cmd -pagerange`.
`fitPageVertically(Constants.CENTER_ALIGN)` downscales the entire layout to guarantee it fits one single page, rather than paginating -- handy for "print this as a single-page summary" use cases; it's mutually exclusive with multi-column mode (§10.1).
## 8. Headers, footers, watermarks, and backgrounds
Repeating page decorations are themselves HTML/CSS fragments, not a separate mini-format to learn:
```java
pd4ml.setPageHeader("$[title]", 30, "1"); // first page only
pd4ml.setPageHeader("$[title] — $[page]/$[total]", 30, "2+"); // every page after
pd4ml.setPageFooter(
"Page $[page] of $[total]
",
24, "1+");
```
Three placeholders are always available: `$[page]` (current page number), `$[total]` (total page count), and `$[title]` (document title). Arbitrary additional placeholders come from `setDynamicData(...)`:
```java
Map data = new HashMap<>();
data.put("customer", "Acme Corp.");
data.put("invoiceNo", "INV-2026-0031");
pd4ml.setDynamicData(data);
pd4ml.setPageFooter("Invoice $[invoiceNo] — $[customer]
", 24, "1+");
```
A watermark, and a full-bleed page background rendered underneath every page's content, follow the same HTML-fragment-plus-scope model -- the watermark content is itself HTML (an `![]()
`, styled text, or anything else CSS can lay out), not a bare image URL:
```java
pd4ml.setWatermark("
",
50, 50, // left, top
0.15f, // opacity
30, // rotation angle, degrees
1.0f, // scale
true, true, // visible on screen and in print
"1+");
pd4ml.setPageBackground("", "1+");
```
## 9. Fonts, bookmarks, and hyperlinks
```java
pd4ml.useTTF("/opt/fonts"); // TrueType/OpenType directory to embed glyphs from
pd4ml.embedTTFs(true, false); // embed only the glyphs actually used, not the full font
pd4ml.applyKerning(true); // honor the font's own kerning pairs
pd4ml.enableLigatures(true); // build compound glyphs (fi, fl, ...) where the font defines them
pd4ml.generateBookmarksFromHeadings(true); // one bookmark per