# &app; Manual V&manrevision;

2003
2004
2005
2006
2007
2008
2009
2010
Hu Zheng
GNOME Documentation Project
&legal; Hu Zheng GNOME Documentation Project

     huzheng001@gmail.com

Will Robinson Stanford University

     wsr23@stanford.edu

Cleaning up English Новица Наков Слободен софтвер Македонија

     acivon@mail.com.mk

Македонски превод Ruud Slaats Eurotech Group

     ruudslaats@eurotechgroup.nl

Nederlandse vertaling Александр Мурыгин AITOC

     murygin@aitoc.com

Русский перевод Сергій Дубик ЛНБ

     dubyk@library.lviv.ua

український переклад

&app; Manual V2.4.2
Nov 2003

Hu Zheng

GNOME Documentation Project

&app; Manual V3.0.2
Jan 2011
This manual describes version &appversion; of &app;.

## Feedback

To report a bug or make a suggestion regarding the &app_t; application or this manual, follow the directions in the GNOME Feedback Page.

User manual for the &app; dictionary.

## Introduction

&app_t; is a Cross-Platform and international dictionary written in Gtk2. It has powerful features such as "Glob-style pattern matching," "Scan selected word," "Fuzzy query," etc.

## Getting Started

### Starting &app_t;

You can start &app_t; in the following ways:

Applications menu

  Choose Accessories StarDict.

Command line

  Type `stardict`, then press Return.

  You can specify a word to query too:

  `stardict word`

  or a Glob-style pattern matching string:

  `stardict wo?d*`

  or do a fuzzy query:

  `stardict /word`

If &app_t; is already running. In &winedition; &app_t; activates the first instance of &app_t;, then terminates. In &gnomeedition; &app_t; actives the first instance of &app_t;, queries the word in that instance if one was supplied on the command line, then terminates.

See for complete description of command line options.

### &app_t; Main window

When you start &app_t;, the following window appears.

#### &app_t; Main Window

Shows &app_t; main window. Contains Search field, Tool buttons, Word list, Definition area and Setting buttons.

The &app_t; Main window consists of the following elements:

Top bar

  The top bar consists of the Search field and a number of buttons. Here they are in the order from left to right.

  Clear

    Clears the Search field.

  Search field

    Use the Search field to enter the word that you want to look up. You can also access recently-queried words through the dropdown box.

  Fuzzy Query

    Fuzzy queries the word entered into the Search field.

  Go Back

    Go back to the word you queried before. Right-click to see a list of words you queried earlier.

  Main menu

    A button on the right end of the Top bar. It pops up the &app_t; Main menu.

Left bar

  The Left bar contains a number of buttons, here they are in the order from top to bottom:

  Word list

    Opens a list words that have been found in search.

  Results list

    Opens a list of sources, mainly dictionaries, where the current word has been found. The Definition area combines results from all the sources. Clicking a source in the list scrolls the Definition area window to the definition from that source.

  Full-Text Translation

    Switches to the Full-text translation mode that allows to translate blocks of text, see .

  Dictionary groups

    Shows a pop-up menu that allows to select a group of dictionaries where to search words. The menu also contains a checkbox to enable network dictionaries.

  Previous word and Next word

    These buttons are at the bottom part of the Left bar. They work with the Word list and allow to switch to previous and next words in the Word list.

Bottom bar

  The left part of the bar in the order from left to right:

  Scan selection checkbox

    Enable and disables the Scan mode. Checking the Scan selection check button will cause &app_t; to automatically look up words that you highlight in any application. See for more details about the Scan mode.

  Info

    Shows an introduction to using &app_t; in the Definition area.

  Quit

    Quits &app_t;.

  The right part of the bar in the order from left to right:

  Internet search

    Click the button to initiate Internet search. By default, the first website is used, but you may select any configured website right-clicking the button. &app_t; queries the word in the Search field sending a GET request to the configured web page. Result are shown in a web browser. To configure the list of websites see .

  &app; project website

    Opens &app_t; project website in a web browser.

  Manage dictionaries

    Opens Manage dictionaries dialog that allows to configure dictionaries to use, organize them in groups and more.

  Preferences

    Opens the Preferences dialog that allows to configuration a multitude of parameters pertaining to &app_t;. See .

Word list

  The smallest half of the &app_t; Main window on the left. It contains a list of words that have been found in search. Click a word to show the related articles in the Definition area. You may use a spliter in the middle of the &app_t; Main window to divide the space between the Word list and the Definition area.

Definition area

  The largest half of the &app_t; Main window on the right. &app_t; displays definition of a word in this area of the window. You may use a spliter in the middle of the &app; main window to divide the space between the Word list and the Definition area. The Definition area has its own bars: a top toolbar (see ) and a bottom search bar (only visible when you search in the Definition area).

The following hotkeys are available in the Main window.

#### Hotkeys

middle mouse button

  This hotkey applies to the Definition area only.

  Query the text selected in the Definition area into the Main window. In &winedition; of &app_t;, if there is no selected text, query clipboard content into the Main window.

right mouse button

  Show pop-up menu.

### Definition area toolbar

The Definition area toolbar is at the top of the Definition area. It contains a number of buttons. Here they are in the left-to-right order.

Hide(Show) the Word list

  Hide or show the Word list or the Results list, depending on what is active now.

Copy

  Copy the Definition area text into clipboard, all the text.

Pronounce the word

  This is a button with an additional dropdown menu. Clicking the button you make &app_t; pronounce the current word using the first TTS engine that can do that. The dropdown menu allows you to select the TTS engine to use.

  #### TTS engines

  Real People TTS

    This engine use sound samples performed by real people.

  Espeak TTS

    Espeak TTS plugin.

  Festival TTS

    Festival TTS plugin.

  Command TTS

    TTS command you may specify in the Preferences dialog. See .

  Depending on configuration settings, installed plugins and other factors, the list of TTS engines may be shorter.

Save to file

  Save Definition area text into a file. The new text is appended to the end of the file. The file to use is specified in the section of the Preferences dialog. You may also specify to export only the found word, not its definition. &app_t; exports not the word you searched for but the word that was found, the one which translation is shown in the Definition area. When "export only word" is not specified, selection is taken into account. When text is selected in the Definition area, the selected text is exported prepended with the found word. When there are no selected text, all text of the Definition area is exported.

  Hotkey: Alt e

Search in the Definition text

  Search for text in the Definition area. This button opens the Definitiona area Search bar at the bottom of the Definition area where you may type a word to search.

  Hotkey: Ctrl f

### Notification area icon

&app_t; will also add an icon to the Notification area. When you iconify the Main window, the window will be hiden. After you click the icon, the window will be shown again. If you right click this icon, it will popup a menu where you can choose to toggle Scan selection, or to Quit. You can toggle Scan selection directly by ctrl-clicking the icon. Clicking the middle mouse button on the icon will query the selected word.

#### &app_t;'s notification area icon

&app_t;'s notification area icon.

### Scan selection

&app_t; can automatically scan selections. This means that when you select a word or phrase in &app_t; or in any other application, &app_t; will get the text that you selected and search for it, then display the Floating window containing the result of the search.

In Windows the Scan mode works differently. It has nothing to do with selection in fact. &app_t; extracts the text under the pointer when you pause the mouse for a while. Normally &app_t; looks up a word under the pointer, if the pointer is not over a word, then words to the left and the right of the pointer are considered. It is time to say what &app_t; considers as a word. &app_t; gives a number of tries. First, it considers a word may include anything but spaces and punctuations; second, a word consisting of only letters; a word of lower case letters; a word of upper case letters; a capitalized word of letters. Finally, &app_t; uses one of the tried word to find the longest prefix making a word. You may help &app_t; to extract the right word or a part of a word selecting it. Although &app_t; does not work with selections, selection may effect the text &app_t; gets.

Scanning in Windows may not work with some applications. For example, it's known that scanning does not work with FireFox 3.x and Windows Console (cmd.exe process). The scanning feature depends on the way application outputs text. If scanning does not work, you may harness another &app_t; feature &mdash; Clipboard scanning, see .

In Windows &app_t; works specially with some applications. First, &app_t; itself. To scan a word in &app_t; Main window you need to select it. The Scan mode in &app_t; Main window works exactly as it should in general case, the fact that it's Windows does not matter. You can not scan in other &app_t; windows however.

Second, there is special plugin to scan in PDF documents, see .

#### &app_t; Floating Window

Shows &app_t; the Floating window. Contains Tool buttons and Definition area.

#### Usage tips

- You may drag the Floating window to move it.

- The Floating window will disappear when you move your pointer some distance away.

- You may configure &app_t; so it will do scanning only when a special modifier key is held down. See .

- You may switch the Scan mode on and off by pressing the Ctrl Alt x shortcut. See .

- &app_t; remembers the last text looked up in the Floating window and will not lookup it again. If you need to see the translation again, you should lookup another word first (it's not enough to simply change selection) and then lookup the original word. Another possibility is to middle-click on the Notification area icon, &app_t; will lookup the selection unconditionally.

The &app_t; Floating window consists of the following elements:

Tool buttons bar

  A bar at the top of the Floating window. The bar will be hidden automatically to save display space. When your mouse pointer enters the Floating window, the Tool buttons bar will appear immediately, and disappear again as the mouse pointer leaves.

  You can click these buttons to query a word in the Main window, copy the query result to clipboard, pronounce the word, stop selection scanning, etc. To the far right is the Lock floating window button. If the Floating window is locked, it will always be shown there.

Definition area

  The query result is displayed in this area.

### WordPick Adobe Acrobat plugin

&app_t; includes an Abode Acrobat plugin that can be used to extract and translate text from Portable Document Format (PDF) documents. The WordPick plugin is available in &winedition; of &app_t; only. The main text extration mechanism does not work with PDF documents in Windows.

#### Limitations

WordPick plugin requires non-free edition of Acrobat like Acrobat Stardard, Pro or richer, it does not work with the free Acrobat Reader product. The plugin is know to work with versions 7-9 of Acrobat. PDF document security restrictions must allow extracting document content.

WordPick plugin embeds an icon into the stardard Acrobat toolbar near the Hand Tool. In Acrobat Reader you will not see that icon &mdash; plugin is not available. If the current document does not allow for text extraction, the icon is disabled, the plugin is not operational.

#### Adobe Acrobat Toolbar with WordPick plugin icon

Shows Adobe Acrobat Toolbar with WordPick plugin icon.

#### How to inspect document security permissions

In the main menu open File, Document properties. Document properties dialog pops up. Proceed to Security tab. Look into Document Restrictions Summary group. Content Copying or Extraction must be allowed.

#### Translate text with WordPick plugin

1. Select WordPick and Select tools. Cursor changes to a vertical bar. Now you can select text with mouse.

2. Start &app_t; if you have not already done that, and enable Scan mode.

3. Select a word in the PDF document, &app_t; shows the Floating window with translation if the word is found.

You may select consecutive words and phrases. If &app_t; is unable to find the phrase, it tries to cut words from the end. You will be shown translation of the first word if nothing else has been found.

Note that the Scan modifier key () has no effect in Acrobat. WordPick search for text when you select something in the document regardless of the state of modifiers. To turn off the text translation mode, deselect the WordPick tool on the toolbar, deselecting the Select tool is not necessary.

### Full-Text Translation

&app_t; provides full-text translation service. It allows you to translate short texts with up to 2000 characters approximately. The exact limit depends on the translation engine and other factors. To switch to Full-Text Translation mode click the Full-Text Translation button on the Left bar in &app_t; Main window.

&app_t; uses online translation services available for free on the Web to perform translation. &app_t; collects text, source and target languages, constructs an HTTP request and sends it to online translation service. The application receives response of the service and shows results in a window. You may see &app_t; interface to Full-Text Translation service below.

#### Full-Text Translation Mode

Shows &app_t; in Full-Text Translation mode.

The top line of the window from left to right contains: engine selection combobox, source language combobox, and target language combobox. Below you see a text area for the text to translate. The bottom part of the window contains a text area for translation results. The Translate button in the middle of the window initiates translation request. The bottom line of the window provides a link to the online translation engine. It opens in a web browser.

To translate something, first select a translation engine. You have the following choice: Google, Yahoo, Excite Japan. Select source and target languages. Available source and target languages depend on selected engine. Available target languages depend on source language as well. Type the text to translate into the source text area. Click the Translate button to start translation. You'll see results in the result text area. Sometimes it may show you Not found! text. It means that translation failed. There can be a number of reasons: source text is too long, the online service is down, the service has changed output format and &app_t; is unable to parse it. You may see other errors in the results area.

## Usage

### Looking Up a Word

To look up the definition of a word, perform the following steps:

1. Type the word that you want to look up in the Search field.

2. &app_t; will show the definition immediately. If not found, you can press Return to do a fuzzy query or just click the Fuzzy query button.

3. Use the scrollbar to scroll through the definition. Select the words in the Word list to view the related words.

### Clearing the Display Area

To clear the text of the Search field, click the Clear button on the left, or just press Alt-C or ESC.

### To Copy Text to Another Application

There are two ways to copy the text in the Definition area to another application:

- To copy all of the text, click the Copy button by the top of the Definition area.

- To copy some of the text, select the text that you want to copy, then click your mouse's right button and choose Copy.

### To Find Text in the Definition Area

To find text in the Definition area, perform the following steps:

1. click the Find button by the top of the Definition area.

2. Type the string that you want to find in the Find text box, then press Return. You cannot use wildcards.

3. To find the next occurrence of the word, press Return again.

### Scanning: operation guide

- Scenarios below assume that you make selection with mouse.

- Scan key is the modifier set by the "Scan modifier key" option, see .

#### Scanning in Linux and Unix

##### Case 1. "Only scan while modifier key is being pressed" option is off

1. Select text to translate.

2. Wait for a few seconds. The Floating Window pops up.

##### Case 2. "Only scan while modifier key is being pressed" option is on

1. Press and hold the Scan key.

2. Select the text.

3. Wait for a few seconds. The Floating Window pops up.

4. Release the Scan key.

##### Case 2.1. "Only scan while modifier key is being pressed" option is on. A variation

1. Select the text and do not release the mouse button yet.

2. Press and hold the Scan key.

3. Release the mouse button.

4. Wait for a few seconds. The Floating Window pops up.

5. Release the Scan key.

Selection is made when you release mouse button. This is the time when the Scan key must be pressed down. It takes some time for StarDict to inspect selection, you must hold the Scan key all this time. What is why you need to hold the key for a few seconds after selection.

#### Scanning in Windows

##### Case 1. "Only scan while modifier key is being pressed" option is off

1. Place the mouse pointer over the word you want to traslate.

2. Do not move the mouse for a few seconds. The Floating Window pops up.

##### Case 2. "Only scan while modifier key is being pressed" option is on

1. Place the mouse pointer over the word you want to traslate.

2. Press and hold the Scan key.

3. Do not move the mouse for a few seconds. The Floating Window pops up.

4. Release the Scan key.

For scanning in PDF documents see .

### Toggle Scan Mode

There are a number of ways to enable or disable the Scan selection mode. When in Scan mode, &app_t; shows translation of the text you select in different windows. See .

#### Ways to enable the Scan mode

- Toggle the Scan selection checkbox at the bottom left corner of the &app_t; Main window.

- Right-click the Notification area icon and check Scan in the pop-up menu.

- Press Ctrl Alt x shortcut (it toggles the Scan mode). To configure the shortcut see .

### Main window hotkeys

Ctrl q

  Quit &app_t;.

Alt x

  Minimize to tray. &app_t; Main window is closed, taskbar item disappears, but the application continues to run. You may open the Main window again clicking on the Notification area icon.

Alt z

  Iconify the application. The Main window is hidden, the taskbar item remains.

Alt e

  Save word definition to a file. See for more details.

F1

  Show help.

Ctrl f

  Search in the Definition area. See for more details.

Alt Left

  Go Back. Return to the word that was queried before.

Alt Up

  Previous word. Query the previous word in the Word index.

Alt Down

  Next word. Query the next word in the Word index.

Alt m

  Menu. Show the Main menu.

Ctrl v

  Query clipboard text in &app_t;.

Ctrl u

  Clear the Search field and focus it.

BackSpace

  The same as Ctrl u.

Enter

  1. The focus is in the Word list.

     If the selected index item has children, expand or collapse the item. If the selected index item has no children, query the item in the main window.

  2. The focus is in the Definition area.

     Requery the text in the Search field.

Space

  Focus the Search field.

Escape

  1. The focus is in Definition area Search bar.

     Hide the search bar.

  2. Otherwise, this hotkey has the same effect as Ctrl u.

Ctrl Alt z

  Open the Main window of &app_t;. The Main window may be iconified, or &app_t; may only exist as a Notification area icon. In all the cases pressing this hotkey presents the Main window to the user. You may change the hotkey in the Preferences dialog, see .

Ctrl Alt x

  Toggle the Scan mode. You may change the hotkey in the Preferences dialog, see .

### Installing new dictionaries

Dictionaries for &app_t; you download are normally packed in archives. You must unpack them and copy into one of the &app_t; dictionary directories. If you simply copy an archive file into the dictionary directory, &app_t; will not find the dictionary. It is recommended to place each dictionary in its own directory. You may build a hierarchy of directories to organize your dictionary collection. &app_t; search directories recursively. See also .

#### Installing a dictionary

1. Download a dictionary. Normally a dictionary is packed in an archive file, for example, `WineEnRu.zip`.

2. Unpack the archive in a new directory. You may name the directory after the archive name, though that is not required.

       WineEnRu/WineEnRu.dict
       WineEnRu/WineEnRu.idx
       WineEnRu/WineEnRu.ifo

3. Copy the dictionary directory into one of &app_t; dictionary directories, see .

4. Restart &app_t;. The new dictionary will be added into the default dictionary group.

#### Broken dictionaries

Some dictionaries you may find on Internet violate restrictions of &app_t; dictionary file format. Using such a dictionary may result in &app_t; crash. If &app_t; becomes unstable, check your dictionaries, especially new ones, with &app; Editor or stardict-verify command line tool.

### Removing dictionaries

To remove a dictionary it's enough to remove all files belonging to that dictionary. All files of a dictionary share the same base name, for example.

    WineEnRu.dict
    WineEnRu.idx
    WineEnRu.idx.oft
    WineEnRu.ifo

Some dictionaries may include resource database that is named differently. For complete list of file see . If you follow the rule "one dictionary &mdash; one directory", removing a dictionary will be easer.

#### Removing a dictionary

1. Quit &app_t;. Make sure that &app_t; has really terminated, not just minimized into tray icon!

2. Remove dictionary files.

## Preferences

To configure &app_t;, click the Preferences button at the right-bottom corner of the Main window or click the Main menu button and choose Preferences.

### Dictionary

#### Scan Selection

Only scan while modifier key is being pressed.

  Only do scanning while the modifier key being pressed. The modifier key is set by the option.

  Default: FALSE.

Hide floating window when modifier key released.

  When this option is set, the Floating window is hidden when user releases the modifier key. Note: the window is hidden only if the pointer has the same position it had when the window was shown. In addition to hiding the window, the last selected text is forgotten, which allow you to lookup the same text again simply pressing the modifier key. When this option is not set, releasing the modifier key has no effect on the Floating window.

  This option has effect only if is checked.

  Default: TRUE.

Scan modifier key

  This option allows to choose a modifier keys or a key combination that enables scanning.

  This option has effect only if is checked.

  Default key: Win (depends on &app_t; edition).

Scan clipboard.

  Enables Clipboard scanning. If enabled, when new text is copied into the clipboard, &app_t; lookup the text into the Floating window.

  This option is only available in &winedition; of &app_t;.

  Default: FALSE.

Scan mode shortcut

  The Scan mode shortcut enables or disables the Scan mode. Check the Use scan hotkey checkbox to enable this shortcut. You may change the shortcut in the field to the right of the label. Click inside the field and press the key combination you want to assign to this action.

  Default: TRUE

  Default shortcut: Ctrl Alt x.

#### Font

Use custom font.

  Allows you to override the system's default for &app_t;. If this option is turned on, the font selelected in the Dictionary font option will be used instead of the system font.

  Font settings apply immediately.

  Default: FALSE.

#### Cache

Create cache files to speed up loading.

  Opening a dictionary the first time, &app_t; does some calculations to access dictionary contents speedily. &app_t; may save the results in special cache files that will be used the next time &app_t; starts. With cache files &app_t; starts quicker, since it does not need to do the same calculations again. It's highly recommended to enable caching. In the first place, &app_t; tries to save a cache file along with the dictionary. If it fails, for example, because the directory is write-protected, &app_t; creates a file under the user home directory, in &app_t;'s directory.

  Default: TRUE.

Sort word list by collation function.

  Normally, &app_t; uses an index of words to look up a word in a dictionary. When the word is present in the index, the corresponding article is shown. Otherwise adjacent words will be checked and may be used as result. &app_t; uses heuristic algorithms to decide whether the particular word may be suggested as result of the search or not. The order of words in an index is very important and it would be handy if index items were sorted by alphabet or according to other rules. Collation functions allows you to specify a number of predefined sorting orders, that may be helpful when working with particular languages.

  To use a collation function check the Sort word list by collation function checkbox and select the desired function from the Collation function list. The collation function will be applied as soon as you close the Preferences dialog. It may take a considerable amount of time to apply the new collation function, please, be patient.

  It's highly recommended to enable the option, otherwise &app_t; will do sorting each time the application starts.

  Default: FALSE.

Clean all cache files

  Remove all &app_t; cache files.

#### Export

&app_t; may export search results into a file. You have two options: export only the found word or export the entire search result, the contents of the Definition area.

Only export words.

  When this option is set, &app_t; exports only the found word, otherwise exports the complete article.

  Default: TRUE.

File name

  Name of the file where to export data.

#### Sound

There are a number of cases when &app_t; needs to play sound files. &app_t; may accompany GUI actions with sounds. &app_t; may pronounce the words you search in the dictionary. Some articles may contain linked sound files you can play.

To play sound files &app_t; may harness platform-specific services or use commands you specify on this page.

This page allows to configure some aspects of the TTS subsystem. The TTS subsystem is used to pronounce words by computer.

Enable sound event.

  Whether to enable sound events. &app_t; will play sound event when button is active, released, and when a menu pops up.

  Default: TRUE.

Command for playing sound files:

  Specifies a command for playing sound files. You may specify a program name (with or without full path) accompaned with any options required. The file name to play will be appended to this command at run time.

Always use sound play command

  On some platforms &app_t; use platform-specific services to play sound files first, then retreats to the custom command provided by the user if the service is unable to play the file. You may specify to always use the custom command selecting this option.

  Default: FALSE.

RealPeopleTTS search path:

  Allows to specify locations of RealPeopleTTS bundles. RealPeopleTTS bundle is a collection of sound files containing speech samples performed by real people. Normally, one file contains one recoded word, the file is named after that word. Sound files are organized into a number of directories. In the text field you must specify a path to the top level directory of the bundle. The order of paths in the text field is important. &app_t; checks directories from top to bottom, the first found file will be used.

  ##### Default:

  In &winedition; of &app_t;

    `C:\Program Files\WyabdcRealPeopleTTS`, `C:\Program Files\OtdRealPeopleTTS`, `WyabdcRealPeopleTTS`, `OtdRealPeopleTTS`

  In other editions of &app_t;

    `/usr/share/WyabdcRealPeopleTTS`, `/usr/share/OtdRealPeopleTTS`

Enable TTS program.

  Allows to use the command below to read words. You need to restart &app_t; for changes to take effect.

  Default: FALSE.

TTS Command line:

  This field allows to specify a command to use to pronounce words. You need to provide a print-like string, with "%s" specifing the place where the word (or phrase) to pronounce will be inserted. You need to restart &app_t; for changes to take effect. Do not forget to check the checkbox above if you want to use this command.

  Default: nothing.

#### Video

Command for playing video files:

  Specifies a command for playing video files. You may specify a program name (with or without full path) accompaned with any options required. The file name to play will be appended to this command at run time. Video files may be linked with dictionary articles.

#### Article rendering

Highlight search term

  Whether to highlight the search term in the Definition area. A search term is a word that was found in dictionaries, a head word of an article.

  Default: FALSE.

### Network

#### Net Dict

&app_t; may look up words in network dictionaries using a custom &app_t; network protocol. This configuration page allows you to register an account, select a server to use, and specify other related parameters.

Enable network dictionaries

  Enables to use network dictionaries. You need to specify the dictionaries to use in the Manage Dictionaries dialog if you enable this option.

  Default: TRUE.

#### Web browser

&app_t; may need to open a web link to start Internet search, show &app_t; project website, show a web page to download new dictionaries, new version of the application and for other reasons. This configuration page allows to specify how a web link should be opened.

Command for opening URLs

  This option allows you to specify a command to use for opening URLs. Some editions of &app_t; use platform-specific services for opening URLs by default. To use the custom command you need to check the checkbox below. For other editions of &app_t; the custom command is the only way to open a web link.

  You may specify a program name (with or without full path) accompaned with any options required. The URL to open will be appended to this command at run time.

  Default: `firefox` (depends on edition).

Always use this command for opening URLs.

  This option is only available in editions of &app_t; that can use other ways to open a web link.

  Check this option to use the custom command to open web links instead of platform-specific services.

  Default: FALSE.

### Main Window

#### Input

Search while typing

  When this option is checked, &app_t; search for the word you are typing in the search field automatically. &app_t; monitors key-press events, it starts searching the word entered as soon as there is no activity for more than a specified amount of time. The time span can be changed in the field below.

  When this option is not checked, you need to press Enter in order for &app_t; to start searching the word.

  Default: TRUE

Word change timeout

  A word change timeout in milliseconds. See the option above for details.

  Default: 300 ms

Show the first word when not found.

  When &app_t; is unable to find the exact word requested, the application may propose another word that is close to the original. When this option is checked, the closest word will be shown in the Definition area, otherwise, &app_t; tells that the original word is not found. Note, that this option applies to simple queries only, that is the queries that do not use regular expressions, patterns, fuzzy matchs and so on.

  Default: TRUE

#### Options

Skin

  Allows to customize graphical appearance of the application. Select the Default item to restore the original appearance of &app_t;, no skins applied. You need to restart the application in order for changes to take effect. For instructions on how to prepare a custom skin see the `doc/Skins` file in &app_t; sources.

  Default: Default.

Hide main window when starting StarDict.

  Controls whether the Main window appears when you first start the program. If you select this option, you will only see the Notification area icon after starting &app_t;. You may still get to the Main window by clicking on this icon.

  Default: FALSE.

Use open main window hotkey

  This option enable the hotkey that opens the Main window, and allows to change that hotkey. When enabled, when user presses the hotkey, the Main window is presented to the user.

  Default: TRUE.

  Default hotkey: Ctrl Alt z

Transparency

  Allows to make the Main window transparent. Moving the slider you may change transparency degree. Transparency is measured in percents, it can range from 0 to 80, where 0 &mdash; fully opaque, 80 &mdash; almost fully transparent. Moving the slider has an immediate effect on the window.

  On X11 this has any effect only on X screens with a compositing manager running. On Windows it should work always.

  Default: 0 &mdash; fully opaque.

#### Search website

&app_t; may use Web search engines, Web dictionaries, databases providing web-based interface and other web sites providing information by request. The text to search is incorporated into URL. Normally, the text is assigned to a GET request parameter. For example, to search for word stardict in Google search engine you may use the following URL `http://www.google.com/search?q=stardict`. You can search websites in &app_t; right-clicking the Internet search button in the Main window.

&app_t; does not handle the web request itself, it only composes a URL and invokes an external program like a web browser or use platform-specific services to open the URL.

On this page you may see a list of websites. Use Add and Remove buttons to add new sites and remove existing records. Use Up and Down arrow buttons to reorder records in the list. Each record consists of three items:

##### Website record

Website name

  This is a label you see in menu. Use a meaningful name.

Website link

  Link to the main page of the website. This link is opened when there is nothing to search for, the Search field is empty.

Website search link

  Link to perform request. %s identifies the place where to insert the search text. For example, `http://www.google.com/search?q=%s`.

### Notification area icon

#### Options

When middle mouse button is clicked:

  Specifies an action to perform when user clicks the middle mouse button on the Notification area icon. There are the following choices:

  - Query selection in floating window

  - Query selection in main window

  - Do nothing

  In the Do nothing case &app_t; simply ignores middle button clicks, otherwise &app_t; get text of the current selection, search for it and displays the results either in the Floating window or in the Main window.

  In case there are a number of windows on desktop having text selected, there might be a confusion what text will be used. &app_t; works with the X Primary selection. Only one application can own a selection at a time, so when you select something in an application that application becomes the selection owner, the previous owner loses selection ownership. Now back to the question. &app_t; will use the text that was selected last.

  Default: Query selection in floating window.

### Floating Window

#### Options

Pronounce the word when it pops up.

  When set, pronounce the word when the Floating window shows translation.

  Default: FALSE.

Show floating window if word not found.

  This option allows to configure what to do if the word to be shown in the Floating window is not found. You have two choices: 1) do not show the Floating window at all &mdash; this option is unset, 2) show the Floating window with text indicating that the word was not found &mdash; this option is set.

  Default: TRUE.

#### Settings

Max window width.

  Sets the Floating window's max width.

  Default: 320.

Max window height.

  Sets the Floating window's max height.

  Default: 240.

Use custom background color:

  Enables to use custom color for background in the Floating window and select that color.

  Default: FALSE.

Transparency

  Allows to make the Floating window transparent. Moving the slider you may change transparency degree. Transparency is measured in percents, it can range from 0 to 80, where 0 &mdash; fully opaque, 80 &mdash; almost fully transparent. Moving the slider has an immediate effect on the window.

  On X11 this has any effect only on X screens with a compositing manager running. On Windows it should work always.

  Default: 0 &mdash; fully opaque.

## Details

### Command line options

&app_t; usage:

`stardict options query_word`

query_word

  With query_word you request &app_t; to look up the specified word just after startup. It has the same effect as if you had typed that word in the Search field. You may use pattens, fuzzy query and other supported modes.

-m, --message-level=integer

  This option specifies the minimum severity level of message that should be printed on console. The value may range from 0 to 6, where 0 means to suppress all output, 6 &mdash; print all produced messages, including debug ones. Default value is 4 which passes informational messages, like what dictionaries are loaded during startup.

-l, --log-level=integer

  This option specifies the minimum severity level of message that should be logged. The value may range from 0 to 6, where 0 means to suppress all output, 6 &mdash; print all produced messages, including debug ones. Default value is 0, that is log file is not used. See for details about &app_t; log.

-h, --hide

  Do not show splash screen during startup and hide the Main window. Only notification area icon will be visible.

-n, --new

  Start a new instance of &app_t;. By default &app_t; checks if the application is already running and prevents starting the second instance.

  This option is only available in &winedition; and &gnomeedition; of &app_t;.

-q, --quit

  Quit an existing instance of &app_t;.

  This option is only available in &gnomeedition; of &app_t;.

--dirs-config

  Specifies path to the &app_t; directory configuration file. See for details about &app_t; directories and configuration file.

  This option is only available in &winedition; of &app_t;.

--portable-mode

  Activate portable mode, see . Specifying the option is not enough to make &app_t; to be &app_port_t;. You should avoid using this option unless you know what you are doing.

  This option is only available in &winedition; of &app_t;.

### Dictionary Management

To manage the dictionaries, click the Manage dictionaries button at the bottom-right corner of the Main window, or click the Main menu button and choose Dict manage.

In the dictionary management dialog, you can disable dictionaries that you don't need, and you can set the order in which the dictonaries are queried.

&app_t; will search the dictionary files at "~/.stardict/dic" and "/usr/share/stardict/dic", and search tree dictionary files at "~/.stardict/treedict" and "/usr/share/stardict/treedict"

### Help

Inside &app_t; you may open documentation either by pressing the F1 key or by clicking the Main menu button, then the Help item in the popup menu. &app_t; documentation has different formats depending on application edition. The primary documentation format is DocBook. &app_t; installs documentation in DocBook format only in Gnome edition. In this edition documentation seamlessly integrates with Gnome documentation system. It can be read through Help Browser. Documentation was translated into a number of languages. You are presented with localized version if it's available. Gnome allows to configure the prefered language.

In other editions of &app_t; documentation is available in html format. You need to configure Web browser to view documentation, see . Choosing documentation language, &app_t; roughly follows gettext package locale selection algorithm. The LANGUAGE enviroment variable is checked first. It's expected to contain a list of language codes in the order of preference. If the LANGUAGE variable is not set, the current locale is inspected. Finally, if documentation in prefered languages is not available, the english documentation is shown.

In &winedition; of &app_t; the default language corresponds to the language selected in the Regional and Language Options dialog.

#### Changing default language

Open Control Panel, Regional and Language Options. Regional and Language Options dialog pops up. On the Regional Options tab select a language in the Stardards and formats group.

You may override the default language with the LANGUAGE environment variable.

Normally, help files can be found in the `C:\Program Files\StarDict\help` directory. Each directory corresponds to one language. Directories are named after language codes.

### &app; directories

&app_t; uses a number of directories to store application data, load and save configuration settings. Default directories are assigned at build time, but some of them can be overriden with `stardict-dirs.cfg` file. Overriding &app; directories is useful for debugging, preparing special configurations like &app;-portable for Windows, an ordinary user does not need this.

&app_t; searches for the `stardict-dirs.cfg` file in the `user_config_dir` directory. You may override location of the `stardict-dirs.cfg` file with `STARDICT_DIRS_CONFIG_FILE` environment variable or with `--dirs-config` command line option. Command line option takes the highest precedence, then the environment variable is inspected, and finally the file in the `user_config_dir` directory. The first specified file wins, it will be probed as a configuration file. If load fails, no other files will be tried.

The `stardict-dirs.cfg` file is a .ini-like config file. The syntax of .ini files is described in detail in the Desktop Entry Specification. All keys must belong to general group.

Do not forget to double backslash characters in values. Backslash is used as path separator in Windows.

Example of `stardict-dirs.cfg` file for Windows:

    [general]
    data_dir=C:\\Program Files\\StarDict
    dll_dir=C:\\StarDict\\msvc_2008\\Debug
    plugin_dir=C:\\StarDict\\msvc_2008\\Debug

#### &app; directories

user_config_dir

  A directory of configuration files.

  Windows default: `C:\Documents and Settings\%USERNAME%\Application Data\StarDict`.

  Other default: `~/.stardict`.

  Environment variable: `STARDICT_CONFIG_PATH`.

  `stardict-dirs.cfg` key: user_config_dir.

user_cache_dir

  User cache directory.

  Windows default: `C:\Documents and Settings\%USERNAME%\Temporary Internet Files\stardict`.

  Other default: `~/.cache/stardict`.

  `stardict-dirs.cfg` key: user_cache_dir.

data_dir

  Data directory.

  Windows default: `C:\Program Files\StarDict`.

  Other default: `/usr/share/stardict`.

  `stardict-dirs.cfg` key: data_dir.

dll_dir

  A directory of hook dlls, in &winedition; only.

  Windows default: `data_dir`.

  `stardict-dirs.cfg` key: dll_dir.

plugin_dir

  A directory of &app; plugins.

  Windows default: `data_dir` + `"/plugins"`.

  Other default: `/usr/lib/stardict/plugins`.

  `stardict-dirs.cfg` key: plugins_dir.

help_dir

  A directory of help files, in all editions except &gnomeedition;.

  Default: `data_dir` + `"/help"`.

  `stardict-dirs.cfg` key: help_dir.

log_dir

  A directory for log files.

  Windows default: `C:\Documents and Settings\%USERNAME%\Local Settings\Temp\StarDict`.

  Other default: `/var/tmp/stardict`.

  `stardict-dirs.cfg` key: log_dir.

Default values in the list above are given for the purpose of illustrating possible values of variables. Actual default value depends on a number of factors and cannot be computed easily. See AppDirs class in the `conf.h` file for details on how the default value is calculated.

### Logging

&app_t; may log messages into a file. By default logging is turned off, you may enable it specifing non-zero log level with `--log-level` command line option, see .

By default messages are printed on to console, log file may be useful if console is not available like in Windows. Log may be useful in troubleshooting startup problems.

For default location of the log directory see , log_dir parameter. &app_t; log files are named like `stardict-process_number.log`. We need to use process numbers to create unique log files, since multiple &app_t; instances may run at the same time. To find the log file belonging to the most recently started instance of &app_t;, consider file creation time.

### Interface language

This section describes the algorithm used to select interface language in &app_t;.

1. Retrieve `STARDICTLANG` environment variable. Goto if the variable is defined.

2. Retrieve the user default locale (to set the default locale: Control Panel Regional and Language Options Regional Options Standards and formats Language ). If locale is not defined, use "en".

3. Assign the language code to the `LANG` environment variable.

4. Retrieve the value of the environment variable `LANGUAGE`. This is a GNU extension. Its value can be a colon-separated list of locale names. If defined, goto .

5. The value of the environment variable `LC_ALL`, `LC_xxx`, or `LANG`. More precisely, the first among these that is set to a non-empty value. This is how POSIX specifies it. The value is a single locale name. If defined, goto .

6. A system-dependent preference list of languages. Its value can be a colon-separated list of locale names. If defined, goto .

7. A system-dependent default locale name. If defined, goto .

8. Processes the found value as a colon-separated list of language codes. Select the first available language. If none is available, select no translation.

Steps through describe translation selection algorithm of the gettext package. The actual procedure may be different.

The best way to specify interface language of &app_t; is to define `STARDICTLANG` environment variable. It should contain language code. See `$StarDictDataDir/locale` for the list of supported languages.

### &app; dictionaries

&app_t; supports two types of dictionaries: index (normal) dictionaries and tree dictionaries. The vast majority of dictionaries for &app_t; you may find on Internet are of the index type. In fact, you hardly find a tree dictionary for &app_t;. An index dictionary contain a list of words in one file and corresponding definitions in other file. That index of words is the reason we call it an index dictionary. An index dictionary may contain other data as well. In a tree dictionary data are organized in a tree that is why it name. &app_t; searches index and tree dictionaries in different directories.

Almost all files constituting a dictionary are binary. It does not make sense to open them in a text editor. A notable exception is `.ifo` file, it contains dictionary description.

#### Index dictionary files and directories

dictname.ifo

  Information about the dictionary. This a text file, you may open it in a text editor. You may found useful information here like dictionary description, author name and e-mail.

dictname.idx or dictname.idx.gz

  Index of words available in the dictionary.

dictname.dict or dictname.dict.dz

  Main content of the dictionary &mdash; articles.

dictname.syn

  Index of synonyms. Optional.

dictname.ind.oft

  Cache for the index file. This file is created by &app_t; to speedup dictionaries loading. You should not redistribute this file.

dictname.syn.oft

  Cache for the synonyms file. This file is created by &app_t; to speedup dictionaries loading. You should not redistribute this file.

dictname.ind.clt

  Collation file for the index file. This file is created by &app_t; when you use collations to modify sorting order of words. You should not redistribute this file.

dictname.syn.clt

  Collation file for the synonyms file. This file is created by &app_t; when you use collations to modify sorting order of words. You should not redistribute this file.

res.rifo, res.ridx, res.rdic

  Files of resource database. It contains resources like images, sound and video files used in the dictionary. Optional.

res.ridx.oft

  Cache for the resource index file. This file is created by &app_t; to speedup resource database loading. You should not redistribute this file.

res

  A directory containing dictionary resources. This is alternative to `res.rifo`, `res.ridx`, `res.rdic` collection of files. Optional.

#### Tree dictionary files

dictname.ifo

  Information about the dictionary. This a text file, you may open it in a text editor. You may found useful information here like dictionary description, author name and e-mail.

dictname.tdx or dictname.tdx.gz

  A word list forming a tree.

dictname.dict or dictname.dict.dz

  Main content of the dictionary &mdash; articles.

#### Directories

This section describes directories where &app_t; searches dictionaries.

Under Unix, &app_t; searches `~/.stardict/dic` and `/usr/share/stardict/dic` directories for index dictionaries and `~/.stardict/treedict` and `/usr/share/stardict/treedict` directories for tree dictionaries. If you build &app_t; with non-standard prefix, the application searches a pair of additional directories for dictionaries. It checks ``$(datadir)`/dic` for index dictionaries and ``$(datadir)`/treedict` for tree dictionaries. Here `$(datadir)` is an autoconf directory variable.

Under Windows, &app_t; searches `C:\Program Files\StarDict\dic` for index dictionaries and `C:\Program Files\StarDict\treedict` for tree dictionaries, assuming that &app_t; was installed into `C:\Program Files\StarDict`. If you've install &app_t; into a different directory, replace `C:\Program Files\StarDict` with real installation path.

Under Windows, you may overwrite `$data_dir` variable, see . By default it matches the &app_t; installation directory. In this case &app_t; will search ``$data_dir`\dic` for index dictionaries and ``$data_dir`\treedict` for tree dictionaries.

All directories are processed recusively.

## &app_port;

&app_port_t; is special edition of &app_t; for Windows that works with any hardware you like (USB flash drive, portable hard drive, etc). Now you can carry &app_t; along with all settings with you. Use them on any Windows computer. All personal data are saved along with application.

&app_port_t; relies on the PortableApps.com Platform. It provides convenient shell to start and configure portable applications. On the screenshot below you may see PortableApps.com menu with &app_port_t; and &app; Editor portable. You may change interface language of the menu and &app_port_t;. To do that click Options Language and select the desired language.

### PortableApps.com menu

PortableApps.com menu with &app_port_t;.

### Differences from non-portable version

Functionality of &app_port_t; is almost identical to the non-portable version. Only features that ties application to the specific machine are disabled. The list below details the deferences.

#### &app_port; features

WordPick Adobe Acrobat plugin

  WordPick Adobe Acrobat plugin is disabled in portable version. Portable application policies forbids to modify the host machine.

Run &app_t; when Windows starts

  This option is disabled in portable version. It does not make sense to autostart application residing on removable storage.

### Installing &app_port;

This section describes &app_port_t; installation procedure.

1. Download and install PortableApps.com Suite on a USB flash drive or wherever you want.

2. Download &app_port_t; package from &app; website. The package file ends with `.paf.exe`, for example, `StarDictPortable-stardict.sourceforge.com_3.0.2.paf.exe`.

3. Launch PortableApps.com menu.

4. Click Options Install a New Apps . Select &app_port_t; package you've just downloaded, click OK and proceed with installer.

5. When installation completes, you will have two new items in the menu: &app_port_t; and &app; Editor portable. You are ready to use &app_port_t;.

### Launching &app_port; directly

You may use &app_port_t; without PortableApps.com menu. In the `$PortableAppsRoot\PortableApps\StarDictPortable-stardict.sourceforge.com` directory you may find two executables: `StarDictPortable.exe` and `StarDictEditorPortable.exe`, they start &app_port_t; and &app; Editor Portable respectively. `$PortableAppsRoot` here is the directory where PortableApps.com suite was installed, normally this is the root of a drive, like `X:\`.

You may pass parameters to &app_port_t; as with normal &app_t;, see . This maybe useful to enable logging, for example.

Do not start files in the `$PortableAppsRoot\PortableApps\StarDictPortable-stardict.sourceforge.com\App\StarDict` directory directly! In this case &app_t; runs in normal non-portable mode, it will search applications settings and other data file in usually places on the host machine instead of directories near the portable application. First, your settings will not be found, second, new settings will be saved on the host machine.

### Interface language

This section describes the algorithm used to select interface language in &app_port_t;.

1. Inspect PortableApps.com suite interface language ( Options Language ). If the language is not selected, goto . If the language is "en_US", goto . Check if &app_t; provides translation to the specified language. Goto if yes, and goto otherwise.

2. Read the `$PortableAppsRoot\PortableApps\StarDictPortable-stardict.sourceforge.com\Data\settings\StarDictPortableSettigns.ini` file. Inspect value of the `STARDICTLANG` option in the `Language` section. If the option is not specified, goto . If the value is "en_US", goto . Check if &app_t; provides translation to the specified language. Goto if yes, and goto otherwise.

3. Assign the language code to the `STARDICTLANG` environment variable.

4. Launch &app_t; executable, namely `stardict.exe`. For subsequent steps see .

## Troubleshooting

If you experience problems with &app_t;, examine &app_t; output. By default the application prints the most important messages to standard output and standard error. To see messages, start &app_t; from the console. You may increase verbosity of the output using the `--message-level` command line option, see .

To see standard output and standard error on Windows, start &app_t; from windows console and pass non-zero parameter to the `--message-level` command line option. Unfortunately, often windows console can not display all unicode characters that are sent to output. If this problem effects you, redirect output to a file or use &app_t; logging facility.

### Starting &app_t; from windows console

Starting &app_t; from windows console with --message-level option specified. Typical &app_t; output.

In some cases, &app_t; prints nothing to console or console is not available. Then turn on logging function, see for details.

## Related Projects

&app_t; would not be possible without many other projects' contributions. Here is a short list of projects that helped &app_t;.

Ma
Su'an

    msa@wri.com.cn

### StarDict 1.31

The original Motif/LessTif-based StarDict 1.31 written in 1999. &app_t; 2 got many good ideas from StarDict1.31 such as "Scan selection." Many of &app_t; 2's features, like "Fuzzy query," come from StarDict1.31.

Opera
Wang

    Opera.Wang@motorola.com

### StarDict 1.33+

StarDict1.33+ is a big enhancement of StarDict1.31. It added many dictionaries, and so it made me realize that dictionary data was not a barrier to a new, GTK2-based dictionary program. If there had been no StarDict1.33+, I would not have started the &app_t; 2 project. The author also helped me to port the StarDict 1.3 dictionary data files to &app_t; 2.

### The DICT Project

Many dictd dictionaries have been ported to &app_t;. dictzip, which came from dictd, is also used by &app_t;.

To find more information about the DICT Project, please visit www.dict.org.

### *Quick

Many wquick dictionaries have been ported to &app_t;.

To find more information about *Quick, please visit *Quick.

Terrence
Miao

    terence_miao@email.com

### The Blowfish Project

The Blowfish Project provided the Oxford English-Chinese dictionary.

To find more information about the Blowfish Project, please visit the Blowfish Project Web site.

Fu
Jianjun

    fujianjun@163.net

### XDICT

XDICT's dictionary has been ported to &app_t;.

### cdict5

cdict5's dictionary has been ported to &app_t;.

Leon
Liang

    Liang.Lu@CERN.CH

#### xcdict-tcltk

xcdict-tcltk Web site

Borg
LU

    dystopia@iname.com

#### cdict5 v1.3

To find more information about the cdict5 Project, please visit the cdict5 on freshports.

Paul
Denisowski

    cedict@chinesetools.com

### CEDICT

CEDICT's dictionary has been ported to &app_t;.

To find more information about the CEDICT Project, please visit the CEDICT Project Web site.

Kong
Hui

    konghui@xinhuanet.com

### CFFD

&app_t;'s icon was created with this software. CFFD also provided some useful information to me.

To find more information about the CFFD Project, please visit the CFFD Project Web site.

Hu
Zheng

    huzheng001@gmail.com

## Developers

To find more information about &app_t;, please visit the StarDict Web site.

Send all comments, suggestions, and bug reports to Hu Zheng (huzheng001@gmail.com).

Македонскиот превод е направен од Новица Наков (acivon@mail.com.mk). Сите коментари и предлози околу овој превод праќајте ги на горната адреса.

Nederlandse vertaling is gedaan door Ruud Slaats (ruudslaats@eurotechgroup.nl). Stuur al u commentaar, suggesties betreffende deze vertaling naar ruudslaats@eurotechgroup.nl.

На русский язык переведено Александром Мурыгиным (murygin@aitoc.com). Пожалуйста присылайте все комментарии и предложения относящиеся к этому переводу на этот адрес.

На українську мову перекладено Сергієм Дубиком (dubyk@library.lviv.ua). Будь ласка присилайте всі коментарі та пропозиції, що відносяться до цього перекладу, на цю адресу.

中文翻译由耿军军完成 (geng82@163.com)。请将有关本翻译的评论和建议发到我的邮箱。

繁體中文翻譯由陳曉陽完成 (roy.chan@debian.org.hk)。請將有關本翻譯的評論和建議電郵給我。