Converting to PDF
There are two conversion paths and they are not variants of one feature. Pick deliberately, because the constraints are what separate them.
| Path | How it works | Runs on |
|---|---|---|
| Native | UniOffice lays the document out and writes the PDF itself | Anywhere Go runs |
| OLE | Drives an installed copy of Microsoft Word and asks it to export | Windows, with Word installed |
Native conversion is the default answer. It has no external dependency, runs on
a server, and is the only option in a container. document/convert exports four
functions in total: ConvertToPdf, ConvertToPdfWithOptions, RegisterFont
and RegisterFontsFromDirectory. Both convert functions return a
UniPDF *creator.Creator rather than bytes, so nothing is written until you ask
it to be, and you can add metadata or pages first. That also means two metered
license keys have to be set, one for UniOffice and one for UniPDF; a program
that sets only the first will not produce a usable PDF. It is the same key in
both places, and forgetting the second is the most common licensing problem
reported against UniOffice, so it has an FAQ entry of its own:
Why does my license key fail when converting to PDF?
What you give up is Word’s rendering. UniOffice is doing the layout, using its
own defaults where the document supplies none: A4 pages, 12 point text, one inch
margins. Field codes are the sharpest edge. The converter evaluates PAGE,
NUMPAGES, FORMCHECKBOX, and REF when field processing is enabled, and
leaves every other field code alone without saying so. A TOC field written by
UniOffice and never opened in Word converts to an empty contents page.
Fonts are the other one, and the more common. A document names its fonts and rarely embeds them. Helvetica, Courier and Times New Roman resolve to the built-in PDF base fonts; anything else has to be registered from a TTF file first. If it is not, the converter logs a debug line and draws the text in Helvetica, which has different metrics, so the text is all present and the line breaks are all in the wrong places.
The OLE path exists for when those differences matter more than the deployment
cost. Word does the work, so the output is what File, Save As, PDF would have
given you, and fields that need an application to evaluate them come out
populated. The price is a Windows host with Word installed and licensed, plus a
dependency on github.com/go-ole/go-ole. It is not something to run as a
service under a non-interactive account.
Where to look
| Guide | Covers |
|---|---|
| Document to PDF | The basic native conversion, and which fields it evaluates. |
| Custom Fonts | Registering TTF files so text is drawn in the right typeface. |
| Conversion Options | What convert.Options controls, and the subsetting default that trips people up. |
| Export via OLE | Driving Word over COM on Windows. |
| Generate a TOC via OLE | Getting a TOC field populated so a native conversion can render it. |