Dictionaries Help
Name:Dictionary
Version:2.5.0
Last update:2019-11-27 14:12:51



This file describes the AlphaTcl Dictionary package.

The Dictionary package is a programme for consulting plain-text dictionaries. So you need at least one such dictionary to have any use of this package. You can download Dictionaries from the internet. There are also some small example dictionaries included in the package.
You can activate the package via the Features Preferences dialog.
NB: There is another dictionary facility in Alpha, the package Www Dictionary, which looks up words in online dictionaries.

The Dictionary Console

The interface to each Dictionary is a small window (Console) with two text fields: a one-line input field and a big output field. Type a word in the input field and press Return (or Enter) and the corresponding entry of the dictionary is shown in the output field. The Corresponding Entry is the first entry in the dictionary which is greater than or equal to the word, according to the criterion specific to the dictionary.
Instead of typing words and pressing Return, with this feature you have the following possibilities, quite standard in dictionary programmes --- these functions are bound to keys as follows:
⌘-UpSee the preceding article in the dictionary
⌘-DownSee the following article
⌘-LeftGo Back (to the previous word you looked up)
⌘-RightGo Forward (to the word you looked up after the actual one)
These two Right/Left functions are meant to work like Back and Forward in a web browser. The Right function makes sense only if you have previously used the Back function.
With Arrow keys (unmodified), you can navigate through the output field, jumping from word to word. The output field is completely hyperised: whenever you press Return (or Shift-Command-Double-Click), the word under the cursor is looked up.
The key shortcut ⌃⌥⇧⌘O will open the data file of the dictionary if you want to have a closer look.

Invoking the Dictionary Console

Turning this package on will insert a new Tools ↣ Local Dictionaries submenu which contains some self-explantory menu items, like Consult Dictionary and Change Dictionary. But the recommended usage is to use the key binding ⌃O which does the same as Consult Dictionary: it brings the Console to front (for the Current Dictionary), and at the same time looking up the word that happens to be under the cursor at that time (i.e. selected text if any; otherwise the word preceding the cursor in the text). Pressing ⌃O again sends you back to the spot in the window from where you invoked the Dictionary. (So the whole lookup sequence consists of two keystrokes based on the "O" key...)

Changing dictionary

The programme manages an arbitrary number of Dictionaries, which are loaded as needed. Each has its own Console, and its own History List etc. One of the Dictionaries is considered as the Default or Current dictionary. This is the one invoked by ⌃O. To change the Current Dictionary, hit ⌃⇧O and choose from the available Dictionaries in the list dialogue. This brings the Console of the new Dictionary to front, with the word under the cursor already looked up. This new Dictionary is now Current.

Managing consoles

This package creates two preferences, named Common Console and Background Console, which can be set by selecting the menu item Alpha ↣ Preferences ↣ Package Preferences ↣ Dictionary:
Common Console
if it is checked, then there is only one Console shared by all Dictionaries. This can be practical to avoid window clutter, but then you cannot have more than one Dictionary open at a time.
Background Console
if it is checked then when you invoke ⌃O (or select Tools ↣ Local Dictionaries ↣ Consult Dictionary), the word is looked up in the background, i.e., the Console does not come to front. This is only practical if you have a large screen so that the Console goes free of your main window. In this case, it is very seemless to look up a word: you don't even leave your main window!
When a Dictionary Console (either common or dictionary specific) first opens, it places itself at a default position somewhere near the right-hand side of your screen. Of course you can just drag the window around, and if you find a good place where you want to have it permanently, you can select the menu item Tools ↣ Local Dictionaries ↣ Save Dict Console Geometry. As long as the preferences for Common Console is turned off, each Dictionary console can have its own default position. When Common Console is turned on, the saving applies to the position of the Common Console.

Installing new dictionaries

Primitive installation

  1. You need a Dictionary file in plain text, with one entry per line (line termination \r). Place the file anywhere you want.
  2. Choose the menu item Tools ↣ Local Dictionaries ↣ Install Dictionary. In the Open-dialogue box, locate the Dictionary file; in the ensuing dialogue box, give a name to the new Dictionary. Unless the Dictionary was prepared specifically for this package, there will be a warning that no Tcl code was found. Don't worry --- or read the instructions below for advanced installation.
  3. The Dictionary is now ready to use.

Fine tuning

It may happen that the Dictionary is not consistently sorted, or that its sort criterion is slightly different from the one assumed by the programme. This can sometimes imply that a word is not immediately found when you look it up. (Usually you can find it manually by Arrowing Up and Down a little bit).
You can always check the sorting of the Dictionary by selecting the menu item Tools ↣ Local Dictionaries ↣ Some Tools ↣ Check Sorting. A list of all words which defy the order will appear as output on the screen. If there are many, it is better to sort the file. This can be done by selecting the command Tools ↣ Local Dictionaries ↣ Some Tools ↣ Sort Dictionary File: this will produce a new file with the extension .sorted added to the original filename. This new file must then be installed separately (and perhaps you would like first to uninstall the old file, by selecting the menu command Tools ↣ Local Dictionaries ↣ Some Tools ↣ Uninstall).

Advanced installation

In addition to the steps described above, the advanced part consists in writing a couple of simple procs to fine-tune the performance: To see the syntax and get an idea of what needs to be done, look first in the example dictionary Country-codes found in the Dictionary-Examples folder.
Insert this code at the beginning of the Dictionary file you are working on. More instructions are found in the Dictionary formats section. Adjust the offset...

Getting dictionaries

There are three ways:
  1. find one on the internet,
  2. prepare one yourself, or
  3. copy from somebody who has one.
There are some good plain text dictionaries available for download, for example: The most interesting way of getting dictionaries is to distill them from commercial programmes (but beware of copyrights). Most such programmes sport the two functions needed to do this: a Next function, and a Copy function. Now it is possible to write a macro which looks up all the words of the Dictionary one by one and copies them into a text file in Alpha. (This can take many nights, of course!)
Any plain text file with one entry per line will do --- if sorted consistently (some tools are provided to help with this). But in case the file is marked up, you will also need to write a little proc for rendering, i.e. telling the lookup function to interpret the markup and how to display the result (instructions are included).

Dictionary formats

A dictionary file has three parts: two header sections and the main body.
  1. The first header is a description of the file for humans. It may contain description of the origin of the file, copyright notices, and the like.
  2. The second header contains instructions for the dictionary script. (Also called the boot sector of the dictionary file.)
  3. Part three, the main body, is simply the list of words, with one word definition per line, and sorted according to the compare proc specified above.
The first part is never read.
The second part is read once by Alpha, namely the first time the dictionary is opened: it then loads the two procs into memory and is ready to look up words. In order for the Tcl interpreter to be able to find this important information, this block must begin with a line 
    <!-- BEGIN TCL
and end with a line 
    END TCL -->
The third part starts at the offSet, defined as the beginning of the first non-white line after the END TCL --> tag. The dictionary programme reads small chunks of random access between $offset and [maxPos], for each lookup. Typically a lookup consists of around 12 quick accesses, and a final chunk which is somewhat bigger.

The boot sector

The boot sector should contain two Tcl procedures: Finally, the boot sector may give colouring instructions. This aspect has not yet been very much exploited. Currently the only accepted instruction is like 
   variable citeDelims [list “ ”]
which would instruct the programme to colour all strings enclosed in curly quotes green. (This particular instruction is taken from the Webster-1913 dictionary, where it serves to colour all citations.)
To see what the boot sector and a dictionary file may look like, open one of the four example dictionaries (located in the Dictionary-Examples folder): To see an example of a really heavy dictionary file (in all respects), look at the Webster-1913 dictionary from https://mat.uab.es/~kock/alpha-tcl/Webster-1913.gz.

More about the format

If the dictionary file is nothing but a sorted list of lines, without any markup, there is not much to do for the rendering proc: just break the output into lines that are not too long.
But typically there is an advantage of having some markup in the dictionary file, and among the files found on the internet there are some with html markup. Of course you don't want to see those tags on the screen when you look up a word so you need to tell the programme how to handle that: these instructions are given in the proc formatOutput which takes a string as input and formats it. (So it mostly performs a series of [regsub] commands...)
More info about the working of the lookup proc: it starts by reducing the input to normal form (which is defined by the proc normalForm), it then performs a binary search in the interval between $offSet and [maxPos] of the dictionary file. When the interval has been narrowed conveniently, the precise location is found linearly. Now if the file is not consistenly sorted, (or if it is sorted according to other criteria than the one specified in the preamble), the lookup script may fail to find a word. You can check if this is the case by invoking the command Check Sorting (found in Utils ↣ Local Dictionaries ↣ Some Tools). If there is any essential alphabetical disorder, you should either perform a sort (invoking Sort Dictionary File) --- this will inforce the criterion specified in the preamble, or: have a look at the out-of-order words to see if you can detect any criterion which governs the order. Then adjust the normalForm proc correspondingly...

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2004-2019, Joachim Kock.
All rights reserved.
The Dictionaries package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JOACHIM KOCK BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.