Preparing Dictionary Contents

Take a look at the MyDictionary.xml file provided in the project template. Your dictionary should follow this form, using UTF-8 encoding. You can change the file name to something other than MyDictionary, but if you change the name, you must edit the DICT_SRC_PATH variable in the makefile.

Dictionary User Interface and Markup ) describes the XML schema you should use to develop a dictionary. The schema uses the RELAX NG schema language, which is described on this website:

http://www.relaxng.org/

You should validate your dictionary source prior to building a new dictionary You can use RELAX NG validators programs, which are available from this website:

http://www.relaxng.org/#validators

You can also validate XML using jing as follows:

$ java -jar <path to jing.jar> <schema definition> <XML to validate>

From the project_template folder, with jing located in ../jing/, the command line is as follows:

$ java -jar ../jing/bin/jing.jar ../documents/DictionarySchema/AppleDictionarySchema.rng MyDictionary.xml

For more information on jing, see:

http://www.thaiopensource.com/relaxng/jing.html

Preparing a Style Sheet

You can prepare a style sheet to use for the contents of the dictionary by editing the MyDictionary.css file provided with the project template. If you change the name of this css file, you need to edit the CSS_PATH variable in the makefile.

You should minimally edit the style sheet.  The Dictionary application and the Dictionary window control use their own style definitions to ensure that the contents fit the display. For best results, do not specify an absolute font or font size.

Editing the Property List File

The property list file for a dictionary is an an XML text file. The project template contains an example file—MyInfo.plist—whose contents are shown in Listing 2-1. You can edit this file so that it contains entries appropriate for your dictionary. Table 2-1 explains the values that you need to provide for your dictionary.

Listing 2-1  An example of a property list file for a dictionary

<key>CFBundleDevelopmentRegion</key>

<string>English</string>

<key>CFBundleDisplayName</key>

<string>My Dictionary</string>

<key>CFBundleIdentifier</key>

<string>com.apple.dictionary.MySample</string>

<key>CFBundleName</key>

<string>MyDictionary</string>

<key>CFBundleShortVersionString</key>

<string>1.0</string>

<key>DCSDictionaryCopyright</key>

<string>Copyright (c) Apple Computer, Inc.</string>

<key>DCSDictionaryManufacturerName</key>

<string>Apple Computer, Inc.</string>

If you change the name of the property list file, you must edit the PLIST_PATH variable in the makefile.

Adding Resources Needed by Your Dictionary

You must place any resources (for example, images) that your dictionary needs in the OtherResources folder in the project_template folder. When you build the dictionary, the resources are copied into the built dictionary.

For example, if your dictionary uses an image file name test.png, you need to place it in the following location:

project_template/OtherResources/Images/test.png

The Images folder is copied into the dictionary. When the dictionary needs the image, it uses to the relative path—Images/test.png—which is written to the XML file during the build process.

Preparing the Makefile

Name your dictionary and then edit the DICT_NAME variable in the makefile. This name is used as the folder name for the dictionary. For example, when DICT_NAME = “My Dictionary”, the built dictionary is My Dictionary.dictionary.

If you change the location of the Dictionary Development Kit from /Developer/Extras/Dictionary Development Kit, you must modify the DICT_BUILD_TOOL_DIR variable in the makefile to reflect the change.

Building the Dictionary

To build your dictionary, follow these steps:

1. Launch the Terminal application.

2. Use the cd command to change to the appropriate location:

   /Developer/Extras/Dictionary Development Kit

3. Enter make.

4. After the make process finishes successfully, type make install to copy the new dictionary to:

   ~/Library/Dictionaries/

After running the make install command, you can delete all the intermediate files in the objects folder. In the Terminal window, enter make clean to remove the objects folder.

Now you can launch the Dictionary application and test your new dictionary.

As you can see from looking at the makefile, the building process uses a script build_dict.sh, located in /Developer/Extras/Dictionary Development Kit/bin. This script takes 4 arguments—dictionary_name, dictionary_source_path, StyleSheet_path, and InfoPlist_path. It builds a new directory in the /objects folder.

Prepare an Entry for the Front and Back Matter

In the XML file for the dictionary, you need to specify a front-back matter entry using an id attribute whose value is set to front_back_matter as shown in the following simple example:

<d:entry id="front_back_matter" d:title="Front/Back Matter">

    <h1><b>My Dictionary</b></h1>

    <h2>Front/Back Matter</h2>

    <p>

        This is a front matter page of the sample dictionary.<br/>

    </p>

    ...

</d:entry>

Modify the Info.plist File

You must modify the property list for the dictionary by adding the DCSDictionaryFrontMatterReferenceID key to the Info.plist file. The associated value is a string that specifies the id value you used in the XML file. The following shows the string used in Prepare an Entry for the Front and Back Matter.

<key>DCSDictionaryFrontMatterReferenceID</key>

<string>front_back_matter</string>

Add an Index Entry (Optional)

This example does not use a <d:index> element, which means that the page won’t show up in a search. If you want the front and back matter to show in a search, add the<d:index> element. Otherwise, users can view the front and back matters by choosing Go > Front/Back Matter from within the Dictionary application.

Modify the Dictionary Contents Appropriately

You need to modify the contents to support the preferences that you set up. For example, if you want to allow the user to choose from among three phonetic notations, you need to provide the three phonetic notations for each entry in our dictionary. The following example shows three phonetic notations for the word make.

<d:entry id="make_1" d:title="make">

    ...

    <h1>make</h1>

    <span class="syntax">

        <span d:pr="US">| māk |</span>

        <span d:pr="US_IPA">| meɪk |</span>

        <span d:pr="UK_IPA">| meɪk |</span>

    </span>

    ...

</d:entry>

Note that the XML does not specify which phonetic notation to show. You’ll do that in the next section by creating an XSLT file.

Prepare an XSLT File to Apply to Dictionary Entries

The XSLT files contains instructions that Dictionary Services applies to each entry before displaying the it. In this example, you need to provide instructions to remove the unused phonetic notation. For this, use the $pronunciation variable, which is a global variable supply by the Dictionary application, as shown in the following example.

<xsl:template match="*[@d:pr='US']">

    <xsl:if test="$pronunciation = '0'">

        <xsl:copy>

            <xsl:apply-templates select="@*|node()" />

        </xsl:copy>

    </xsl:if>

</xsl:template>

<xsl:template match="*[@d:pr='IPA']">

    <xsl:if test="$pronunciation = '1'">

        <xsl:copy>

            <xsl:apply-templates select="@*|node()" />

        </xsl:copy>

    </xsl:if>

    <xsl:if test="$pronunciation = '2'">

        <xsl:copy>

            <xsl:apply-templates select="@*|node()" />

        </xsl:copy>

    </xsl:if>

</xsl:template>

<xsl:template match="*[@d:pr='US_IPA']">

    <xsl:if test="$pronunciation = '1'">

        <xsl:copy>

            <xsl:apply-templates select="@*|node()" />

        </xsl:copy>

    </xsl:if>

</xsl:template>

<xsl:template match="*[@d:pr='UK_IPA']">

    <xsl:if test="$pronunciation = '2'">

        <xsl:copy>

            <xsl:apply-templates select="@*|node()" />

        </xsl:copy>

    </xsl:if>

</xsl:template>

Implement the Preferences User interface

You need to provide an XHTML file that specifies the user interface to present in the Dictionary Preferences window in the Dictionary application. The following example shows how to set up preferences for phonetic notation. The user will see three choices displayed as radio buttons. After making a selection, Dictionary Services saves the it and passes the selection to the XSLT instructions. The instructions are then applied to the dictionary entries.

<html xmlns="http://www.w3.org/1999/xhtml">

    <head>

        <meta http-equiv="content-type" content="text/html; charset=UTF-8" />

    </head>

    <body>

        <div id="copyright"></div>

        <hr />

        <div class="query">

            <input type="hidden" name="version" value="1" />

        </div>

        <div class="query">

            Pronunciation:<br />

            <input type="radio" name="pronunciation" value="0">US English (Diacritical)</input><br />

            <input type="radio" name="pronunciation" value="1">US English (IPA)</input><br />

            <input type="radio" name="pronunciation" value="2">British English (IPA)</input><br />

        </div>

    </body>

</html>

Modify the Info.plist File

You must add keys to the Info.plist file to indication that the dictionary has its own preferences. The values for this example are shown in the following property list entry. You need to change the values to ones that are appropriate for your dictionary. The values expected for each of the keys are shown in Table 2-2.

<key>DCSDictionaryDefaultPrefs</key>

    <dict>

        <key>pronunciation</key>

        <string>0</string>

        <key>version</key>

        <string>1</string>

    </dict>

    <key>DCSDictionaryPrefsHTML</key>

    <string>MyDictionary_prefs.html</string>

    <key>DCSDictionaryXSL</key>

    <string>MyDictionary.xsl</string>