Dictionary Developer Utilities


DictBuilder

DictBuilder is a part of MDict application.
DictBuilder.app resides inside the MDict.app bundle in:
/Applications/MDict.app/Contents/Resources/DictBuilder.app
DictBuilder.app is a GUI wrapper for DictBuilder core scripts. These scripts can be used without the GUI from the command line (see below).
They reside inside the DictBuilder.app bundle: DictBuilder.app/Contents/Resources/DictBuilder.
DictBuilder.app switches between the Pack/Unpack Modes automatically:
- If you specify a directory as the input, DictBuilder switches to the Pack Mode (see unpacked dictionary directory structure below);
- And if you specify a dict-file as the input, it switches to the Unpack Mode.
For these scripts to work you will need a Mac OS X HFS+ like file system, and file names must be in UTF-8 encoding.


Unpacked Dictionary Directory Structure

Unpacked dictionaries have the following directory structure (this format is common for all unpacked MDict dictionaries):
￼
1
Unpacked dictionary parent folder.
When packing your dictionary, this folder’s name will be used as your dictionary’s name.

2
Words folder contains your dictionary’s word files (i.e. dictionary entry files.)
You should put contents of each dictionary entry in a separate word file. Word file names must correspond to entry names of your dictionary.
For example, if you want to create a dictionary entry for the word “dictionary”, you should browse to Words folder and create a new file called “dictionary.txt” (if you’re creating a simple plain text dictionary or a plain text dictionary with hypertext markup), or “dictionary.html” (if you’re creating an HTML dictionary), and this file should contain the text of the dictionary entry.
Word file names may contain optional numeric suffixes delimited with a dash from main parts of their names, e.g.: “Atlas-1.txt”, “atlas-2.txt” (for simple plain text dictionaries), and “Test-3.html”, “test-4.html” (for HTML dictionaries). This feature allows creating two or more dictionary entries that differ only in their titles’ character case. When packing a dictionary, these numeric suffixes are always discarded.
All the following file names for the dictionary entry “test” are allowed:
- test
- test-1
- test-2.txt
- test-3.html

3
Replacements folder is optional. It may contain replacement files for dictionary entry names containing special characters not allowed in file names.
For example, you want to create a dictionary entry for the term “input/output”. “input/output” is an illegal file name, because it contains a special character – “/”. Therefore you should choose another name for this dictionary entry’s file, e.g., “input_output”. Then you should browse to Replacements folder and create a file with the same name (in our case it would be “input_output”) containing only one line of text: “input/output”.
Note: A replacement file’s name must be fully identical with the corresponding word file’s name (including its extension). So if you’re creating an HTML dictionary, a replacement file name for the word file called “input_output.html” should be also named “input_output.html”. And this replacement file should contain neither HTML tags nor metadata, but only one line of text: “input/output” (without quotes.)
When packing a dictionary, each word file WordN from Words folder is checked for its counterpart in Replacements folder, and if such replacement file is found, the text from Replacements/wordN file is used as that dictionary entry’s title.
This alias technique gives maximum flexibility in naming dictionary entries.
Accordingly, if during a dictionary unpacking process DictBuilder detects an entry whose title contains special characters, it automatically creates a replacement file for that word file (e.g., _REPLACEMENT_SomeNum-SomeNum).

4
Extensions folder is optional, too. It may have an arbitrary directory structure and contain random multimedia files (images, documents, Wave audio, Flash or even video files.)
If you’re creating an HTML dictionary, you can link to multimedia resources inside this folder from your dictionary entries. These links must be relative to your Extensions folder. Links to your Extensions folder itself should look like “__E__” (without quotes). When compiling a dictionary, DictBuilder replaces “__E__” with the real path to your Extensions folder.
Link examples:
- A link to image file “Extensions/fish.png” in the HTML word file “Words/fish.html” would look like this:
<img src=“__E__/fish.png”>
- A link to video file “Extensions/Movies/fisher.mov” would look like this:
<a href=“__E__/Movies/fisher.mov”>Fisher Video Clip</a>
- And if you prefer internal viewing, you should use the following link:
<object type=“video/quicktime” data=“__E__/Movies/fisher.mov” width=“320” height=“260”><param name=“controller” value=“true”/>[Fisher Video Clip]</object>
When packing your dictionary, DictBuilder packs Words folder into “My Dictionary.dict” (your dictionary file containing all the dictionary entries) and “My Dictionary.idx” (your dictionary’s index file); and your Extensions folder is packed into “My Dictionary.ext” (where “My Dictionary” is the name of your dictionary’s parent folder used as your packed dictionary’s name.)
A simple dictionary structure with multimedia resources could look like this:
demo-dict
demo-dict/Extensions
demo-dict/Extensions/colors.png
demo-dict/Extensions/Movies
demo-dict/Extensions/Movies/intro.mov
demo-dict/Extensions/Movies/test.mov
demo-dict/unpack.log
demo-dict/Words
demo-dict/Words/adobe colors panel.html
demo-dict/Words/intro-1.html
demo-dict/Words/test-2.html
After packing this dictionary, you would get three output files: “demo-dict.dict”, “demo-dict.idx” and “demo-dict.ext”.
Resulting “demo-dict.dict” file contents could look like this:
Adobe Photoshop CS 2 color panel looks like this:<br>
<img src="__E__/colors.png">
Apple WWDC'06 Intro<br>
<object type="video/quicktime" data="__E__/Movies/intro.mov" width="360" height="280">
<param name="controller" value="true" />
 [Test Movie Video Clip]
</object>
Test<br>
<a href="__E__/Movies/test.mov">Test link</a>
When packing your dictionary, DictBuilder captures all your word files into a single dict-file.


Dictionary Entry File Format

Links

All MDict dictionary formats support cross-referencing between dictionary entries. MDict cross-references have the following simple Wiki-like format:
[:[ … ]:]
Note: you may use any characters after the opening tag ([:[), except the white space.
Example:
[:[have]:] – a link to a dictionary entry titled “have”.
MDict cross-references may be compound:
[:[been|be]:] – “been” as a link to a dictionary entry titled “be”.
You can also use this cross-reference tag to link to external resources via http, ftp, file and feed protocols:
[:[http link demo - link to Apple|http://apple.com]:]
[:[ftp link demo - link to FreeBSD server|ftp://ftp.freebsd.org]:]
[:[file link demo - shows /etc/hosts|file:///etc/hosts]:]
[:[feed link demo - some RSS|feed://www.macosxhints.com/backend/geeklog.rdf]:]
Tip: you can use HTML tags in the first part of compound links (in HTML dictionaries only), e.g.:
[:[<strong><sup>х</sup><sub>а</sub><sup>в</sup><sub>а</sub><em>т</em><i>ь</i></strong>|есть]:]
or even:
[:[<img src=http://mif.mitme.ru/images/mdict.png>|dictionary]:]
if you want to use an externally stored image as a link.
If you’re creating an HTML dictionary containing multimedia resources, and your Extensions/images folder contains a file named “mdic.png”, you can use this image file as a link:
[:[<img src=__E__/images/mdict.png>|dictionary]:]


CSS Styles

If you’re creating an HTML dictionary, you can also use CSS styles.
You can create a CSS file called, say, “styles.css” inside your Extensions/css folder that would contain the following CSS formatting style:
/* dictionary styles */
p { font-size: 30; color: red; }
and then link to this CSS file from inside your HTML word files:
<link type=text/css rel=stylesheet href=__E__/css/styles.css />
<p>test
Because at runtime all dictionary articles are split into separate HTML parts between directives, and those HTML parts are rendered independently, it is necessary to include style-lines after each MDict directive for styles to take effect.


Dictionary Distribution

After packing your dictionary using DictBuilder app, you may want to zip resulting files into a single archive and distribute it via the Internet.
If you’ve created a simple dictionary containing no multimedia resources, your zip-archive would contain two files: “dict.dict” and “dict.idx” (where “dict” is the name of your dictionary.) And if you’ve created a multimedia-rich dictionary, except the above two files, your zip-archive would contain also a file with the extension “.ext”.
Beginning from version … MDict supports new dictionary package format with “mdict” extension. Dictionary packages simplify storage and distribution of your dictionaries, as they contain all dictionary files (dict, idx and ext files) in a single package file. A dictionary package may contain one or more dictionaries.
Additionally, a dictionary package file may also contain a property list file (a file with the extension “.plist”) containing dictionary metadata, such as dictionary name, dictionary format (Plain, Plain/HT or HTML) and dictionary description. Here is an example of a dictionary property list file contents (for a package containing two dictionaries):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
 <key>aliases</key>
	<dict>
		<key>dict1</key>
		<string>Dict1 Name</string> //-- the name of the first dictionary
		<key>dict2</key>
		<string>Dict2 Name</string> //-- the name of the second dictionary
	</dict>
 <key>types</key>
	<dict>
		<key>dict2</key>
		<string>Plain/HT</string> //-- dictionary format
	</dict>
 <key>information</key>
	<dict>
	 	<key>dict1</key>
		<string>dictionary1 full description here</string> //-- dictionary description
	</dict>
</dict>
</plist>
To create a dictionary package file:
1. Create a new folder.
2. Put dict, idx, ext (if your dictionary is multimedia-rich) and plist (if you’ve created one) file(s) into that folder.
3. Rename that folder using the name of your dictionary (or a short description of dictionaries, if you add more than one dictionary to your package, e.g. “English Dictionaries”, or “Business Dictionaries”), then add the extension “.mdict” (without quotes) at the end of the folder name and push the Enter button.
4. When a dialog appears asking, if you are sure you want to add the extension, click “OK”.
After creating your dictionary package you may want to archive it using built-in Mac OS X archiving feature (Control-Click/Right-click on your mdict-file and choose “Create Archive of...”) or third-party archiving utilities to reduce its file size.
There are several ways to install a new dictionary package:
1. Drag-and-drop a dictionary package onto MDict window.
2. Open MDict dictionary preferences (click “Dictionaries” button in MDict toolbar, push  Command-, keyboard shortcut (MDict window must be in front), or select MDict > Preferences in the menu bar, and then choose “Dictionaries” tab, if it isn’t already active), click “+” button (the leftmost button under the list of installed dictionaries), browse to the dictionary package file you want to install and click “Open”.
3. Double-click a dictionary package file in Finder.
The first two methods can also be used for installing MDict raw dictionaries (files with “.dict” extension.)


DictBuilder Scripts

You can process your dictionaries in the command line using these three simple Perl scripts:
- dictparser.pl – for unpacking a StarDict-like tab-dictionary to a directory with the structure described above;
- unpackdict.pl – for unpacking an existing MDict dictionary to a directory with the structure described above;
- packdict.pl – for packing a directory with the structure described above to a dictionary file (with its parent folder’s name used as the resulting dictionary file name) for its later distribution.
You’ll need a Perl interpreter to run these scripts. You’ll also need to set their permissions to “executable” (+x) after unzipping them. You can set these script files’ permissions to +x  using the following command in Terminal.app:
chmod +x unpackdict.pl packdict.pl
You should run these scripts using corresponding commands in Terminal.app. To get help on using the scripts run them using the following command (assuming that the scripts are in the current folder):
./dictparser.pl
./unpackdict.pl
./packdict.pl

Good Luck!
– MiF.
