Fonts must be installed on your server to use the Windward engine. The engine uses these fonts to both perform page layout and to create PDF reports. Every font used in a template must be installed on the server. This page walks you through the process.
Also read All About Fonts for more information on this topic.
The Importance of Matching Fonts
There is a significant difference between the fontmetrics. EX: Courier, Arial, Trebuchet
Windward uses the fontmetrics to determine how tall each line of text is, where to put in soft line breaks, where to put in soft page breaks, etc. If the layout is performed with Arial but the font is actually Courier, then the final document will have too much text on each line with letters overlapping.
In addition, the person designing the report expects the generated report to look a certain way. If the final document needs to use Lucida Sans, but it hasn't been installed on the server, the font might default to Times New Roman, which can create a very different feel as well as disturb the format due to the size of the text.
Note that these two lines are the same point size, but take up a different amount of space on the page.
Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in liberty, and dedicated to the proposition that all men are created equal.(Lucida Sans)
Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in liberty, and dedicated to the proposition that all men are created equal. (Times New Roman)
If the end users get a report that looks significantly different, then they are not going to be satisfied with the output. Therefore you must install the fonts you want to use in your finished report template on the server.
All Fonts Are Not Created Equal
So you can just copy the Windows fonts over to Linux right? No.
First, that is a violation of the license for the fonts as they are licensed for your Windows O/S only.
Second, while true type fonts can be used on any system, they generally look poor when used on a different O/S. Good true type fonts are tweaked for each O/S and you need the version designed for your O/S if you want the text to look right.
A Font May Not Have All Necessary Glyphs
In addition, many fonts do not have the glyphs for all characters. Virtually all fonts (except symbol variants) have the Latin glyphs as well as the European characters. Many have the additional common short alphabets: Arabic, Cyrillic, Greek, & Hebrew. But the majority do not have the Asian (Chinese, Japanese, & Korean) or complex (Hindi, Thai, etc.) glyphs.
If you are using characters that are more than the Latin alphabet, you need to ensure that the fonts you install on your server have the glyphs you need.
Also watch out for situations, such as using Out Tags, where you may be using a Chinese (or other Asian) font and the font of choice has no Chinese glyphs. The tag, itself, might print well because it is written in Latin characters, but when the report runs the text which populates the field is Chinese and causes disturbances in the format, or simply doesn't work.
There Are Two Sets of Fonts
When Windward runs, there are two distinct sets of fonts it uses.
First are the fonts the JVM (Java Virtual Machine) sees. These are the default fonts used for the layout of the page. Second are the fonts that iText sees for PDF rendering. These second fonts can also be used for layout (how to is listed below) instead of the Java fonts.
Both sets of fonts are truetype fonts. Both sets can, and should be, the same set of font files on your system. The critical issue here is that having a font file only on your server is not sufficient. Java and iText must be configured to see these fonts.
- Java generally pulls the fonts that the O/S has installed. If Java does not see the O/S fonts, contact your vendor to find out what to do.
- If iText does not see the fonts, add the directory they are in to the font.files= setting in WindwardReports.properties.
Setting the path where you installed your Linux fonts:
You can run the utility net.windward.tools.ShowFonts (in WindwardReports.jar) and it will list all fonts in each group.
In the WindwardReports.Properties, uncomment the last line and then point it to the directory where your fonts are installed on your Linux system.
- IE: font.files = /usr/bin/fonts/WindwardFonts/*.ttf
You can list a series of paths, separated by semicolons, to where the true type fonts are on your system. The only wildcard recognized is the * (ie, no regular expressions).
Using the iText Fonts for Line Breaks
You can set line.break=internal in your WindwardReports.properties file and that will do two things:
- The page layout will use the iText fonts instead of the JVM fonts. If both point to the same font files, this makes no difference.
- The rules for where breaks are allowed in text use Windward rules (basically spaces) instead of the JVM rules.
This is a useful fallback if you cannot get fonts registered with your JVM. However we strongly encourage you to get fonts registered with the JVM. Incorrect server configuration will generally cause you problems, and usually at the worst time!
Purchasing & Installing Fonts on Your Server
Red Hat Systems:
- To install for only one user:
o Double-click the "Computer" icon on your desktop.
o In the "File" menu, choose "Open Location..."
o Type in: fonts://
o When the fonts window appears, drag and drop the fonts to be installed into this window.
- To install for all users:
o Login as root.
o Create a directory under /usr/share/fonts/
- For example: /usr/share/fonts/custom
o Copy the fonts to this directory and run:
- fc-cache -f /usr/share/fonts/
- In KDE:
o Use the "Control Center" -> "System Administration" -> "Font Installer" utility
- In GNOME:
o To install for only one user:
- Simply place the font files into the "~/.fonts" folder
- Note that this folder is hidden. Use the command "ls -a" in the terminal to display it.
- Log out and log back in.
o To install for all users:
- Log in as root.
- Place the fonts into the "/usr/share/fonts" folder.
- Log out and log back in.
Also see te Oracle Font Administrator User's Guide
- Open the Font Administrator:
o Click the Application Manager control in the CDE Front Panel's Applications subpanel.
o In the Application Manager, double-click the System_Admin folder
o In the System_Admin folder, double-click the Font Administator icon.
o Alternatively you can type the command: /usr/dt/bin/sdtfontadm &
- Choose Install from the Fonts menu.
- From the top of the dialog, choose the directory to list fonts from.
- Select the fonts you wish to install.
- Choose the directory to install the fonts to then select the "Install" dialog.
- If there are any conflicts between the new font and an existing font, a window will be presented to resolve them.
Also see Installing Fonts
- Via Synaptic:
o You will need to enable the Universe and Multiverse repositories (see: Adding Repositories).
o Once these are enabled, search for "font" in Synaptic and install any desired fonts.
o You may need to restart applications, and log out then log back in for the new fonts to be recognized.
o Create a new folder in /usr/share/fonts/truetype/
o Place your font files into this new directory.
o Enter the following in the terminal: sudo fc-cache -f -v
Windward Font Mapping
Generally you will not need to set any font mapping. We strongly discourage using font mapping instead of installing the correct fonts on your server. These settings exist to handle naming differences, not to map from one font to another. In other words, mapping from Arial to Helvetica is generally ok. But mapping from Times New Roman to Helvetica is bad.
The Windward engine (and the JVM) do a pretty good job substituting fonts as needed. So substituting Helvitica for Arial or Times Roman for Times New Roman will generally happen automatically.
This directly maps one font name to another and you can have as many pairs as you wish. This performs a direct substitution of font names for PDF reports and also when using line.break=internal for page layout. This is the setting to use to substitute font names on the server.
Note: prior to version 11.1.46 the substituted font must exist in the template (ie setting Arial=Helvetica required that the Helvetica font is included in the font table int he DOCX/PPTX/XLSX file). If it is not, the engine throws an exception. Starting with version 11.1.46 the font does not need to reside in the template's font table.
This maps font names to their true type name. This also is used just in iText so for PDF output and, if line.break=internal is set, for line breaks. Do not use this to map to a different font. Only use this to map the font name to the true type name for the font. You will rarely need to do this. It is needed if for example you are using Arial and the font you have installed has a true type name of Arial(MT) and it is not being mapped to that.
This has nothing to do with font mapping. But it does define how fonts are used in the PDF generate in 3 modes. Using core fonts, using system fonts but not embedding them and finally using system fonts and embedding them.
- 0 - ADOBE INTERNAL FONTS ONLY Will only use the Acrobat internal fonts which are Helvetica (Arial), Times-Roman, Courier, Symbol, and Zapfdingbats. All fonts will be mapped to one of these five fonts.
- 1 - FONT IS NOT EMBEDDED IN PDF(default) Will use the font specified in the template but will not embed the font itself in the pdf file. This adds very little to the size of the final file. However, if Acrobat cannot create a font for the filename specified, it will not display the final file.
- 2 - FONT IS EMBEDDED IN PDF Will use the font specified in the template and will embed the font in the final pdf file. This will provide the most accurate final pdf file and all fonts can be rendered. However, it makes the final file a lot larger.
If you have X-Windows running on your server, you can ignore this section. Or if you see line.break=internal you can ignore this section.
If you do not have X-Windows installed, you need to install it. You do not need to run it, but you need to install it. In many cases Java uses the installed libraries and/or fonts for many of the Java library calls.
Your O/S may also require some configuration settings to run in headless mode. Consult your O/S documentation for details.