I18n Index Library Tutorial

This section describes how to make a sample PDF using the included batch files.

Please select an XSLT processor from Saxon 6.5.5, Xalan 2.7.1, or Saxon-B 9.1, and then download it from the following URL.

After downloading the archive, unzip it into an appropriate folder.

1.2 Updating Batch File

Modify the startcmd.bat batch file according to the selected XSLT processor. Rewrite the following values to correspond to the location where the .jar file was saved. Not all XSLT processors are needed.

    SET SAXON6_HOME=%PROJECT_HOME%xslt\saxon6-5-5
    SET XALAN2_HOME=%PROJECT_HOME%xslt\xalan-j_2_7_1
    SET SAXON9_HOME=%PROJECT_HOME%xslt\saxonb9-1-0-6j

For instance, if you want to test using SaxonB-9 only, rewrite SAXON9_HOME environmental variable and comment out the other lines.

    REM *** Example ***
    REM SET SAXON6_HOME=%PROJECT_HOME%xslt\saxon6-5-5
    REM SET XALAN2_HOME=%PROJECT_HOME%xslt\xalan-j_2_7_1
    SET SAXON9_HOME=C:\MY_DOWNLOAD\xslt\saxonb9-1-0-6j

Next, please rewrite the following line according to your Formatter environment.

    REM AHF Formatter, XSL Formatter home
    SET AHF_HOME=C:\Program Files\Antenna\XSLFormatterV43
    REM SET AHF_HOME=C:\Program Files\AntennaHouse\AHFormatterV5

1.3 Testing PDF Output

1. From Explorer, click startcmd.bat. The command window titled “I18n Index Library” opens.
2. You can test following batch files from this window.
   • run_en.bat
   • run_zhcn_normal.bat
   • run_zhcn_sortaspinyin.bat
   • run_ja.bat
   • run_ko.bat

   The command format is as follows. Select “saxon6″ ,”xalan2” or “saxon9” as parameter according to the XSLT processor that you downloaded.

   run_en.bat [saxon6 | xalan2 | saxon9]

   [Fig.2]  Example of running a batch file

   

   The result of sample_en.pdf is saved to the current folder.

   [Fig.3]  English output PDF sample

   

1.4 Test Data Features

By running the batch files, you can confirm the following features:

Pinyin/Strokes/Radical/GB2312-90 Code Order

Strokes/Radical/Big5 Code Order

2 Customizing Stylesheet

This library has XSLT1.0 and XSLT2.0 sample stylesheets in the stylesheet folder. These stylesheets create XSL-FO from DocBook instance. Each stylesheet file has the following role. (XSLT1.0 stylesheet has the prefix “dbtofo”. XSLT2.0 stylesheet has the prefix “dbtofo2”.)

The most important stylesheet files are dbtofo_indexterm.xsl and dbtofo_index.xsl. The core index processing algorithms is integrated into these two stylesheets. You can make modifications to this stylesheet or import them into your stylesheets.

3 Library Interface

The library ah_i18n_index.jar has following static method for the stylesheet (XSLT processor).

The first parameter is a language code defined in RFC3066. It should be the main language of the input document.

The second parameter differs by XSLT processor. It must be the same temporary document (Result Tree Fragments in XSLT 1.0) created from the indexterm element. The content has the following element structure.

    <!-- Indexterm element in source document -->
    <indexterm>
        <primary>cheese</primary>
        <secondary>sheeps milk</secondary>
        <tertiary>pecorino</tertiary>
    </indexterm>
    <indexterm>
        <primary sortas="element"><element/></primary>
    </indexterm>
         
         ↓
         
    <!-- Temporary document passed to library -->
    <index-data indexkey="cheese:sheeps milk:pecorino" level="3" nestedindexterm="0" significance="normal">
        <indexterm>cheese</indexterm>
        <indexterm>sheeps milk</indexterm>
        <indexterm>pecorino</indexterm>
    </index-data>
    <index-data indexkey="<element/>" level="1" nestedindexterm="0" significance="normal">
        <indexterm sortas="element"><element/></indexterm>
    </index-data>

The third parameter is a string that indicates to use sortas attribute as pinyin reading. This parameter value should be ‘true' or ‘false'. The default value is ‘false' and this parameter can be omitted.

☞ NOTE: Refer to the JavaDoc in the javadoc folder or db2fo_index.xsl stylesheet source file for details.

4 Note when using sortaspinyin=”true”

In this mode, the sortas attribute is the assumed pinyin reading. So you can correct irregularly positioned indexterm like following.

    <!-- Illegaly positioned indexterm in index page (粘贴 belongs N group)-->
    <indexterm>
        <primary>粘贴</primary>
    </indexterm>
         
         ↓
         
    <!-- Corrected indexterm (粘贴 belongs Z group) -->
    <indexterm>
        <primary sortas="zhan1 tie1">粘贴</primary>
    </indexterm>

But there are other uses for sortas. For example, you might want place “<element/>” indexterm to E group or you might want to treat “β测试” (β testing) as “测试”. In this case, please modify the source document as follows.

    <!-- sortaspinyin="false" mode -->
    <indexterm>
        <primary sortas="element"><element/></primary>
    </indexterm>
    <indexterm>
        <primary sortas="测试">β测试</primary>
    </indexterm>
         
         ↓
         
    <!-- sortaspinyin="true" mode ("∆" means space) -->
    <indexterm>
        <primary sortas="e∆l∆e∆m∆e∆n∆t"><element/></primary>
    </indexterm>
    <indexterm>
        <primary sortas="�∆ce4∆shi4">β测试</primary>
    </indexterm>

Because sortas attribute is assumed as pinyin readings, Hanzi character must be specified as pinyin and Non-Hanzi character can be used as is. However in both cases, pinyin or Non-Hanzi characters must both be separated by a space. And in the latter example, you must insert U+FFFD (REPLACEMENT CHARACTER) instead of “β” character. This is because, the “β” character is not included in sortas attribute. U+FFFD is a placeholder of such character.

5 Other Resources

• This release has an optimized version of I18n Support Library. The original library had many extraneous. To restore the original library, unzip i18n_support_lgpl.zip and rebuild the library. It contains the original documents in the doc folder.
• If you want to change index configurations. You must change i18n_index/config/botb_index_rules/botb_index_rules.xml. For more information please read the documents mentioned above (docs/isogen_i18n_user_guide.html in i18n_support_lgpl.zip) and the comments in the botb_index_rules.xml file.
• If you want to customize index algorithms or use another Java based XSLT processor, you can customize and rebuild ah_i18n_index.jar by using ah_i18n_index_nolgpl.zip. This archive contains the source code of I18n Index Library.