DITA: Troubleshooting Japanese and Simplified Chinese PDF output

Products: XMetaL Author Enterprise 4.6 and later, or DITA Open Toolkit 1.4.1 with RenderX XEP.

By default, the DITA Open Toolkit (DITA OT) includes configuration files to produce HTML output for 47 locales, and 7 locales for PDF output. As of DITA OT 1.5, the 7 preconfigured locales for PDF output are:

- English (en-us)
- French (fr-fr)
- German (de-de)
- Italian (it-it)
- Japanese (ja-jp)
- Simplified Chinese (zh-cn)
- Spanish (es-es)

You can configure the DITA OT to work with additional locales, such as Traditional Chinese and Russian, however this article will only cover how to work with the preconfigured locales.

HTML output from the DITA OT usually appears correctly in any language. When creating PDF output, however, Simplified Chinese and Japanese characters often do not appear at all. This article explains how to make Simplified Chinese and Japanese characters appear. It is assumed that you are using RenderX XEP as your XSL-FO processor. RenderX XEP is installed automatically with XMetaL Author Enterprise Edition.

Background
When creating a PDF file, you must indicate what font(s) to use for displaying text. If the font is not available on your system, the text will appear either incorrectly or not at all. Most fonts that are widely used for Western languages cannot display Chinese or Japanese characters, and the fonts which are aesthetically optimal for Western languages are not optimal for Asian ones.

You can configure the DITA Open Toolkit to use any font for any language. By default, it is preconfigured to use a font called "Adobe Song Std Light" for Simplified Chinese, and a font called "KozMinProVI" for Japanese. Both of these fonts are free, however if you don't regularly read Japanese or Chinese documents on your computer, you probably don't have them installed. To create PDF files which use these fonts, you must do the following:

1) Download and install the fonts.
2) Configure RenderX XEP so that it can find the font files.
3) Apply a patch to the DITA OT so that it will use the correct fonts in headings.

Prerequisites

Before you begin, locate your active copy of the DITA OT folder.
Make sure the root element of each DITA topic and map is tagged with an appropriate xml:lang attribute. See DITA: Indicating the language of content for DITA processing for details.
You do not need to know XSL or any programming language to work with the files mentioned in this article. However, make sure you know how to open configuration files using an appropriate multilingual text editor.

Downloading and Installing the Fonts
1) Download and install this: Adobe Reader 9 Font Packs - Chinese Simplified
2) Download and install this: Adobe Reader 9 Font Packs - Japanese
3) Open your Windows Fonts folder. This is typically C:\WINDOWS\Fonts.
4) Open the folder in which the font packs have been installed. This is typically C:\Program Files\Adobe\Reader 9.0\Resource\CIDFont. You should see at least four files, including AdobeSongStd-Light.otf and KozMinPr6N-Regular.otf. Copy those two files to your Windows Fonts folder.

Configuring RenderX XEP
1) Locate your xep.xml file. For most installations of XMetaL Author Enterprise, it is in the following folder: C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL Shared\renderx

2) Do ONE of the following:
- Download and unzip the file that is attached to this article. Back up the existing xep.xml file and replace it with the copy of the xep.xml file that you just downloaded.
- Open the xep.xml file in a text editor. Copy the following lines of code and paste it within the <fonts> element of the xep.xml file, then save the file:

Code:

<font-group xml:base="file:/C:/Windows/Fonts/">
   <font-family name="AdobeSongStd-Light">
   <font><font-data otf="AdobeSongStd-Light.otf"/></font>
</font-family>
   <font-family name="KozMinProVI-Regular">
   <font><font-data otf="KozMinPr6N-Regular.otf"/></font>
</font-family>
</font-group>

Patching the DITA OT to use custom fonts for headings
There is a known issue in one of the default stylesheet files which causes headings to appear in Helvetica rather than the correct font. To fix this issue, see the post, "Patch for making headings use the correct font in PDF output".

Adding an "xml:lang" attribute to your content

The "xml:lang" attribute indicates what language your document is in, so that the publishing system can display it appropriately. The XMetaL Enhanced PDF output format uses the xml:lang attribute that is set at the root of the primary map file. To set the xml:lang attribute:

1) Open the DITA map file in the XMetaL map editor pane.
2) Click the map title to select it.
3) Click the Properties button.
4) Click the Other Attributes tab.
5) In the Language field, type either ja-jp for Japanese, or zh-cn for Simplified Chinese.
6) Click OK.

To generate output, click File > Generate Output for DITA Map. Select "XMetaL Enhanced PDF for RenderX XEP" as the deliverable type. After output is generated, you should now see your Japanese or Simplified Chinese content appearing in the PDF.

For testing, you can download a set of sample DITA files in Japanese and Simplified Chinese, which is attached to this article.

Legal:
* Licensed Materials - Property of JustSystems, Canada, Inc.
*
* (c) Copyright JustSystems Canada, Inc. 2010
* All rights reserved.
*
*-------------------------------------------------------------------
* The sample contained herein is provided to you "AS IS".
*
* It is furnished by JustSystems Corporation as a simple example and has not been
* thoroughly tested under all conditions. JustSystems Canada, Inc., therefore, cannot
* guarantee its reliability, serviceability or functionality.
*
* This sample may include the names of individuals, companies, brands and products
* in order to illustrate concepts as completely as possible. All of these names are
* fictitious and any similarity to the names and addresses used by actual persons or
* business enterprises is entirely coincidental.
*---------------------------------------------------------------------