When jOfficeConvert is set to embed fonts, we will attempt to find the best matching font file available on the system. Sometimes we can’t always find the best match and alternatives will be used. To obtain more detailed logging on the process and details for each attempt to find a matching font turn on the qoppa.debug.embedfont option.

Text runs inside a Microsoft Office program typically specify a font by name with a String and boolean properties that indicate whether to use Bold and/or Italic faces. Sometimes an alternative font name is also provided by the Office document, but not necessarily.

Also, via the jOfficeConvert options, a user may specify specific font names to be used either as backups or preferred substitutions for other named fonts, if in case the font in the Office document may either be unavailable on the local system or not preferred by a user.

In version v2022R1, we added a vm option to debug into the font selection and log detailed information about the font matching process.

To turn on font debugging when converting Microsoft Office documents to PDF using jOfficeConvert, enable to the following vm option in your Java application:

qoppa.debug.embedfont = true

When finding a font file to use for a specific named font in an Office document, jOfficeConvert will check the options to see if a substitution font has been specified and is set to be preferred over the original font. If so, we will first search for the substitution font, if not we first search for the original named font in the Office document. If a match is found by name, we will use that font file and also attempt to match the bold and/or italic settings to a specific font face file. If bold and/or italic was specified but a bold and/or italic version of the font face was not found, the plain style font file will be used with the bold and/or italic style simulated during rendering.

If a substitution font was specified but not set to preferred, we will search for the substitution font only if we fail to find a match by name on the original document font.

If a font file matching neither the original nor substitution font names could not be found, then we will check if the Office document specified an alternative font. If so the same process above will be repeated using the alternative font name.

Finally, if no matching font file could be located, the fallback font will be used if a fallback font has been specified. Otherwise, if no fallback font has been specified (or if one was specified but not found) then a PDFException will be thrown from the process.