# The &kdict; Handbook

Christian
Gebauer

    gebauer@kde.org

Christian
Gebauer

    gebauer@kde.org

Developer

Reviewer
2002
Christian Gebauer
&FDLNotice;
2003-09-30
0.5.6

&kdict; is a graphical client for the DICT protocol. It enables you to search through dictionary databases for a word or phrase, then displays suitable definitions.

KDE
kdict
kdenetwork
dictionary
translation

## Introduction

&kdict; is a graphical client for the DICT Protocol. It enables you to search through dictionary databases for a word or phrase, then displays suitable definitions. &kdict; tries to ease basic as well as advanced queries. A separate list offers a convenient way to deal with the enormous number of matching words that a advanced query can return.

The remainder of &kdict;'s user interface resembles a web browser. For instance, you can jump to the definition of a synonym by simply clicking on the highlighted word. The back/forward functionality is also implemented, enabling you to quickly go back to the result of previous queries.

&kdict; is able to process the content of the clipboard, so it's easy to combine &kdict; with your web browser or text editor.

If your machine is behind a firewall, has no permanent internet connection or the server of dict.org is too slow for you, you can set up your own local server, all you need is available at www.dict.org. The advantages of a local server are optimal performance and the ability to install additional databases of your choice. This handbook contains a small tutorial for installation and links to databases.

## Using &kdict;

### Getting Started

After you have started &kdict; (using the panel menu, or by typing `kdict` at the command prompt) the &kdict; main window shows up:

Starting &kdict;
The &kdict; main window.

The &kdict; main window.

There are two different methods to lookup a word or phrase with &kdict;. You can use a define query. &kdict; will look for exact matches in the databases and displays all matching definitions in the lower left view. Or you can use a match query, in this case all matching database entries will be displayed in the list view on the right side. You can then decide what definitions you want to look at. This method has the advantage that you can use more sophisticated search strategies like prefix, suffix or regular expressions.

### Configuring the DICT server

Before you can make your first query, you have to check if the preset server settings work with your setup. You can modify the settings in the preferences dialog. The preset server is dict.org, which is a public server, so you don't have to change anything if you have a working internet connection.

You can test your configuration by selecting Server Information from the Server menu, this displays some status information about the server.

Now you should use Server Get Capabilities, this will fetch a list of all available databases and strategies from the server. &kdict; is now able to show you all features of the server in its menus. (You should always call Get Capabilities after switching to a new server)

### Basic Queries: Define

A define query will search for words/phrases in the selected database(s) that match the given text exactly. The definitions belonging to these words are displayed in the main view. If the server finds nothing suitable, &kdict; will use a search strategy optimized for spell checking to display a list of of similar words.

In most databases some words (especially synonyms) are marked with brackets {}. These words are highlighted and by clicking on them with the &LMB; you start an new define-query with this word.

You can select a part of the text with the &LMB;. The selection is automatically copied into the clipboard. This is very convenient, because you can use the &MMB; anywhere in the main view to define the content of the clipboard. So, if you want to get a definition for a word/phrase that is not tagged as synonym, you just mark it with the &LMB; and get the definition when you press the &MMB;.

The &RMB; shows a popup menu, where you can choose to start queries with the selected text, the clipboard or the tagged synonym under the mouse pointer. The menu has also two entries Back and Forward. You can use them to browse through the results of previous queries.

### Advanced Queries: Match

A match query uses the currently selected search strategy (the strategy selector is is located above the match list) to search in the selected database(s) for words similar to the given text. The result is a list of similar words that appears in the match list on the right. The entries are grouped according to the database they belong to. Now you have multiple options:

- You can use the Get All button (located below the match list) to fetch all definitions. Please note that the number of listed words and fetched definitions may differ, because in some cases two or more words share one definition and &kdict; removes the duplicated definitions.

- You can use the mouse or the keyboard to select the most interesting words in the list and then press the Get Selected button (located below the match list) to fetch only them. If you want to get all definitions from one database just select the list item which contains the database name.

- When you press Enter (keyboard) or double click (mouse) on a list item, &kdict; will ignore the selection and fetch the definition for this item. When you do this with a root item (an item that contains the database name), you will get all definitions belonging to this database.

- You can use one of the words as a starting point for a new query, this is done via the popup menu (&RMB;).

A click with the &MMB; anywhere in the list will start a new match query with the content of the clipboard (similar to the main view).

The &RMB; calls the popup menu for a list item, which has the following entries:

Get

  Shows the definition for the current item.

Match, Define

  Starts a match/define query with the current item.

Match Clipboard Content, Define Clipboard Content

  Starts a match/define query with the current content of the clipboard.

Get Selected, Get All

  Same functions as the buttons below the list.

Expand List, Collapse List

  (Un)folds all databases.

### Database Sets

Sometimes it's useful to restrict a query to a subset of the available databases, for example all english-german dictionaries. This is achieved by defining database sets. These sets appear in the database selector as virtual databases.

You can access the configuration dialog via Server Edit Database Sets or the toolbar icon.

Editing database sets
The database set editor.

The database set editor.

The dialog has the following elements:

Set

  You must use this selector to select the set you want to modify. You can also rename a set here by entering a new name and pressing the Save button.

Save

  Saves changes you made in the current set. You must use this button before you select another set or leave the dialog, because otherwise all changes will be lost.

New

  This button creates a new database set.

Delete

  Deletes the currently selected set.

Close

  Closes the dialog without saving your changes.

The two lists (Selected Databases and Available Databases) show which databases are currently in the database set. You can use the arrow buttons between the lists to transfer items from one list to another.

By the way, you can leave this configuration dialog open and continue your work with &kdict;. This is a nice way to test your changes immediately.

### Preferences

You can modify many aspects of &kdict;'s behavior in the preferences dialog. The dialog can be opened via Settings Configure Kdict or the the toolbar icon.

Configuring &kdict;
The preferences dialog.

The preferences dialog.

The dialog is divided into several pages. The Default button restores the default values for the current page. The Apply button will apply your changes on all pages. The OK button will apply the changes and close the dialog. The Cancel button does this without saving the changes. By the way, you can leave the preferences dialog open and continue your work with &kdict;. This is a nice way to test your changes.

#### The Server Page

Hostname

  The internet hostname or the ip address of the DICT server.

Port

  This is the port number the server listens on. 2628 is the default port and is used by the most servers.

Hold connection for

  &kdict; is able to keep the connection open in short periods of inactivity. This feature avoids the lengthy login procedure before every query. A value of 0 seconds disables this feature. Very large values aren't useful, because in most cases the DICT server will close the connection after a couple of minutes.

Timeout

  This value determines how long &kdict; will wait for a answer from the server.

Command Buffer

  The DICT protocol allows the client to send multiple commands in one network packet. The size of the internal command buffer determines how many commands are send in parallel by &kdict;. You can try to tune this value for your network connection, but in most cases it is not worth the effort.

Encoding

  With this selector the text encoding method of the databases can be specified. The default value is "utf8", this setting should work on most servers. If an encoding is selected that doesn't match the encoding used by the databases, you will see broken characters.

Server requires authentication

  Activate this if you want to provide a authentication with username and password. (a server may require this for access to all databases) You have to enter a valid Username and Password combination below.

#### The Appearance Page

On this page you can customize the colors and fonts of the definition view. A proportional font for the normal text will increase readability, but will also destroy the hardcoded layout of tables and similar things in the definitions of some databases.

#### The Layout Page

The layout of the result isn't really configurable yet. But you can decide how many headings (a heading states which database the definition belongs to) &kdict; should place in the result. The choices should be selfexplaining. Note that changes on this page won't have any effect until you start a new query.

#### The Miscellaneous Page

On this page you can modify various limits that prevent &kdict; from eating up insane amounts of memory.

Definitions

  This limits the number of definitions you can fetch at once by selecting them in the match list.

Cached Results

  This number determines how many previous results are held in a internal cache for fast access. You can set this to 0, but this will disable your ability to browse back to old results.

History Entries

  This is the number of past entries the input line remembers. Large values will cause a slower start and shutdown of &kdict;.

Save history on exit

  If this is selected, &kdict; will remember your history between sessions.

Define selected text on start

  If this is selected, &kdict; will immediately try to define the contents of the clipboard when it is started.

## The Panel Applet

If you use &kdict; frequently you may find it useful to use the included panel applet. You can get the applet via K-Menu Configure PanelAddApplet Dictionary.

The Panel Applet
The Panel Applet

The Panel Applet

The input field behaves like the input field of the &kdict; main window. When you press Enter &kdict; opens and the query starts. Instead of typing you can also select a phrase you entered before from the drop down list.

Additionally the applet features three push buttons:

C

  Define the current content of the clipboard.

D

  Define the current content of the input field.

M

  Start a match query with the current content of the input field.

## Command Reference

### The File Menu

&Ctrl;S File Save

  Saves the current result as an html document.

&Ctrl; P File Print

  Prints the current result..

File Start Query

  Defines the content of the input field..

File Stop Query

  Aborts the current query..

&Ctrl;Q File Quit

  Quits &kdict;.

### The Edit Menu

&Ctrl;C Edit Copy

  Copies the currently selected text into the clipboard.

&Ctrl;C Edit Select All

  Selects the complete text.

Edit Define Clipboard Content

  Defines the current content of the clipboard.

Edit Match Clipboard Content

  Find database entries which match the current content of the clipboard.

&Ctrl;F Edit Find...

  Finds a string in the displayed definitions.

### The History Menu

&Alt;Left History Back

  Displays the previous search result.

&Alt;Right History Forward

  Displays the next search result.

History Clear History

  Clears the list of past queries.

At the bottom of the History the ten last queries are listed.

### The Server Menu

Server Get Capabilities

  Determines which databases and strategies are available on the DICT server. You must call this once to be able to specify search strategy and database for a query.

Server Edit Database Sets...

  Opens the database set editor.

Server Database Information

  Submenu which offers a summary of the databases available, and detailed information for every database.

Server Strategy Information

  Displays a list with short descriptions of the search strategies available on the current server.

Server Server Information

  Displays some status information (uptime, &etc;) about the current DICT server.

### The Settings Menu

This menu provides options for configuring &kdict;, changing its appearance, shortcuts and standard behavior.

Settings Toolbars

  Submenu which toggles the toolbars on or off. You can toggle either the Main toolbar or the Query toolbar independently.

Settings Show Statusbar

  Toggles the statusbar on/off.

Settings Show Match List

  Hides (or shows) the match list.

Settings Swallow Match List

  This (un-)swallows the match list into the main window.

Settings Configure Shortcuts...

  Opens a dialog for changing the key bindings. Using this option you can change the standard key shortcut for &kdict;'s commands or create new ones.

Settings Configure Toolbars...

  Opens a dialog for configuring the toolbar. You can add and remove toolbuttons for &kdict;'s commands with this option.

Settings Configure Kdict...

  Opens the preferences dialog.

### The Help Menu

&help.menu.documentation;

## Command Line Options

&kdict; can be started directly from a terminal like &konsole; or xterm. Several command line options are available.

`kdict` `word/phrase`

  lookup the given text. You will have to put the phrase into double quotes, if the phrase contains more than one word. For example: `kdict "double quote"`

`kdict` `-c / --clipboard`

  define the current content of the clipboard.

`kdict` `-v / --version`

  Displays the version number of &kdict; (and that of &Qt;/&kde;).

`kdict` `--license`

  Shows under which licenses &kdict; is being published.

&kdict; also supports all other command line options common to &kde; and &Qt; programs. You can get a list of these options with ``--help``, ``--help-kde`` and ``--help-qt``

## Credits and License

&kdict; - The &kde; Dictionary Client

Copyright (c) 1999-2001, Christian Gebauer

Copyright (c) 1998, Matthias Hölzer-Klüpfel

&kdict; was originally written in 1998 by Matthias Hölzer-Klüpfel hoelzer@kde.org. Currently it is maintained by Christian Gebauer gebauer@kde.org.

&underFDL; &underArtisticLicense;

## Installation

### How to obtain &kdict;

&install.intro.documentation; &install.compile.documentation;

### Requirements

Besides a working &kde; installation &kdict; requires the posix threads library which is available on all modern unices.

## Mini-Howto: Installing a local DICT server

### Obtaining and installing `dictd`

At first the `dictd` daemon has to be installed. The easiest way to install `dictd` is using a precompiled package. Such a package is included both in Debian and SuSE &Linux;. You can find packages that should work on all RPM based &Linux; distributions on rpmfind.net.

If you want to compile `dictd` yourself, download ftp://ftp.dict.org/pub/dict/dictd-1.9.1.tar.gz. Compilation is easy, just unpack the archive and run ``./configure``, ``make`` and ``make` `install`` in the `dictd` folder. You might want to use the `--prefix` option of the configure script to install `dictd` in a different folder. By default `dictd` will be installed in `/usr/local`.

### Obtaining databases

Now you need to download some databases. The standard set (webster, wordnet, jargon file, foldoc, ...) that is present on the DICT server of dict.org, is available from ftp://ftp.dict.org/pub/dict/pre/. These are also available as Debian and rpm packages.

#### Additional preformatted databases

www.freedict.de

  Translating dictionaries for Africaans, Czech, Danish, English, French, German, Greek, Hungarian, Irish, Italian, Japanese, Latin, Nederlands (Dutch), Portuguese, Russian, Serbo-Croatian, Swedish, Slovak, Spanish, Swahili, Swedish, Turkish and Welsh

http://www.wh9.tu-dresden.de/~heinrich/dict/

  Translating dictionaries for English, French, German, Italian, Latin, Portugue and Spanish.

http://purl.oclc.org/NET/voko/revodict.tgz

  Esperanto dictionary

http://www.bainsware.com/downloads/obi-bio.tar.gz

  OBI's Online Biographical Dictionary

http://www.bainsware.com/downloads/inaug.tar.gz

  The Inaugural Addresses of all the US presidents

You can find more databases on the link page of www.dict.org, but the majority of them are not formatted for `dictd`.

Each database consists of two files: The `*.index` file contains the index and the `*.dict.dz` file the actual data. Unpack all packages into a folder of your choice, for example `/usr/share/dict/`.

### Configuration

You have to create/modify two configuration files. Both are stored in `/usr/local/etc` if you used the default installation prefix (`/usr/local`).

`dict.conf` belongs to the basic `dict` client. It contains only one line: `server localhost`. This tells `dict` to use the local server.

`dictd.conf` configures the server. First you must add the access statement: `access {allow localhost deny *}`.

This example grants only local access and blocks all external connections. You can use more than one allow and deny rule, for example:

    access {allow localhost allow *.workgroup deny
    *}

The database statement configures the location of the index and the data file for a database:

        database web1913   { data "/usr/share/dict/web1913.dict.dz"
                             index "/usr/share/dict/web1913.index" }

You must add a statement for each database you want to use.

Now you should be able to start `dictd` and to use it with `dict` and &kdict;.

Please consult the man page of `dictd` for a complete description of `dictd.conf`.

### Starting `dictd` automatically

If you want to use the `dict` server frequently, you might want to start it automatically during the startup process of your system. Some of the precomplied packages install a suitable script, but you can also adapt the generic SYSV style script included in the source distribution: ftp://ftp.dict.org/pub/dict/INITSCRIPT.

&documentation.index;