PD4Browser: Interactive Converter and Fonts Tool

PD4Browser is a desktop application included in pd4ml.jar; its window is titled PD4ML Converter. It shows an HTML document page by page, exactly as PD4ML lays it out, and updates the preview as you resize the window, change the page format or adjust other settings. One click converts the document to PDF, DOCX or RTF. Its Fonts Tool builds the font mapping files (pd4fonts.properties) and font JARs that useTTF() reads.

PD4Browser is meant for development work: finding the right HTML width, page format and margins for a document, checking how CSS changes affect page breaks, and preparing fonts. It can also convert a single document without opening its window (see Converting without the window). For scripted conversion with more options, use Pd4Cmd or the Java API.

The application is the class org.zefer.pd4ml.tools.PD4Browser. It keeps its settings in a plain text file, pd4browser.properties, described in The pd4browser.properties file below.

Starting PD4Browser

The usual way to start it is the -gui option of pd4ml.jar:

java -Xmx512m -jar pd4ml.jar -gui
java -Xmx512m -jar pd4ml.jar -gui https://example.com/report.html
java -Xmx512m -jar pd4ml.jar -gui file:/C:/work/report.html -ttf C:/work/fonts

• A URL after -gui opens that document on start. file:, http: and https: URLs are supported.
• -ttf <font directory or mapping file> uses a different set of fonts for this session than the one in your settings file (see Fonts).
• -Xmx gives Java enough memory for large documents, since the preview keeps the whole laid-out document in memory.

You can also start the class directly, which lets you choose the settings file:

java -Xmx512m -cp pd4ml.jar org.zefer.pd4ml.tools.PD4Browser [-config <settings file>] [URL]

-config names the settings file PD4Browser reads when it starts and writes when it closes. Without it, and whenever you start with -gui, PD4Browser uses pd4browser.properties in the folder you start it from. If you start PD4Browser from different project folders, each project keeps its own settings, history and presets.

Converting without the window

Give PD4Browser an output file after the URL, and it converts the document without opening a window:

java -Xmx512m -Djava.awt.headless=true -cp pd4ml.jar org.zefer.pd4ml.tools.PD4Browser [-config <settings file>] <URL> <output file>

The conversion uses the same settings as Render in the window: page format, margins, fonts, headers and footers, bookmarks, encryption and everything else in pd4browser.properties. This makes it a simple way to reproduce, from a script, exactly what you see in PD4Browser.

A few differences from the window:

• The result is always a PDF, whatever format render.format.selection names.
• The HTML width comes from userSpace.width (there is no window to measure): the width the preview had when PD4Browser was last closed, minus the page margins.
• The settings file is only read, never written.
• Progress messages go to the console.

The window

PD4Browser with an invoice open, at an HTML width of 787 pixels. The status bar shows two presets, [ 1 ] and [ 2 ].

Toolbar

Render saves its result as a temporary file named pd4ml…pdf (or .docx, .rtf). The file goes into the folder set in dir.tmp, or your system's temp folder, and is removed when you close PD4Browser. To keep a result, save a copy from the application that opened it.

Preview

The middle of the window shows one page of your document as PD4ML renders it, with rulers along the top and left edges. As you move the mouse over the page, the status bar shows its position in pixels, counted from the top left corner of the content area. When you drag, it also shows the size of the dragged rectangle, which is useful for measuring elements.

The window width is the HTML width. PD4Browser lays out your document as a browser window as wide as the preview, minus the page margins. This is the same value you'd pass to setHtmlWidth() in your application. A wider window makes the content smaller on the page; a narrower one makes it larger. The preview is redrawn after every resize, and Render uses the same width, so the exported document matches the preview.

Status bar

From left to right:

PD4Browser also prints its progress to the console, with the time each step took: reading, parsing, layout, page breaks and writing. With debug.info.enable set, PD4ML's log appears there as well.

Presets

Presets let you switch between documents that need different settings. Clicking a preset sets:

• the window width, and with it the HTML width;
• the folder the file dialog opens in;
• optionally the page format, margins and orientation;
• optionally a label that goes into the PDF's Creator and Producer fields.

You define presets in pd4browser.properties, as preset.1.* up to preset.9.* (see Preset keys below). Number them without gaps: PD4Browser stops reading at the first missing number. Each preset gets its own [ n ] button in the status bar.

Closing

When you close PD4Browser, it saves its state to pd4browser.properties: the window size and position, your address history, the chosen output format, the folders you used last and all other settings.

Fonts

PD4ML finds its fonts through a font mapping file, pd4fonts.properties (see Configuring PDF Fonts). PD4Browser takes the font folder or mapping file from ttf.fonts.dir, or from -ttf on the command line, and passes it to useTTF(). The preview and every export use the same fonts.

With ttf.fonts.default.serif, ttf.fonts.default.sansserif and ttf.fonts.default.monospace you choose the fonts used for the generic CSS families serif, sans-serif and monospace in exported documents. font.kerning and font.ligatures turn on kerning and ligatures (see applyKerning() and enableLigatures()).

Fonts Tool

The Fonts Tool, available since v4.0.16, builds a font mapping file interactively, as an alternative to Pd4Cmd's -configure.fonts option.

The Fonts Tool in PD4ML Converter 4.0.16, filtered to the Arial, Courier New and Times New Roman files of C:\Windows\Fonts. The toolbar of the current version looks different.

1. Click [ Fonts Tool ] in the status bar.
2. Select a folder with TrueType or OpenType fonts, such as your project's font folder or a system folder like C:\Windows\Fonts. The tool lists every font it finds, one mapping line each (Font\ Name=fontfile.ttf), in a text area you can edit.
3. A system font folder usually holds far more fonts than a document needs. To narrow the list, type a few file name patterns into the field at the top, separated by commas (for example arial, cour, times), and press Enter or click Filter By Font File Name. Only fonts whose file names contain one of the patterns stay in the list. Case is ignored.
4. Edit the list as needed: remove fonts you don't need, rename keys so they match the font-family names in your CSS, or add fallback entries like customsans1=… (see Tweaking Fonts in PDF).
5. Finish with one of the buttons:

Inside the JAR, the fonts sit in a folder called pdffonts, and that's the name you give useTTF(). To use a different folder name, uncomment the jar.folder line at the end of the list and change it before you save. Then use the new name in useTTF("java:<folder>"):

# SAVE AS JAR: uncomment below and specify JAR folder to store the font files.
# Fonts from "pdffonts" folder are available via pd4ml.useTTF("java:pdffonts")
jar.folder=myfonts

The tool remembers the last font folder you used (dir.last.fonts) and your filter (font.tool.filter).

The list has the same format as any font mapping file: Java properties, one font per line. The key is the font name as your CSS refers to it, with spaces escaped by a backslash, and the value is the font file. For a font inside a TrueType collection (.ttc), the file name ends with the font's number in the collection:

Arial=arial.ttf
Arial\ Bold=arialbd.ttf
Courier\ New=cour.ttf
SimSun=simsun.ttc_1
customsans1=mybrandfont.ttf

Indexing fonts from the command line

The same mapping file can be generated from the command line:

java -jar pd4ml.jar -configure.fonts <font directory> [<mapping file location>]

Starting the class directly with PD4Browser -configure.fonts <font directory> does the same. If the current folder has no pd4browser.properties yet, it also creates one with that font folder already set as ttf.fonts.dir.

The pd4browser.properties file

pd4browser.properties is a standard Java properties file: one key=value setting per line, and lines starting with # are comments. The file is read as ISO-8859-1, and a backslash escapes special characters. So write Windows paths either with doubled backslashes (C\:\\work\\fonts) or with forward slashes (C:/work/fonts), and use \uXXXX escapes for non-Latin text.

PD4Browser saves the file when it closes, with the keys sorted alphabetically. If the file doesn't exist yet, it's created at that point with your current settings. Any keys PD4Browser doesn't know about are kept as they are.

Values are read as follows:

• true and false turn an option on or off. Anything other than true counts as false.
• Numbers are whole numbers. If a numeric key holds something that isn't a number, PD4Browser does not start, and the error is printed to the console.
• The text null in a text value means "not set".

Some settings affect only exported files:

• Used for the preview and for exports: page format, orientation, margins, fonts, kerning, ligatures, the extra CSS, table.breaks.enable, userSpace.adjustToContent, pdf.protect.pud, multi-column layout, the proxy and debug output.
• Used only when you click Render: everything that changes the output file, like headers and footers, bookmarks, links, form fields, PDF/A, document title and author, encryption, default fonts and image settings.

Page

Rendering

Fonts

PDF output

These settings are used only when you click Render.

Encryption and permissions

These settings are used only when you click Render. PD4Browser never writes them itself, so add them by hand.

Header and footer

These settings are used only when you click Render. They give every page a simple header and footer: a title line and a page number, or your own HTML, plus an optional watermark image. The header.* and footer.* keys work the same way, so the table only lists the header.* names. An area stays empty until you set a template or a watermark for it.

Preset keys

You can have up to nine presets, numbered from 1 without gaps.

preset.1.dir=C:/work/invoices
preset.1.width=950
preset.1.format=A4
preset.1.margins.ltrb=15,20,15,20,mm
preset.2.dir=C:/work/reports
preset.2.width=1200
preset.2.landscape=true

Network

Session state

PD4Browser maintains these keys itself; you rarely need to edit them.

Unused keys

Some keys are still written for compatibility with older versions, or remain from them, but have no effect: adobe.font.metrics, rendering.patch, viewer.params, dir.viewer, viewer.executeble and viewer.rtf.executeble.

If you have a settings file from PD4ML v3, it may still use insets.top, insets.left, insets.right, insets.bottom, insets.units and page.orientation for margins and orientation. PD4Browser still reads them, and replaces them with page.margins.ltrb and page.landscape the next time it saves the file.

Example

A complete file for A4 documents with 15 mm margins, your project's fonts, kerning, a footer with page numbers and unencrypted PDF output:

page.format=A4
page.landscape=false
page.margins.ltrb=15,15,15,15,mm
userSpace.adjustToContent=true

ttf.fonts.dir=C:/work/project/fonts
ttf.fonts.default.sansserif=Open Sans
font.kerning=true

page.bookmarks.headings=true
page.hyperlinks=true
document.author=ACME Corp.
permissions.mask=-1

footer.height=20
footer.page.num.template=Page $[page] of $[total]
footer.page.num.align=center
footer.font.face=Arial
footer.font.size=9

preset.1.dir=C:/work/project/templates
preset.1.width=950

See also

• Pd4Cmd Command-Line Reference: converting from the command line and from scripts.
• Configuring PDF Fonts: font mapping files and useTTF() in detail.
• PD4ML Fonts Tool and Tweaking Fonts in PDF on pd4ml.com.
• PDF Header and Footer Generation: HTML headers and footers through the API.
• PD4ML API Reference (Javadoc).