Using non-Western fonts in your Firebird docs

A font embedding guide for Firebird docwriters and translators

Paul Vinkenoog

7 March 2020 – Document version 1.1

Table of Contents

Introduction
How the PDF is created
Step 1: Find the fonts you need
Step 2: Override the stylesheet fonts
Step 3: Create metrics files
Step 4: Create a FOP userconfig file
Step 5: Build the PDF and commit your work
Afterword
A. Document history
B. License notice

Introduction

If you use non-Western characters in your Firebird documentation, the HTML version will probably look fine – modern browsers can display any language and script, as long as the necessary fonts are present on the user's machine. But making the PDF version come out right requires a number of extra steps. This is what you have to do:

Find the fonts you need for body text, titles, and monospaced text.
Override the default (Western) fonts specified in the stylesheets.
Create metrics files for the fonts you're going to use.
Create a FOP userconfig file with font embedding instructions.
Build the PDF and if everything works as intended, commit the results of steps 2–4 to git.

If you are the first person in the Firebird documentation project to write in a certain language, you'll have to complete all of the above steps. Otherwise you can use the existing setup, but you may have to edit the FOP userconfig file because font file locations can differ from system to system. See the “Important” box in the section on Step 4.

It is assumed that you already know how to create and edit DocBook XML files in your own language and save them in a Unicode encoding, e.g. in UTF-8. XMLMind, SciTE, Windows Notepad and others have no problem with this (XMLMind saves in UTF-8 by default). ConText can only save Unicode as UTF-16, but as far as I know this poses no problem for the build tools.