In this page

Overview

The PDF file format was designed by Adobe to allow using any font you'd like in the documents. Better PDF Exporter offers the same grade of flexibility for the PDF documents that are exported from Jira.

Exporting Jira issues with Unicode characters to PDF
Exporting Jira issues with Unicode characters to PDF

Since version 6.4.0 the app comes with a default strategy to select the best font for your documents after intelligently analyzing their content. Therefore, it works perfectly for pretty much any language and any Unicode symbol out of the box.

You should look into font configuration only in the following typical cases:

  • When the glyphs (symbols) of your language are not found in the font automatically selected by the app. This should be a relatively rare case as the app comes with a super-rich font. And even if it happens, you can easily supply your own font file to get this working.
  • When typography plays an important role in your brand identity. If your team standardizes on using a specific set of fonts in all business documents, you probably want to use those instead of the default font also in the PDF documents exported from Jira.
  • When filesize is important. PDF defines 14 fonts (called Standard Type 1 fonts, Standard 14 fonts or Base 14 fonts) with special significance. These or their reasonable substitutions should be available for any PDF reader application. If you use glyphs only from these, you can get smaller PDF files, because font information does not need to be embedded in the PDF files.
    Standard 14 include normal, bold, italic and bold-italic versions of serif, sans-serif, monospace and symbol fonts, therefore they meet most typographic needs. Unfortunately, they contain glyphs mostly for the common Western Latin languages and aren't a good fit for Asian, Slavic, Arabic languages.

How to use fonts?

You can use multiple strategies to select the fonts for your documents. You can use different strategies in different PDF templates and you can even combine different strategies within the same template.

This table compares the options and the following sections will go into details about each.

Used font(s) Advantages Disadvantages Recommended if
Automatically selected font (default) Just works. In most cases. (You should use the other options only when having a good reason.) Learn more
Standard 14 font Smallest filesize. Limited to Western Latin characters only (roughly speaking). If filesize is important and you are fine with the character limitations. Learn more
Custom font Any font can be freely used. Embedding the custom fonts results in larger PDF files. If you want to use your own fonts. Learn more

About the Standard 14 Fonts

Standard 14 fonts contain glyphs for the "Western Latin" languages. The table of Windows-1252 characters gives a good approximation of the supported characters.

As you see, these are included:

  1. Most Western European languages (English, German, French, Spanish, etc.)
  2. Punctuation marks (brackets, dash, basic math signs, etc.)
  3. Various symbols (Euro symbol, copyright symbol, etc.)

There are typical examples of languages whose glyphs are not included:

  1. Slavonic languages
  2. Arabic languages
  3. Asian languages

Like written above, you can get any language working using custom fonts. Just read on.

Using various types of fonts

In the following sections we explain the various options in details and also give working examples for each.

To keep the examples short, we are using <fo:block> elements in those, but typically you want to set the font family on the <fo:root> element so that it gets applied to the whole document.

Using automatic fonts

This is the default strategy. It works as expected in most cases, therefore if you are unsure, just use this.

It automatically chooses the correct font based on the characters to be shown in the final PDF. You can set this behavior by using the "auto" pseudo font family: 

<fo:block font-family="auto">This text can contain any character, it will be OK!</fo:block>

How does it work? Before rendering the FO document into the PDF file, the renderer checks if there is any character used in the document that is not available in the Standard 14 fonts:

  1. If all characters are in the Standard 14 fonts, "Helvetica" will be used. As "Helvetica" is a Standard 14 font, there is no font to embed in the final PDF file, thus that remains lightweight. Therefore, it works optimally if you are using Western Latin characters only.
  2. If there is at least one character unavailable in Standard 14 fonts, "Arial Unicode" will be used. Arial Unicode is a font that contains glyphs for most languages in the world. Therefore, it works optimally if you are characters from "non Western Latin" languages.

As you see, it works optimally in both cases. You can simply think about "auto" as synonym for "the optimal font family based on the characters used in this PDF".

Using Standard 14 fonts only

Use this strategy if you want to use the standard fonts that are "built in" to every PDF reader application. Read the Wikipedia article on Standard 14 Fonts to learn more about the typefaces and their variations.

The primary advantage of this strategy is that it can reduce the filesize of the final PDF documents, because there is no need to embed font information in those. While the size reduction may be significant for small PDF files (e.g. from 30K to 10K), it is less significant for large PDF files (e.g. from 1000K to 980K).

When choosing this strategy, all you have to do is making sure that you are using only the font families shown in the example below. Make sure you are not using "auto", because that may eventually turn into "Arial Unicode", as explained above.

If you are using these font families, but try to insert a character that is not available in these, it will be displayed as a hash character ('#') in the PDF.

As you see, there are alternative font family names (synonyms) for some, which you can use interchangeably, if you prefer so: 

## Helvetica is a sans-serif typeface. (It should be your default choice.)
## Synonyms: "sans-serif", "SansSerif"
<fo:block font-family="Helvetica">Hello Helvetica!</fo:block>

## Times is a serif typeface.
## Synonyms: "serif"
<fo:block font-family="Times">Hello Times!</fo:block>

## Courier is great for mono-space content like source code.
## Synonyms: "monospace", "Monospaced"
<fo:block font-family="Courier">for (int i = 0; i &gt; 23; i++) {} </fo:block>

## Symbol contains the Greek alphabet, math symbols and such.
<fo:block font-family="Symbol">&#945; = &#931; &#946; </fo:block>

## ZapfDingbast contains every sort of signs and symbols.
## Use it to add graphics like circled digits, arrows, check marks to your documents.
<fo:block font-family="ZapfDingbats">&#x2460; &#x27A5; &#x2713;</fo:block>

Using custom fonts

Use this strategy if you wanted to use your own fonts for some reason.

Steps:

  1. Login to Jira as administrator.
  2. Go to Administration → Add-ons → PDF Templates.
  3. Open the fop-config.xml file.
  4. Register the directory that contains your font files by adding a <directory> element to the <fonts> section.
    For example: 
    <renderers>
	<renderer mime="application/pdf">
		<fonts>
			<!-- local font, in case of Windows -->
			<directory>C:\Windows\Fonts</directory>
			<!-- local font, in case of Ubuntu Linux -->
			<directory>/usr/share/fonts/truetype/ubuntu</directory>
			<!-- optional, in case of specifying styles, on Windows -->
			<font kerning="yes" embed-url="file:\\\C:\Windows\Fonts\Verdana-Italic.ttf">
				<font-triplet name="Verdana Italic" style="italic" weight="normal"/>
			</font>
			<!-- optional, in case of specifying styles, on Linux -->
			<font kerning="yes" embed-url="file:///usr/share/fonts/true-type/Ubuntu-Italic.ttf">
				<font-triplet name="Ubuntu Italic" style="italic" weight="normal"/>
			</font>
		</fonts>
	</renderer>
</renderers>

    Notes:

    • There is probably a <directory> element existing which we added to make it easier. If so, uncomment and modify that.
    • The <directory> element must contain a full filesystem path in its body text which specifies a directory that contains font files (TTF, etc.). The renderer will scan those directories when searching for fonts by font family name. To search in a directory and all of its sub-directories, use <directory recursive="true">.
  5. Alternatively, if you want to use fonts from a remote URL, add the <font> element like this: 
    <renderers>
	<renderer mime="application/pdf">
		<fonts>
			<!-- remote font -->
			<font kerning="yes" embed-url="http://www.mysite.com/fonts/Verdana.ttf">
				<font-triplet name="Verdana" style="normal" weight="normal"/>
			</font>
		</fonts>
	</renderer>
</renderers>
  6. Save your changes.
  7. Open the issue-fo.vm file or whichever template you want to use the custom font.
  8. Tell the template to use your preferred font by referencing that by its font family name. You can set the font for any scope (the whole document, a single block, a single word, etc.) by setting the font-family attribute of the corresponding FO element. If you want to use that in the whole document, set it for fo:root: 
    <!-- in case of Windows -->
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" font-family="Verdana">
<!-- in case of Ubuntu Linux -->
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" font-family="Ubuntu">

    Notes:

    • You need to use the font name (typeface names), not the file name! Open the font file with the default font viewer of your operating system to see the precise font name in the file. (There can be multiple fonts in one file.)
    • Font-names are case-sensitive! ("Ubuntu" will work, but "ubuntu" will not.)
  9. Save your changes, and try another export. If you can't see the new font being used, check these:
    1. If the font was not found, the renderer will fall back to using "Times". If so, check the configuration steps again.
    2. If you receive a "java.lang.UnsupportedOperationException: ... not yet supported" exception, check the corresponding troubleshooting article.
  10. Hooray, it works!

See even more information about registering custom fonts in the Fonts page of the FOP project.

Using "undefined" fonts

This is the strategy of not setting the font-family attribute at all in the FO template. This is somewhat a special case, but it is a frequent one.

When this happens, the renderer will just use "Helvetica".

Please note that Adobe Reader replaces "Helvetica" with "Arial" and "Times" with "Times New Roman" when displaying PDF documents, for copyright reasons. Therefore, don't be surprised to see "Arial" when no font was specified.

Don't mix this case with not setting font-family for just one or more FO elements! That's absolutely normal: you should not set that attribute for every FO element separately, because the template code gets unnecessarily complicated. As expected, FO elements simply inherit the font setting from their parents, and this is a mechanism you can and should rely on.

Questions?

Ask us any time.