<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
<!ENTITY appversion "3.0.7">
<!ENTITY manrevision "3.0.7">
<!ENTITY date "Nov 2020">
<!ENTITY app "StarDict">
<!ENTITY app_port "StarDict Portable">
<!ENTITY app_t "<application>StarDict</application>">
<!ENTITY app_port_t "<application>StarDict Portable</application>">
<!ENTITY winedition "Windows edition">
<!ENTITY gnomeedition "Gnome edition">
<!ENTITY mdash "‒">
]>
(Do not remove this comment block.)
Maintained by the GNOME Documentation Project
http://developer.GNOME.org/projects/gdp
Template version: 2.0 beta
Template last modified Jan 30, 2002
-->
<article id="index" lang="en">
<articleinfo>
<title>&app; Manual V&manrevision;</title>
<copyright>
<year>2003</year>
<year>2004</year>
<year>2005</year>
<year>2006</year>
<year>2007</year>
<year>2008</year>
<year>2009</year>
<year>2010</year>
<holder>Hu Zheng</holder>
</copyright>
<publisher>
<publishername> GNOME Documentation Project </publishername>
</publisher>
&legal;
<authorgroup>
<author role="maintainer">
<firstname>Hu</firstname>
<surname>Zheng</surname>
<affiliation>
<orgname>GNOME Documentation Project</orgname>
<address> <email>huzheng001@gmail.com</email> </address>
</affiliation>
</author>
maintainers, etc. -->
<othercredit role="translator">
<firstname>Will</firstname>
<surname>Robinson</surname>
<affiliation>
<orgname>Stanford University</orgname>
<address> <email>wsr23@stanford.edu</email> </address>
</affiliation>
<contrib>Cleaning up English</contrib>
</othercredit>
<othercredit role="translator">
<firstname>Новица</firstname>
<surname>Наков</surname>
<affiliation>
<orgname>Слободен софтвер Македонија</orgname>
<address> <email>acivon@mail.com.mk</email> </address>
</affiliation>
<contrib>Македонски превод</contrib>
</othercredit>
<othercredit role="translator">
<firstname>Ruud</firstname>
<surname>Slaats</surname>
<affiliation>
<orgname>Eurotech Group</orgname>
<address> <email>ruudslaats@eurotechgroup.nl</email> </address>
</affiliation>
<contrib>Nederlandse vertaling</contrib>
</othercredit>
<othercredit role="translator">
<firstname>Александр</firstname>
<surname>Мурыгин</surname>
<affiliation>
<orgname>AITOC</orgname>
<address> <email>murygin@aitoc.com</email> </address>
</affiliation>
<contrib>Русский перевод</contrib>
</othercredit>
<othercredit role="translator">
<firstname>Сергій</firstname>
<surname>Дубик</surname>
<affiliation>
<orgname>ЛНБ</orgname>
<address> <email>dubyk@library.lviv.ua</email> </address>
</affiliation>
<contrib>український переклад</contrib>
</othercredit>
</authorgroup>
<revhistory>
than the current revision. -->
<revision>
<revnumber>&app; Manual V2.4.2</revnumber>
<date>Nov 2003</date>
<revdescription>
<para role="author">Hu Zheng</para>
<para role="publisher">GNOME Documentation Project</para>
</revdescription>
</revision>
<revision>
<revnumber>&app; Manual V3.0.2</revnumber>
<date>Jan 2011</date>
</revision>
</revhistory>
<releaseinfo> This manual describes version &appversion; of &app;.
</releaseinfo>
<legalnotice>
<title>Feedback</title>
<para>To report a bug or make a suggestion regarding the &app_t; application or
this manual, follow the directions in the
<ulink url="help:gnome-feedback" type="help">GNOME Feedback Page</ulink>.
</para>
</legalnotice>
<abstract role="description">
<para>User manual for the &app; dictionary.</para>
</abstract>
</articleinfo>
<indexterm><primary>StarDict</primary></indexterm>
<indexterm><primary>Dictionary</primary></indexterm>
<sect1 id="stardict-introduction">
<title>Introduction</title>
<para>
&app_t; is a Cross-Platform and international dictionary written in Gtk.
It has powerful features such as "Glob-style pattern matching," "Scan selected word," "Fuzzy query," etc.
</para>
</sect1>
<sect1 id="stardict-getting-started">
<title>Getting Started</title>
<sect2 id="stardict-to-start">
<title>Starting &app_t;</title>
<para>You can start &app_t; in the following ways:
</para>
<variablelist>
<varlistentry>
<term><guimenu>Applications</guimenu> menu</term>
<listitem>
<para>Choose <menuchoice><guisubmenu>Accessories</guisubmenu><guimenuitem>StarDict</guimenuitem></menuchoice>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Command line</term>
<listitem>
<para>Type <command>stardict</command>, then press <keycap>Return</keycap>.</para>
<para>
You can specify a word to query too:
</para>
<para>
<command>stardict <replaceable>word</replaceable></command>
</para>
<para>
or a Glob-style pattern matching string:
</para>
<para>
<command>stardict <replaceable>wo?d*</replaceable></command>
</para>
<para>
or do a fuzzy query:
</para>
<para>
<command>stardict <replaceable>/word</replaceable></command>
</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
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.
</para>
</note>
<para>See <xref linkend="stardict-details-command-line" /> for complete description of command line options.
</para>
</sect2>
<sect2 id="stardict-main-window">
<title>&app_t; Main window</title>
<para>When you start &app_t;, the following window appears.</para>
<figure id="stardict-main-window-fig">
<title>&app_t; Main Window</title>
<screenshot>
<mediaobject>
<imageobject><imagedata
fileref="figures/stardict_main_window.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Shows &app_t; main window. Contains Search field, Tool buttons, Word list, Definition area and Setting buttons.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<para>The &app_t; <firstterm>Main window</firstterm> consists of the following elements:</para>
<variablelist>
<varlistentry>
<term>Top bar</term>
<listitem>
<para>The top bar consists of the <firstterm>Search field</firstterm> and a number of buttons. Here they are in the order from left to right.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Clear</guilabel></term>
<listitem>
<para>Clears the Search field.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><firstterm>Search field</firstterm></term>
<listitem>
<para>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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><firstterm><guilabel>Fuzzy Query</guilabel></firstterm></term>
<listitem>
<para>Fuzzy queries the word entered into the Search field.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Go Back</guilabel></term>
<listitem>
<para>Go back to the word you queried before. Right-click to see a list of words you queried earlier.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Main menu</guilabel></term>
<listitem>
<para>A button on the right end of the Top bar.
It pops up the &app_t; Main menu.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>Left bar</term>
<listitem>
<para>The Left bar contains a number of buttons, here they are in the order from top to bottom:
</para>
<variablelist>
<varlistentry>
<term><firstterm><guilabel>Word list</guilabel></firstterm></term>
<listitem>
<para>Opens a list words that have been found in search.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><firstterm><guilabel>Results list</guilabel></firstterm></term>
<listitem>
<para>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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Full-Text Translation</guilabel></term>
<listitem>
<para>Switches to the Full-text translation mode that allows to translate blocks of text, see <xref linkend="stardict-translation"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Dictionary groups</guilabel></term>
<listitem>
<para>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. See <xref linkend="stardict-prefs-network-net-dict"/> for information about network dictionaries and how to configure them.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Previous word</guilabel> and <guilabel>Next word</guilabel></term>
<listitem>
<para>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.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>Bottom bar</term>
<listitem>
<para>The left part of the bar in the order from left to right:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Scan selection</guilabel> checkbox</term>
<listitem>
<para>Enable and disables the Scan mode.
Checking the <guibutton>Scan selection</guibutton> check button will cause &app_t;
to automatically look up words that you highlight in any application.
See <xref linkend="stardict-scan-selection"/> for more details about the Scan mode.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Info</guilabel></term>
<listitem>
<para>Shows an introduction to using &app_t; in the Definition area.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Quit</guilabel></term>
<listitem>
<para>Quits &app_t;.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>The right part of the bar in the order from left to right:
</para>
<variablelist>
<varlistentry>
<term><firstterm><guilabel>Internet search</guilabel></firstterm></term>
<listitem>
<para>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 <xref linkend="stardict-prefs-main-window-searchwebsite"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>&app; project website</guilabel></term>
<listitem>
<para>Opens &app_t; project website in a web browser.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Manage dictionaries</guilabel></term>
<listitem>
<para>Opens <firstterm>Manage dictionaries</firstterm> dialog that allows to configure dictionaries to use, organize them in groups and more.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Preferences</guilabel></term>
<listitem>
<para>Opens the <firstterm>Preferences</firstterm> dialog that allows to configuration a multitude of parameters pertaining to &app_t;. See <xref linkend="stardict-prefs"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><firstterm>Word list</firstterm></term>
<listitem>
<para>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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><firstterm>Definition area</firstterm></term>
<listitem>
<para>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 <xref linkend="stardict-definition-aria-toolbar"/>) and a bottom search bar (only visible when you search in the Definition area).
</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following hotkeys are available in the Main window.
</para>
<variablelist>
<title>Hotkeys</title>
<varlistentry>
<term><mousebutton>middle</mousebutton> mouse button</term>
<listitem>
<para>
This hotkey applies to the Definition area only.
</para>
<para>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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><mousebutton>right</mousebutton> mouse button</term>
<listitem>
<para>Show pop-up menu.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="stardict-definition-aria-toolbar">
<title><firstterm>Definition area toolbar</firstterm></title>
<para>The Definition area toolbar is at the top of the <guilabel>Definition area</guilabel>.
It contains a number of buttons. Here they are in the left-to-right order.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Hide(Show) the Word list</guilabel></term>
<listitem>
<para>Hide or show the Word list or the Results list, depending on what is active now.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Copy</guilabel></term>
<listitem>
<para>
Copy the Definition area text into clipboard, all the text.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Pronounce the word</guilabel></term>
<listitem>
<para>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.
</para>
<variablelist>
<title>TTS engines</title>
<varlistentry>
<term><guimenuitem>Real People TTS</guimenuitem></term>
<listitem>
<para>
This engine use sound samples performed by real people.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenuitem>Espeak TTS</guimenuitem></term>
<listitem>
<para>
Espeak TTS plugin.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenuitem>Festival TTS</guimenuitem></term>
<listitem>
<para>
Festival TTS plugin.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenuitem>Command TTS</guimenuitem></term>
<listitem>
<para>
TTS command you may specify in the Preferences dialog.
See <xref linkend="stardict-prefs-dictionary-sound"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Depending on configuration settings, installed plugins and other factors, the list of TTS engines may be shorter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Save to file</guilabel></term>
<listitem>
<para>
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 <xref linkend="stardict-prefs-dictionary-export"/>
section of the <guilabel>Preferences</guilabel> 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.
</para>
<para>Hotkey: <keycombo><keycap>Alt</keycap><keycap>e</keycap></keycombo>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Search in the Definition text</guilabel></term>
<listitem>
<para>
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.
</para>
<para>Hotkey: <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo>
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="stardict-notification-area">
<title>Notification area icon</title>
<para>
&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 <guimenuitem>Scan selection</guimenuitem>, or to <guimenuitem>Quit</guimenuitem>.
You can toggle <guimenuitem>Scan selection</guimenuitem> directly by ctrl-clicking the icon. Clicking the middle mouse button on
the icon will query the selected word.
</para>
<figure id="stardict-notification-area-fig">
<title>&app_t;'s notification area icon</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_notification_area.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>&app_t;'s notification area icon.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
</sect2>
<sect2 id="stardict-scan-selection">
<title>Scan selection</title>
<para>&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. </para>
<para>
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.
</para>
<para>
Scanning in Windows may not work with some applications.
For example, it's known that scanning does not work
with <application>FireFox 3.x</application> and <application>Windows Console</application> (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 —
<firstterm>Clipboard scanning</firstterm>, see
<xref linkend="stardict-prefs-dictionary-scan"/>.
</para>
<para>
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.
</para>
<para>
Second, there is special plugin to scan in PDF documents, see <xref linkend="stardict-acrobat-plugin"/>.
</para>
<figure id="stardict-float-window-fig">
<title>&app_t; Floating Window</title>
<screenshot>
<mediaobject>
<imageobject><imagedata
fileref="figures/stardict_float_window.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Shows &app_t; the Floating window. Contains Tool buttons and Definition area. </phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<itemizedlist>
<title>Usage tips</title>
<listitem>
<para>You may drag the Floating window to move it.</para>
</listitem>
<listitem>
<para>The Floating window will disappear when you move your pointer some distance away.</para>
</listitem>
<listitem>
<para>You may configure &app_t; so it will do scanning only when a special modifier key is held down. See <xref linkend="stardict-prefs-dictionary-scan"/>.</para>
</listitem>
<listitem>
<para>You may switch the Scan mode on and off by pressing the
<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>x</keycap></keycombo>
shortcut. See <xref linkend="stardict-prefs-dictionary-scan"/>.</para>
</listitem>
<listitem>
<para>&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.</para>
</listitem>
</itemizedlist>
<para>The &app_t; Floating window consists of the following elements:</para>
<variablelist>
<varlistentry>
<term>Tool buttons bar</term>
<listitem>
<para>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. </para>
<para>You can click these buttons to <guibutton>query</guibutton> a word in the Main window,
<guibutton>copy</guibutton> the query result to clipboard,
<guibutton>pronounce</guibutton> the word, <guibutton>stop</guibutton> selection scanning, etc.
To the far right is the <guibutton>Lock floating window</guibutton> button. If the
Floating window is locked, it will always be shown there. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Definition area</term>
<listitem>
<para>The query result is displayed in this area. </para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="stardict-acrobat-plugin">
<title>WordPick Adobe Acrobat plugin</title>
<para>&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.
</para>
<note>
<title>Limitations</title>
<para>
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.
</para>
</note>
<para>WordPick plugin embeds an icon into the stardard Acrobat toolbar near the Hand Tool.
In Acrobat Reader you will not see that icon — plugin is not available.
If the current document does not allow for text extraction, the icon is disabled,
the plugin is not operational.
</para>
<figure id="stardict-acrobat-toolbar-fig">
<title>Adobe Acrobat Toolbar with WordPick plugin icon</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="figures/acrobat_toolbar.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Shows Adobe Acrobat Toolbar with WordPick plugin icon.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<tip>
<title>How to inspect document security permissions</title>
<para>
In the main menu open <guimenu>File</guimenu>, <guimenuitem>Document properties</guimenuitem>.
<guilabel>Document properties</guilabel> dialog pops up. Proceed to <guilabel>Security</guilabel> tab. Look into <guilabel>Document Restrictions Summary</guilabel> group. <guilabel>Content Copying or Extraction</guilabel> must be allowed.
</para>
</tip>
<orderedlist>
<title>Translate text with WordPick plugin</title>
<listitem>
<para>Select WordPick and Select tools. Cursor changes to a vertical bar.
Now you can select text with mouse.
</para>
</listitem>
<listitem>
<para>Start &app_t; if you have not already done that, and enable Scan mode.
</para>
</listitem>
<listitem>
<para>Select a word in the PDF document,
&app_t; shows the Floating window with translation if the word is found.
</para>
</listitem>
</orderedlist>
<para>
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.
</para>
<para>Note that the Scan modifier key (<xref linkend="stardict-prefs-dictionary-scan"/>) 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.
</para>
</sect2>
<sect2 id="stardict-translation">
<title>Full-Text Translation</title>
<para>&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 <guilabel>Full-Text Translation</guilabel> button on the Left bar in &app_t; Main window.
</para>
<para>
&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.
</para>
<figure id="stardict-full-text-translation-fig">
<title>Full-Text Translation Mode</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="figures/stardict_full_text_translation.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Shows &app_t; in Full-Text Translation mode.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<para>
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 <guilabel>Translate</guilabel> 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.
</para>
<para>
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 <guilabel>Translate</guilabel> button to start translation. You'll see results in the result text area. Sometimes it may show you <guilabel>Not found!</guilabel> 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.
</para>
</sect2>
</sect1>
<sect1 id="stardict-usage">
<title>Usage</title>
<sect2 id="stardict-usage-lookup">
<title>Looking Up a Word</title>
<para>To look up the definition of a word, perform the following steps:</para>
<orderedlist>
<listitem><para>Type the word that you want to look up in the Search
field.</para></listitem>
<listitem><para>&app_t; will show the definition immediately. If not found, you can
press <keycap>Return</keycap> to do a fuzzy query or just click the <guibutton>Fuzzy query</guibutton> button. </para></listitem>
<listitem><para>Use the scrollbar to scroll through the definition. Select the words in the Word list to view the
related words. </para></listitem>
</orderedlist>
</sect2>
<sect2 id="stardict-usage-clear">
<title>Clearing the Display Area</title>
<para>To clear the text of the Search field, click the <guibutton>Clear</guibutton> button on the
left, or just press <keycap>Alt-C</keycap> or <keycap>ESC</keycap>.</para>
</sect2>
<sect2 id="stardict-usage-select">
<title>To Copy Text to Another Application</title>
<para>There are two ways to copy the text in the Definition area to another application:</para>
<itemizedlist>
<listitem><para>To copy all of the text, click the <guibutton>Copy</guibutton> button by the top of the <guilabel>Definition area</guilabel>.</para></listitem>
<listitem><para>To copy some of the text, select the text that you want to copy, then click your mouse's right
button and choose <guimenuitem>Copy</guimenuitem>.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="stardict-usage-find">
<title>To Find Text in the Definition Area</title>
<para>To find text in the Definition area, perform the following steps:</para>
<orderedlist>
<listitem><para>click the <guibutton>Find</guibutton> button by the top of the <guilabel>Definition area</guilabel>. </para> </listitem>
<listitem><para>Type the string that you want to find in the <guilabel>Find</guilabel> text box,
then press <keycap>Return</keycap>. You cannot use wildcards.</para></listitem>
<listitem><para>To find the next occurrence of the word, press <keycap>Return</keycap> again.</para></listitem>
</orderedlist>
</sect2>
<sect2 id="stardict-usage-scanning">
<title>Scanning: operation guide</title>
<itemizedlist>
<listitem>
<para>Scenarios below assume that you make selection with mouse.
</para>
</listitem>
<listitem>
<para>Scan key is the modifier set by the "Scan modifier key" option,
see <xref linkend="stardict-prefs-dictionary-scan"/>.
</para>
</listitem>
</itemizedlist>
<sect3 id="stardict-usage-scanning-linux">
<title>Scanning in Linux and Unix</title>
<orderedlist>
<title>Case 1. "Only scan while modifier key is being pressed" option is off</title>
<listitem>
<para>Select text to translate.
</para>
</listitem>
<listitem>
<para>Wait for a few seconds. The Floating Window pops up.
</para>
</listitem>
</orderedlist>
<orderedlist>
<title>Case 2. "Only scan while modifier key is being pressed" option is on</title>
<listitem>
<para>Press and hold the Scan key.
</para>
</listitem>
<listitem>
<para>Select the text.
</para>
</listitem>
<listitem>
<para>Wait for a few seconds. The Floating Window pops up.
</para>
</listitem>
<listitem>
<para>Release the Scan key.
</para>
</listitem>
</orderedlist>
<orderedlist>
<title>Case 2.1. "Only scan while modifier key is being pressed" option is on. A variation</title>
<listitem>
<para>Select the text and do not release the mouse button yet.
</para>
</listitem>
<listitem>
<para>Press and hold the Scan key.
</para>
</listitem>
<listitem>
<para>Release the mouse button.
</para>
</listitem>
<listitem>
<para>Wait for a few seconds. The Floating Window pops up.
</para>
</listitem>
<listitem>
<para>Release the Scan key.
</para>
</listitem>
</orderedlist>
<para>
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.
</para>
</sect3>
<sect3 id="stardict-usage-scanning-windows">
<title>Scanning in Windows</title>
<orderedlist>
<title>Case 1. "Only scan while modifier key is being pressed" option is off</title>
<listitem>
<para>Place the mouse pointer over the word you want to traslate.
</para>
</listitem>
<listitem>
<para>Do not move the mouse for a few seconds. The Floating Window pops up.
</para>
</listitem>
</orderedlist>
<orderedlist>
<title>Case 2. "Only scan while modifier key is being pressed" option is on</title>
<listitem>
<para>Place the mouse pointer over the word you want to traslate.
</para>
</listitem>
<listitem>
<para>Press and hold the Scan key.
</para>
</listitem>
<listitem>
<para>Do not move the mouse for a few seconds. The Floating Window pops up.
</para>
</listitem>
<listitem>
<para>Release the Scan key.
</para>
</listitem>
</orderedlist>
<para>For scanning in PDF documents see <xref linkend="stardict-acrobat-plugin"/>.
</para>
</sect3>
</sect2>
<sect2 id="stardict-usage-scan-mode">
<title>Toggle Scan Mode</title>
<para>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 <xref linkend="stardict-scan-selection"/>.</para>
<itemizedlist>
<title>Ways to enable the Scan mode</title>
<listitem><para>Toggle the <guilabel>Scan selection</guilabel> checkbox at the bottom left corner of the &app_t; Main window.</para></listitem>
<listitem><para>Right-click the Notification area icon and check <guimenuitem>Scan</guimenuitem>
in the pop-up menu.</para></listitem>
<listitem><para>Press
<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>x</keycap></keycombo>
shortcut (it toggles the Scan mode). To configure the shortcut see
<xref linkend="stardict-prefs-dictionary-scan"/>.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="stardict-usage-hotkeys">
<title>Main window hotkeys</title>
<variablelist>
<varlistentry>
<term><keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
</term>
<listitem>
<para>Quit &app_t;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Alt</keycap><keycap>x</keycap></keycombo>
</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Alt</keycap><keycap>z</keycap></keycombo>
</term>
<listitem>
<para>Iconify the application. The Main window is hidden, the taskbar item remains.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Alt</keycap><keycap>e</keycap></keycombo>
</term>
<listitem>
<para>Save word definition to a file. See <xref linkend="stardict-definition-aria-toolbar"/> for more details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>F1</keycap></keycombo>
</term>
<listitem>
<para>Show help.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo>
</term>
<listitem>
<para>Search in the Definition area. See <xref linkend="stardict-definition-aria-toolbar"/> for more details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Alt</keycap><keycap>Left</keycap></keycombo>
</term>
<listitem>
<para>Go Back. Return to the word that was queried before.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>
</term>
<listitem>
<para>Previous word. Query the previous word in the Word index.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Alt</keycap><keycap>Down</keycap></keycombo>
</term>
<listitem>
<para>Next word. Query the next word in the Word index.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Alt</keycap><keycap>m</keycap></keycombo>
</term>
<listitem>
<para>Menu. Show the Main menu.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Ctrl</keycap><keycap>v</keycap></keycombo>
</term>
<listitem>
<para>Query clipboard text in &app_t;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Ctrl</keycap><keycap>u</keycap></keycombo>
</term>
<listitem>
<para>Clear the Search field and focus it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>BackSpace</keycap></keycombo>
</term>
<listitem>
<para>The same as <keycombo><keycap>Ctrl</keycap><keycap>u</keycap></keycombo>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Enter</keycap></keycombo>
</term>
<listitem>
<orderedlist>
<listitem>
<para>The focus is in the Word list.</para>
<para>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.</para>
</listitem>
<listitem>
<para>The focus is in the Definition area.</para>
<para>Requery the text in the Search field.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Space</keycap></keycombo>
</term>
<listitem>
<para>Focus the Search field.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Escape</keycap></keycombo>
</term>
<listitem>
<orderedlist>
<listitem>
<para>The focus is in Definition area Search bar.</para>
<para>Hide the search bar.</para>
</listitem>
<listitem>
<para>Otherwise, this hotkey has the same effect as
<keycombo><keycap>Ctrl</keycap><keycap>u</keycap></keycombo>.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>z</keycap></keycombo>
</term>
<listitem>
<para>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
<xref linkend="stardict-prefs-main-window-options"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>x</keycap></keycombo>
</term>
<listitem>
<para>Toggle the Scan mode.
You may change the hotkey in the Preferences dialog, see
<xref linkend="stardict-prefs-dictionary-scan"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="stardict-usage-add-dicts">
<title>Installing new dictionaries</title>
<para>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 <xref linkend="stardict-details-dictionaries"/>.
</para>
<orderedlist>
<title>Installing a dictionary</title>
<listitem>
<para>Download a dictionary. Normally a dictionary is packed in an archive file, for example, <filename>WineEnRu.zip</filename>.
</para>
</listitem>
<listitem>
<para>Unpack the archive in a new directory. You may name the directory after the archive name, though that is not required.
</para>
<screen>
WineEnRu/WineEnRu.dict
WineEnRu/WineEnRu.idx
WineEnRu/WineEnRu.ifo</screen>
</listitem>
<listitem>
<para>Copy the dictionary directory into one of &app_t; dictionary directories, see <xref linkend="stardict-details-dictionaries-dirs"/>.
</para>
</listitem>
<listitem>
<para>Restart &app_t;. The new dictionary will be added into the default dictionary group.
</para>
</listitem>
</orderedlist>
<caution>
<title>Broken dictionaries</title>
<para>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 <application>&app; Editor</application> or <application>stardict-verify</application> command line tool.
</para>
</caution>
</sect2>
<sect2 id="stardict-usage-remove-dicts">
<title>Removing dictionaries</title>
<para>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.
</para>
<screen>
WineEnRu.dict
WineEnRu.idx
WineEnRu.idx.oft
WineEnRu.ifo</screen>
<para>Some dictionaries may include resource database that is named differently. For complete list of file see <xref linkend="stardict-details-dictionaries"/>. If you follow the rule "one dictionary — one directory", removing a dictionary will be easer.
</para>
<orderedlist>
<title>Removing a dictionary</title>
<listitem>
<para>Quit &app_t;. Make sure that &app_t; has really terminated, not just minimized into tray icon!
</para>
</listitem>
<listitem>
<para>Remove dictionary files.
</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
<sect1 id="stardict-prefs">
<title>Preferences</title>
<para>To configure &app_t;, click the <guibutton>Preferences</guibutton> button at the
right-bottom corner of the Main window or click the <guibutton>Main menu</guibutton> button and choose
<guimenuitem>Preferences</guimenuitem>. </para>
<sect2 id="stardict-prefs-dictionary">
<title>Dictionary</title>
<sect3 id="stardict-prefs-dictionary-scan">
<title>Scan Selection</title>
<variablelist>
<varlistentry>
<term id="stardict-prefs-dictionary-scan-scan-when-modifier">
<guilabel>Only scan while modifier key is being pressed.</guilabel> </term>
<listitem>
<para>Only do scanning while the modifier key being pressed. The modifier key is set
by the <xref linkend="stardict-prefs-dictionary-scan" endterm="stardict-prefs-dictionary-scan-scan-key"/> option.</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="stardict-prefs-dictionary-scan-hide-when-modifier-released">
<guilabel>Hide floating window when modifier key released.</guilabel></term>
<listitem>
<para>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.
</para>
<para>This option has effect only if <xref linkend="stardict-prefs-dictionary-scan" endterm="stardict-prefs-dictionary-scan-scan-when-modifier"/>
is checked.</para>
<para>Default: TRUE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="stardict-prefs-dictionary-scan-scan-key"><guilabel>Scan modifier key</guilabel></term>
<listitem>
<para>This option allows to choose a modifier keys or a key combination that enables scanning.</para>
<para>This option has effect only if <xref linkend="stardict-prefs-dictionary-scan" endterm="stardict-prefs-dictionary-scan-scan-when-modifier"/>
is checked.</para>
<para>Default key: <keycap>Win</keycap> (depends on &app_t; edition).</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="stardict-prefs-dictionary-scan-scan-clipboard"><guilabel>Scan clipboard.</guilabel></term>
<listitem>
<para>Enables Clipboard scanning. If enabled, when new text is copied into the clipboard,
&app_t; lookup the text into the Floating window.</para>
<para>This option is only available in <emphasis>&winedition;</emphasis> of &app_t;.</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Scan mode shortcut</term>
<listitem>
<para>The Scan mode shortcut enables or disables the Scan mode.
Check the <guilabel>Use scan hotkey</guilabel> 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.</para>
<para>Default: TRUE</para>
<para>Default shortcut:
<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>x</keycap></keycombo>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-dictionary-font">
<title>Font</title>
<variablelist>
<varlistentry>
<term><guilabel>Use custom font.</guilabel> </term>
<listitem>
<para>Allows you to override the system's default for &app_t;.
If this option is turned on, the font selelected in the <guilabel>Dictionary font</guilabel> option will be
used instead of the system font.</para>
<para>Font settings apply immediately.</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-dictionary-cache">
<title>Cache</title>
<variablelist>
<varlistentry>
<term><guilabel id="stardict-prefs-dictionary-scan-create-cache-files">Create cache files to speed up loading.</guilabel></term>
<listitem>
<para>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.</para>
<para>Default: TRUE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel id="stardict-prefs-dictionary-scan-use-collation">Sort word list by collation function.</guilabel></term>
<listitem>
<para>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.
</para>
<para>
To use a collation function check the
<guilabel>Sort word list by collation function</guilabel>
checkbox and select the desired function from the
<guilabel>Collation function</guilabel> 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.
</para>
<para>It's highly recommended to enable the
<xref linkend="stardict-prefs-dictionary-cache" endterm="stardict-prefs-dictionary-scan-create-cache-files"/>
option, otherwise &app_t; will do sorting each time the application starts.
</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Clean all cache files</guilabel></term>
<listitem>
<para>Remove all &app_t; cache files.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-dictionary-export">
<title>Export</title>
<para>&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.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Only export words.</guilabel></term>
<listitem>
<para>When this option is set, &app_t; exports only the found word,
otherwise exports the complete article.</para>
<para>Default: TRUE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>File name</guilabel></term>
<listitem>
<para>
Name of the file where to export data.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-dictionary-sound">
<title>Sound</title>
<para>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.
</para>
<para>
To play sound files &app_t; may harness platform-specific services or use commands you specify on this page.
</para>
<para>
This page allows to configure some aspects of the TTS subsystem.
The TTS subsystem is used to pronounce words by computer.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Enable sound event.</guilabel> </term>
<listitem>
<para>Whether to enable sound events. &app_t; will play sound event when button is
active, released, and when a menu pops up.</para>
<para>Default: TRUE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Command for playing sound files:</guilabel></term>
<listitem>
<para>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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Always use sound play command</guilabel></term>
<listitem>
<para>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.
</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>RealPeopleTTS search path:</guilabel></term>
<listitem>
<para>
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.
</para>
<variablelist>
<title>Default:</title>
<varlistentry>
<term>In &winedition; of &app_t;</term>
<listitem>
<para>
<filename class='directory'>C:\Program Files\WyabdcRealPeopleTTS</filename>,
<filename class='directory'>C:\Program Files\OtdRealPeopleTTS</filename>,
<filename class='directory'>WyabdcRealPeopleTTS</filename>,
<filename class='directory'>OtdRealPeopleTTS</filename>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>In other editions of &app_t;</term>
<listitem>
<para>
<filename class='directory'>/usr/share/WyabdcRealPeopleTTS</filename>,
<filename class='directory'>/usr/share/OtdRealPeopleTTS</filename>
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Enable TTS program.</guilabel></term>
<listitem>
<para>
Allows to use the command below to read words.
You need to restart &app_t; for changes to take effect.
</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TTS <guilabel>Command line:</guilabel></term>
<listitem>
<para>
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.
</para>
<para>Default: <emphasis>nothing</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-dictionary-video">
<title>Video</title>
<variablelist>
<varlistentry>
<term><guilabel>Command for playing video files:</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-dictionary-article-rendering">
<title>Article rendering</title>
<variablelist>
<varlistentry>
<term><guilabel>Highlight search term</guilabel></term>
<listitem>
<para>
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.
</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-dictionary-dict-management">
<title>Dict management</title>
<variablelist>
<varlistentry>
<term><guilabel>Add new dictionaries to active dictionary group</guilabel></term>
<listitem>
<para>
At start time &app_t; scans known directories for dictionary files.
This options specifies what to do with new dictionaries.
When this option is on, new dictionaries are added to the active dictionary group.
Otherwise you have to add new dictionaries to a group manually.
</para>
<para>Disabling this option may be useful if you have multiple groups and you want to control precisely what each group contains. Often the last active dictionary group is not appropriate for new dictionaries.
</para>
<para>Default: TRUE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Add new plug-ins to active dictionary group</guilabel></term>
<listitem>
<para>
At start time &app_t; scans known directories for plug-in files.
This options specifies what to do with new plug-ins (belonging to Virtual Dictionary and Network dictionary plug-in categories).
When this option is on, new plug-ins are added to the active dictionary group.
Otherwise you have to add new plug-ins to a group manually.
</para>
<para>Disabling this option may be useful if you have multiple groups and you want to control precisely what each group contains. Often the last active dictionary group is not appropriate for new plug-ins.
</para>
<para>Default: TRUE.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="stardict-prefs-network">
<title>Network</title>
<sect3 id="stardict-prefs-network-net-dict">
<title>Net Dict</title>
<para>&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.
</para>
<para>
At the present time &app_t; may be configured to query only one server. When network dictionaries are enabled, each time you ask &app_t; to lookup a word or phrase, the application sends a request to the configured server. Note that network dictionaries are enabled globally, they are used in both Main and Floating windows, they do not depend on the dictionary group selected.
</para>
<para>To configure the list of dictionaries on the server, use the Manage Dictionaries dialog, Network dictionaries tab.
</para>
<para>You need to register on the server to use this feature. Click <guilabel>Register an account</guilabel> button on this page to register an account.
</para>
<caution>
<para>Enabling network dictionaries poses a security risk.
Your text will be sent to remote servers.
Additionally, since network requests do not use any encryption,
anyone able to sniff communication can see that text.
</para>
</caution>
<variablelist>
<varlistentry>
<term><guilabel>Enable network dictionaries</guilabel></term>
<listitem>
<para>Enables network dictionaries.
</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-network-web-browser">
<title>Web browser</title>
<para>
&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.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Command for opening URLs</guilabel></term>
<listitem>
<para>
This option allows you to specify a command to use for opening <acronym>URL</acronym>s.
Some editions of &app_t; use platform-specific services for opening <acronym>URL</acronym>s 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.
</para>
<para>
You may specify a program name (with or without full path) accompaned with any options required. The <acronym>URL</acronym> to open will be appended to this command at run time.
</para>
<para>Default: <command>firefox</command> (depends on edition).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Always use this command for opening URLs.</guilabel></term>
<listitem>
<para>
This option is only available in editions of &app_t; that can use other ways to open a web link.
</para>
<para>
Check this option to use the custom command to open web links instead of platform-specific services.
</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="stardict-prefs-main-window">
<title>Main Window</title>
<sect3 id="stardict-prefs-main-window-input">
<title>Input</title>
<variablelist>
<varlistentry>
<term><guilabel>Search while typing</guilabel></term>
<listitem>
<para>
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. If the time span is 0, search is started immediately after you change the search field.
</para>
<para>
When this option is not checked, you need to press
<keycombo><keycap>Enter</keycap></keycombo>
in order for &app_t; to start searching the word.
</para>
<para>Default: TRUE</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Word change timeout</guilabel></term>
<listitem>
<para>
A word change timeout in milliseconds. See the option above for details.
</para>
<para>Default: 300 ms</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Show the first word when not found.</guilabel></term>
<listitem>
<para>
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.
</para>
<para>Default: TRUE</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-main-window-options">
<title>Options</title>
<variablelist>
<varlistentry>
<term><guilabel>Skin</guilabel></term>
<listitem>
<para>
Allows to customize graphical appearance of the application.
Select the <emphasis>Default</emphasis> 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 <filename>doc/Skins</filename> file in &app_t; sources.
</para>
<para>Default: <emphasis>Default</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Hide main window when starting StarDict.</guilabel></term>
<listitem>
<para>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.</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Use open main window hotkey</guilabel></term>
<listitem>
<para>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.
</para>
<para>Default: TRUE.</para>
<para>Default hotkey:
<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>z</keycap></keycombo>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Transparency</guilabel></term>
<listitem>
<para>
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 — fully opaque, 80 — almost fully transparent.
Moving the slider has an immediate effect on the window.
</para>
<para>
On X11 this has any effect only on X screens with a compositing manager running.
On Windows it should work always.
</para>
<para>Default: 0 — fully opaque.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-main-window-searchwebsite">
<title>Search website</title>
<para>&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 <acronym>URL</acronym>.
Normally, the text is assigned to a GET request parameter.
For example, to search for word <emphasis>stardict</emphasis> in
<ulink url="http://www.google.com" type="http">Google search engine</ulink> you may use the following
<acronym>URL</acronym>
<uri>http://www.google.com/search?q=<replaceable>stardict</replaceable></uri>.
You can search websites in &app_t;
right-clicking the <guibutton>Internet search</guibutton> button in the Main window.
</para>
<para>
&app_t; does not handle the web request itself, it only composes a <acronym>URL</acronym> and invokes an external program like a web browser or use platform-specific services to open the <acronym>URL</acronym>.
</para>
<para>
On this page you may see a list of websites. Use <guilabel>Add</guilabel> and
<guilabel>Remove</guilabel> buttons to add new sites and remove existing records.
Use <guilabel>Up</guilabel> and <guilabel>Down</guilabel> arrow buttons to reorder records in the list. Each record consists of three items:
</para>
<variablelist>
<title>Website record</title>
<varlistentry>
<term><guilabel>Website name</guilabel></term>
<listitem>
<para>This is a label you see in menu. Use a meaningful name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Website link</guilabel></term>
<listitem>
<para>Link to the main page of the website.
This link is opened when there is nothing to search for, the Search field is empty.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Website search link</guilabel></term>
<listitem>
<para>Link to perform request.
<emphasis>%s</emphasis> identifies the place where to insert the search text.
For example, <uri>http://www.google.com/search?q=<replaceable>%s</replaceable></uri>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="stardict-prefs-notification-area-icon">
<title>Notification area icon</title>
<sect3 id="stardict-prefs-notification-area-icon-options">
<title>Options</title>
<variablelist>
<varlistentry>
<term><guilabel>When middle mouse button is clicked:</guilabel> </term>
<listitem>
<para>Specifies an action to perform when user clicks the middle mouse button on the Notification
area icon. There are the following choices:</para>
<itemizedlist>
<listitem>
<para><guilabel>Query selection in floating window</guilabel></para>
</listitem>
<listitem>
<para><guilabel>Query selection in main window</guilabel></para>
</listitem>
<listitem>
<para><guilabel>Do nothing</guilabel></para>
</listitem>
</itemizedlist>
<para>In the <guilabel>Do nothing</guilabel> 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.
</para>
<para>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 <emphasis>X</emphasis> <emphasis>Primary</emphasis> 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.
</para>
<para>Default: <guilabel>Query selection in floating window</guilabel>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="stardict-prefs-floating-window">
<title>Floating Window</title>
<sect3 id="stardict-prefs-floating-options">
<title>Options</title>
<variablelist>
<varlistentry>
<term><guilabel>Pronounce the word when it pops up.</guilabel> </term>
<listitem>
<para>When set, pronounce the word when the Floating window shows translation.</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Show floating window if word not found.</guilabel></term>
<listitem>
<para>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 — this option is unset, 2) show the Floating window with text indicating that the word was not found — this option is set.</para>
<para>Default: TRUE.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="stardict-prefs-floating-settings">
<title>Settings</title>
<variablelist>
<varlistentry>
<term><guilabel>Max window width.</guilabel> </term>
<listitem>
<para>Sets the Floating window's max width.</para>
<para>Default: 320.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Max window height.</guilabel> </term>
<listitem>
<para>Sets the Floating window's max height.</para>
<para>Default: 240.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Use custom background color:</guilabel></term>
<listitem>
<para>Enables to use custom color for background in the Floating window and select that color.</para>
<para>Default: FALSE.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Transparency</guilabel></term>
<listitem>
<para>
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 — fully opaque, 80 — almost fully transparent.
Moving the slider has an immediate effect on the window.
</para>
<para>
On X11 this has any effect only on X screens with a compositing manager running.
On Windows it should work always.
</para>
<para>Default: 0 — fully opaque.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
</sect1>
<sect1 id="manage-dicts">
<title>Manage dictionaries</title>
<para>This section of the manual describes the
Manage dictionaries dialog that allows you to view and organize all dictionaries available in &app_t;.
You may work with the following types of dictionaries: normal (index-based) dictionaries, virtual plugins, network plugins, network dictionaries, tree dictionaries.
The dialog consists of 4 tabs: <xref linkend="manage-dicts-dict-list"/>,
<xref linkend="manage-dicts-manage-dict"/>, <xref linkend="manage-dicts-manage-dict"/>,
<xref linkend="manage-dicts-tree-dict"/>.
Each tab is described in details below.
</para>
<sect2 id="manage-dicts-dict-list">
<title>Dict list tab</title>
<para>Dict list tab allows you to view and reorder a list of all dictionaries of the following types: normal (index-based) dictionaries, virtual plugins, network plugins.
Dictionaries of these types may be organized into groups.
To work with dictionaries groups, switch to <xref linkend="manage-dicts-manage-dict"/>.
This tab shows all dictionaries that are known to &app_t;, irrespective of whether they are used in some dictionary group or not.
</para>
<figure id="manage-dicts-dict-list-fig">
<title>Dict list tab</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_manage_dicts_dict_list.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</figure>
<para>Columns of the dictionary list as self-explaining. <guilabel>Dictionary name</guilabel> — name of the dictionary for a normal dictionary and the name of plugin for plugins.
<guilabel>Word count</guilabel> — number of word in a normal dictionary. For plugins this column always contains 0. <guilabel>Type</guilabel> — type of the dictionary <guilabel>Local</guilabel> for normal dictionaries, <guilabel>Virtual</guilabel> for Virtual plugins, <guilabel>Network</guilabel> for Network plugins.
</para>
<para>You may reorder dictionaries in the list with buttons on the right or using drag and drop technology.
Note that you can select only one dictionary at a time.
This list specifies the default order of dictionaries for Add dictionary dialog.
That dialog is used to add new dictionaries to groups, see <xref linkend="manage-dicts-manage-dict"/>.
The order of dictionaries is saved between application restarts.
Note, however, that virtual and network plugins are always appear at the end of the list.
Their order is not saved, &app_t; saves only the order of normal dictionaries.
</para>
<para>To get detailed information about a dictionary, double-click on a list item.
<guilabel>Dictionary information</guilabel> dialog appears.
Here you may see dictionary name, word count, author, email and other fields.
</para>
</sect2>
<sect2 id="manage-dicts-manage-dict">
<title>Manage dict tab</title>
<para>This tab allows you organize all dictionaries listed on <xref linkend="manage-dicts-dict-list"/> in groups.
By default &app_t; has one group including all dictionaries.
You may create new groups to organize your dictionaries better.
Switching dictionary group allows you to quickly change a set of dictionaries where &app_t; searches words.
See <xref linkend="stardict-main-window"/>, Left bar for information about how to switch dictionary group.
For example, you may organize your dictionaries by a language pairs: English to Chinese, Chinese to German, German to Russian, etc.
</para>
<figure id="manage-dicts-manage-dict-fig">
<title>Manage dict tab</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_manage_dicts_manage_dict.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</figure>
<para>Each group consists of two subgroups: Query Dict and Scan Dict.
The first subgroups is used for queries in the Main window, while the second is used in Scan mode.
Subgroups contain lists of dictionaries.
The order of dictionaries this dialog correspond to the order of results in Main window or Floating window, depending on subgroup.
Note, however, that results from Network plugins are always added at the bottom.
That is because response from a Network plugin is normally asynchronous and comes with unpredictable delay.
</para>
<para>Dictionary list is organized in a tree, you may collapse groups and subgroups to save space.
You may reorder dictionary groups and dictionaries inside a subgroup using buttons at the right or using drag and drop technology.
Note, that can select only one item at a time. You cannot move dictionaries between groups and subgroups.
</para>
<para>To get detailed information about a dictionary, double-click on a row, or select a row and click the button with a bulb, or click <guimenuitem>Show information</guimenuitem> in context menu.
</para>
<para>
To remove a dictionary from a subgroup, or to remove a group, select that list item, then click on the button with a trash can. Note that removing a dictionary does not affect the corresponding file on the hard disk. Clicking the remove button on a subgroup, removes all dictionaries from that subgroup.
</para>
<para>Each dictionary in the list can be independently enabled/disabled.
Disabling a dictionary has the same effect as removing it from the list, it will not be used to search words when the corresponding dictionary group is selected.
Disabled dictionary retains its position in the list, you can easily enable it later.
In the context menu you may find <guimenuitem>Select all</guimenuitem>, <guimenuitem>Unselect all</guimenuitem> items. They select (unselect) all dictionaries in a subgroup.
</para>
<para>To add new dictionaries into subgroup, you need to select a subgroup or a dictionary inside it, and click the button with a plus sign.
Add dictionary dialog appears.
Here you see a list of all dictionaries that are not yet added to the selected subgroup.
The order of dictionaries is the same as on <xref linkend="manage-dicts-dict-list"/>.
You may select any number of items in this list.
Some columns are clickable. Clicking on a column title sort the list by that column.
Sorting by <guilabel>Path</guilabel> column is especially useful if your dictionaries are organized in directories corresponding to dictionary groups.
After sorting all dictionaries from the same directory will be located in adjacent rows.
</para>
<figure id="manage-dicts-add-dict-fig">
<title>Add dictionary dialog</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_manage_dicts_add_dict.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</figure>
<para>To rename a group, select it, then click on the selected row again.
Now you may edit the group name in place.
</para>
</sect2>
<sect2 id="manage-dicts-tree-dict">
<title>Tree dictionaries tab</title>
<para>On this tab you may see a list of all tree dictionaries.
Tree dictionaries are not used when you type a word into the Main window or use the Scan feature.
Tree dictionaries are shown on a tab of its own in the Main window, see <xref linkend="stardict-main-window"/>, <guibutton>Tree</guibutton> button on the Left bar.
</para>
<figure id="manage-dicts-tree-dict-fig">
<title>Tree dictionary tab</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_manage_dicts_tree_dict.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</figure>
<para>You may reorder dictionaries with the buttons on the right or using drag and drop technology.
</para>
<para>To get detailed information about a dictionaries, double-click on it or select <guimenuitem>Show information</guimenuitem> from the context menu.
</para>
<para>You may disable any dictionaries using a checkbox in the first column.
In the context menu you may find <guimenuitem>Select all</guimenuitem>, <guimenuitem>Unselect all</guimenuitem> items that selects/unselect all dictionaries in the list.
</para>
</sect2>
<sect2 id="manage-dicts-network-dict">
<title>Network dictionaries tab</title>
<para>Network dictionaries tab contains a list of network dictionaries.
As the name implies, network dictionaries are not installed on your machine, they reside on a server in Internet.
&app_t; uses a custom protocol to query remote dictionaries and get results.
Before you can add dictionaries into this list, you need to register on the server,
see <xref linkend="stardict-prefs-network-net-dict"/>.
</para>
<figure id="manage-dicts-network-dict-fig">
<title>Network dictionaries tab</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_manage_dicts_network_dicts.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</figure>
<para>You may reorder the dictionaries using the buttons on the right of the dialog or using drag and drop technology.
</para>
<para>To get detailed information about a dictionary, double-click on it.
</para>
<note>
<para>
It's perfectly normal that &app_t; does not react immediately to your activity.
Many action in this dialog require access to the remote server.
The response comes with unpredictable delay.
</para>
</note>
<para>To add new dictionaries, click on the <guibutton>Add</guibutton> button.
<guilabel>Browse dictionaries</guilabel> dialog appears.
</para>
<para>
In <guilabel>Browse dictionaries</guilabel> dialog, expand dictionary groups to see dictionaries.
To get information about a dictionary, select a dictionary, then click the <guibutton>Information</guibutton> button.
To add a dictionary, select a dictionary on the list, then click the <guibutton>Add</guibutton> button.
</para>
<figure id="manage-dicts-network-dict-browse-fig">
<title>Browse dictionaries dialog</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_manage_dicts_network_dicts_browse.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</figure>
<para>To remove dictionaries from your list, click on the <guibutton>Remove</guibutton> button.
</para>
</sect2>
</sect1>
<sect1 id="manage-plugins">
<title>Manage Plugins</title>
<para>Mange plug-in dialog allows you to view, configure, enable/disable &app_t; plug-ins.
Plug-ins extends &app_t; functionality, they may be independently turned on and off.
Some plug-ins provides a number of options that may be configured via a GUI dialog.
Some settings take effect immediately, other may require restarting &app_t;.
List of available plug-in depends on &app_t; edition.
If you build &app_t; from source, you may permanently disable some plug-ins, they will not be available in the Mange Plugins dialog.
</para>
<para>Selecting a plug-in in the list activates two functions. You may see plug-in details, clicking on <guilabel>Plug-in Details</guilabel> link at the bottom of the dialog. Here you may see short plug-in description, author, web site and file name. <guibutton>Configure Plug-in</guibutton> button is made available for plug-ins that have configurable options.
</para>
<para>
<variablelist>
<title>Plugin categories</title>
<varlistentry>
<term><guilabel>Virtual Dictionary</guilabel></term>
<listitem>
<para>A plug-in of this category acts like as a normal dictionary, it returns some information per key phrase, but it does not use a &app_t; dictionary. Plug-in may take information from different sources: a database file, OS service, it may generate response on the fly. For example, Man plug-in displays system man pages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Network Dictionary</guilabel></term>
<listitem>
<para>A plug-in of this category uses a network service or network dictionary as a source of information. Once you type a key phrase into the Search field of the Main window, the plug-in sends a network request to a service. Once response is received, result are displayed in &app_t;. You need a working Internet connection for this type of plug-in.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Special Dictionary</guilabel></term>
<listitem>
<para>There currently only one dictionary assigned to this category — WordNet dict rendering. It displays results in special interactive widget while other dictionaries produce static content.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>TTS Engine</guilabel></term>
<listitem>
<para>Text to Speech engines. TTS Engines allows you to "Read" text. Plug-ins of this category do not add any content to the results window. To activate this type of plug-in, you need to click a button or a menu item, then you should hear sound.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Data Parsing Engine</guilabel></term>
<listitem>
<para>Plug-ins of the category convert contents of a dictionary into a format understandable by &app_t;. Articles of &app_t; dictionary may use a number of textual formats, like HTML, XDXF, WordNet, Wiki. In order for &app_t; to be able to render the article, data must be converted to Pango text, that is the format &app_t; now work with. If you do not have the required plug-in to render the dictionary article, instead of article you'll see a message like this, "XDXF data parsing plug-in is not found!".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Misc</guilabel></term>
<listitem>
<para>This is a category for plug-ins that do not fit into other categories.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<sect2 id="manage-plugins-xdxf">
<title>XDXF data parsing plug-in</title>
<para>This is a plug-in of Data Parsing Engine category that parses XDXF data format.
This plug-in allows you to configure colors used to render an article.
<variablelist>
<title>XDXF plug-in options, colors</title>
<varlistentry>
<term><guilabel>Abbreviation</guilabel></term>
<listitem>
<para>Abbreviations like n. (noun), v. (verb), adj. (adjective), etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Example</guilabel></term>
<listitem>
<para>Example that demonstrates use of the key phrase.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Extra key phrase</guilabel></term>
<listitem>
<para>The first key phrase is rendered uniformly for all articles, irrespective of the data format of the article, information source and other factors. Some articles may contain extra key phrases, you may assign special color to render them.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Emphasize</guilabel></term>
<listitem>
<para>An article may contain emphasized text. Normally the article specify the color to use for such text, but in case it is not specified, this color will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Reference</guilabel></term>
<listitem>
<para>A web link or a link to other word in the dictionary.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
<sect1 id="stardict-details">
<title>Details</title>
<sect2 id="stardict-details-command-line">
<title>Command line options</title>
<para>&app_t; usage:
</para>
<para><command>stardict <replaceable>options</replaceable> <replaceable>query_word</replaceable></command>
</para>
<variablelist>
<varlistentry>
<term>query_word</term>
<listitem>
<para>With <replaceable>query_word</replaceable> 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-m, --message-level=<replaceable>integer</replaceable></term>
<listitem>
<para>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 — print all produced messages, including debug ones. Default value is 4 which passes informational messages, like what dictionaries are loaded during startup.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l, --log-level=<replaceable>integer</replaceable></term>
<listitem>
<para>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 — print all produced messages, including debug ones. Default value is 0, that is log file is not used. See <xref linkend="stardict-details-logging"/> for details about &app_t; log.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h, --hide</term>
<listitem>
<para>Do not show splash screen during startup and hide the Main window. Only notification area icon will be visible.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-n, --new</term>
<listitem>
<para>Start a new instance of &app_t;.
By default &app_t; checks if the application is already running and prevents starting the second instance.
</para>
<para>This option is only available in &winedition; and &gnomeedition; of &app_t;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-q, --quit</term>
<listitem>
<para>Quit an existing instance of &app_t;.
</para>
<para>This option is only available in &gnomeedition; of &app_t;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--dirs-config</term>
<listitem>
<para>Specifies path to the &app_t; directory configuration file. See <xref linkend="stardict-details-dirs"/> for details about &app_t; directories and configuration file.
</para>
<para>This option is only available in &winedition; of &app_t;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--portable-mode</term>
<listitem>
<para>Activate portable mode, see <xref linkend="stardict-portable"/>. 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.
</para>
<para>This option is only available in &winedition; of &app_t;.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="stardict-details-dictmanage">
<title>Dictionary Management</title>
<para>To manage the dictionaries, click the <guibutton>Manage dictionaries</guibutton> button at the bottom-right corner of the Main window, or click
the <guibutton>Main menu</guibutton> button and choose <guimenuitem>Dict manage</guimenuitem>.
</para>
<para>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.
</para>
<para>&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"</para>
</sect2>
<sect2 id="stardict-details-help">
<title>Help</title>
<para>Inside &app_t; you may open documentation either by pressing the <keycombo><keycap>F1</keycap></keycombo> key or by clicking the <guibutton>Main menu</guibutton> button, then the <guimenuitem>Help</guimenuitem> 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 <application>Help Browser</application>. 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.
</para>
<para>In other editions of &app_t; documentation is available in html format. You need to configure Web browser to view documentation, see <xref linkend="stardict-prefs-network-web-browser"/>. 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.
</para>
<para>
In &winedition; of &app_t; the default language corresponds to the language selected in the <guilabel>Regional and Language Options</guilabel> dialog.
</para>
<tip>
<title>Changing default language</title>
<para>Open <guilabel>Control Panel</guilabel>, <guilabel>Regional and Language Options</guilabel>.
<guilabel>Regional and Language Options</guilabel> dialog pops up. On the <guilabel>Regional Options</guilabel> tab select a language in the <guilabel>Stardards and formats</guilabel> group.
</para>
</tip>
<para>
You may override the default language with the LANGUAGE environment variable.
</para>
<para>
Normally, help files can be found in the <filename>C:\Program Files\StarDict\help</filename> directory. Each directory corresponds to one language. Directories are named after language codes.
</para>
</sect2>
<sect2 id="stardict-details-dirs">
<title>&app; directories</title>
<para>&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 <filename>stardict-dirs.cfg</filename> file.
Overriding &app; directories is useful for debugging,
preparing special configurations like &app;-portable for Windows,
an ordinary user does not need this.
</para>
<para>
&app_t; searches for the <filename>stardict-dirs.cfg</filename> file in the <varname>user_config_dir</varname> directory. You may override location of the <filename>stardict-dirs.cfg</filename> file with <varname>STARDICT_DIRS_CONFIG_FILE</varname> environment variable or with <parameter class='command'>--dirs-config</parameter> command line option. Command line option takes the highest precedence, then the environment variable is inspected, and finally the file in the <varname>user_config_dir</varname> directory. The first specified file wins, it will be probed as a configuration file. If load fails, no other files will be tried.
</para>
<para>The <filename>stardict-dirs.cfg</filename> file is a .ini-like config file. The syntax of .ini files is described in detail in the <ulink url="http://freedesktop.org/wiki/Specifications/desktop-entry-spec">Desktop Entry Specification</ulink>.
All keys must belong to <quote>general</quote> group.
</para>
<tip>
<para>Do not forget to double backslash characters in values. Backslash is used as path separator in Windows.
</para>
</tip>
<para>Example of <filename>stardict-dirs.cfg</filename> file for Windows:
<programlisting>
<![CDATA[
[general]
data_dir=C:\\Program Files\\StarDict
dll_dir=C:\\StarDict\\msvc_2008\\Debug
plugin_dir=C:\\StarDict\\msvc_2008\\Debug
]]>
</programlisting>
</para>
<variablelist>
<title>&app; directories</title>
<varlistentry>
<term>user_config_dir
</term>
<listitem>
<para>A directory of configuration files.</para>
<para>Windows default: <filename>C:\Documents and Settings\%USERNAME%\Application Data\StarDict</filename>.
</para>
<para>Other default: <filename>~/.stardict</filename>.
</para>
<para>Environment variable: <varname>STARDICT_CONFIG_PATH</varname>.
</para>
<para><filename>stardict-dirs.cfg</filename> key: user_config_dir.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>user_cache_dir
</term>
<listitem>
<para>User cache directory.</para>
<para>Windows default: <filename>C:\Documents and Settings\%USERNAME%\Temporary Internet Files\stardict</filename>.
</para>
<para>Other default: <filename>~/.cache/stardict</filename>.
</para>
<para><filename>stardict-dirs.cfg</filename> key: user_cache_dir.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>data_dir
</term>
<listitem>
<para>Data directory.
</para>
<para>Windows default: <filename>C:\Program Files\StarDict</filename>.
</para>
<para>Other default: <filename>/usr/share/stardict</filename>.
</para>
<para><filename>stardict-dirs.cfg</filename> key: data_dir.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>dll_dir
</term>
<listitem>
<para>A directory of hook dlls, in &winedition; only.
</para>
<para>Windows default: <varname>data_dir</varname>.
</para>
<para><filename>stardict-dirs.cfg</filename> key: dll_dir.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>plugin_dir
</term>
<listitem>
<para>A directory of &app; plugins.
</para>
<para>Windows default: <varname>data_dir</varname> + <filename>"/plugins"</filename>.
</para>
<para>Other default: <filename>/usr/lib/stardict/plugins</filename>.
</para>
<para><filename>stardict-dirs.cfg</filename> key: plugins_dir.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>help_dir
</term>
<listitem>
<para>A directory of help files, in all editions except &gnomeedition;.
</para>
<para>Default: <varname>data_dir</varname> + <filename>"/help"</filename>.
</para>
<para><filename>stardict-dirs.cfg</filename> key: help_dir.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>log_dir
</term>
<listitem>
<para>A directory for log files.
</para>
<para>Windows default: <filename>C:\Documents and Settings\%USERNAME%\Local Settings\Temp\StarDict</filename>.
</para>
<para>Other default: <filename>/var/tmp/stardict</filename>.
</para>
<para><filename>stardict-dirs.cfg</filename> key: log_dir.
</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>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 <filename>conf.h</filename> file for details on how the default value is calculated.
</para>
</note>
</sect2>
<sect2 id="stardict-details-logging">
<title>Logging</title>
<para>&app_t; may log messages into a file. By default logging is turned off, you may enable it specifing non-zero log level with <parameter class='command'>--log-level</parameter> command line option, see <xref linkend="stardict-details-command-line"/>.
</para>
<para>
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.
</para>
<para>
For default location of the log directory see <xref linkend="stardict-details-dirs"/>, log_dir parameter. &app_t; log files are named like <filename>stardict-<replaceable>process_number</replaceable>.log</filename>. 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.
</para>
</sect2>
<sect2 id="stardict-details-GUI-lang">
<title>Interface language</title>
<para>
This section describes the algorithm used to select interface language in &app_t;.
</para>
<orderedlist>
<listitem>
<anchor id="GUILangStarDictLoader" xreflabel="1"/>
<para>
Retrieve <varname>STARDICTLANG</varname> environment variable. Goto <xref linkend="GUILangSetLANG"/> if the variable is defined.
</para>
</listitem>
<listitem>
<anchor id="GUILangUserDefLocale" xreflabel="2"/>
<para>
Retrieve the user default locale
(to set the default locale:
<menuchoice>
<guibutton>Control Panel</guibutton>
<guibutton>Regional and Language Options</guibutton>
<guibutton>Regional Options</guibutton>
<guilabel>Standards and formats</guilabel>
<guilabel>Language</guilabel>
</menuchoice>).
If locale is not defined, use "en".
</para>
</listitem>
<listitem>
<anchor id="GUILangSetLANG" xreflabel="3"/>
<para>
Assign the language code to the <varname>LANG</varname> environment variable.
</para>
</listitem>
The steps below are based on comments in this function. -->
<listitem>
<anchor id="GUILangGetLANGUAGE" xreflabel="4"/>
<para>
Retrieve the value of the environment variable <varname>LANGUAGE</varname>.
This is a GNU extension. Its value can be a colon-separated list of locale names.
If defined, goto <xref linkend="GUILangAvailableTransl"/>.
</para>
</listitem>
<listitem>
<anchor id="GUILangGetPOSIXVars" xreflabel="5"/>
<para>
The value of the environment variable <varname>LC_ALL</varname>, <varname>LC_xxx</varname>, or <varname>LANG</varname>.
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 <xref linkend="GUILangAvailableTransl"/>.
</para>
</listitem>
<listitem>
<anchor id="GUILangGetSystemLangs" xreflabel="6"/>
<para>
A system-dependent preference list of languages. Its value can be a
colon-separated list of locale names.
If defined, goto <xref linkend="GUILangAvailableTransl"/>.
</para>
</listitem>
<listitem>
<anchor id="GUILangGetDefaultLocale" xreflabel="7"/>
<para>
A system-dependent default locale name.
If defined, goto <xref linkend="GUILangAvailableTransl"/>.
</para>
</listitem>
<listitem>
<anchor id="GUILangAvailableTransl" xreflabel="8"/>
<para>
Processes the found value as a colon-separated list of language codes. Select the first available language. If none is available, select no translation.
</para>
</listitem>
</orderedlist>
<warning>
<para>Steps <xref linkend="GUILangGetLANGUAGE"/> through <xref linkend="GUILangAvailableTransl"/> describe translation selection algorithm of the gettext package. The actual procedure may be different.
</para>
</warning>
<para>
The best way to specify interface language of &app_t; is to define <varname>STARDICTLANG</varname> environment variable. It should contain language code. See <filename class="directory">$StarDictDataDir/locale</filename> for the list of supported languages.
</para>
</sect2>
<sect2 id="stardict-details-dictionaries">
<title>&app; dictionaries</title>
<para>
&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.
</para>
<note>
<para>Almost all files constituting a dictionary are binary. It does not make sense to open them in a text editor. A notable exception is <filename>.ifo</filename> file, it contains dictionary description.
</para>
</note>
<variablelist>
<title>Index dictionary files and directories</title>
<varlistentry>
<term><replaceable>dictname</replaceable>.ifo
</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.idx or <replaceable>dictname</replaceable>.idx.gz
</term>
<listitem>
<para>Index of words available in the dictionary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.dict or <replaceable>dictname</replaceable>.dict.dz
</term>
<listitem>
<para>Main content of the dictionary — articles.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.syn
</term>
<listitem>
<para>Index of synonyms. Optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.idx.oft
</term>
<listitem>
<para>Cache for the index file. This file is created by &app_t; to speedup dictionaries loading. You should not redistribute this file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.syn.oft
</term>
<listitem>
<para>Cache for the synonyms file. This file is created by &app_t; to speedup dictionaries loading. You should not redistribute this file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.idx.clt
</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.syn.clt
</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>res.rifo, res.ridx, res.rdic
</term>
<listitem>
<para>Files of resource database. It contains resources like images, sound and video files used in the dictionary. Optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>res.ridx.oft
</term>
<listitem>
<para>Cache for the resource index file. This file is created by &app_t; to speedup resource database loading. You should not redistribute this file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>res
</term>
<listitem>
<para>A directory containing dictionary resources. This is alternative to <filename>res.rifo</filename>, <filename>res.ridx</filename>, <filename>res.rdic</filename> collection of files. Optional.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Tree dictionary files</title>
<varlistentry>
<term><replaceable>dictname</replaceable>.ifo
</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.tdx or <replaceable>dictname</replaceable>.tdx.gz
</term>
<listitem>
<para>A word list forming a tree.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>dictname</replaceable>.dict or <replaceable>dictname</replaceable>.dict.dz
</term>
<listitem>
<para>Main content of the dictionary — articles.</para>
</listitem>
</varlistentry>
</variablelist>
<sect3 id="stardict-details-dictionaries-dirs">
<title>Directories</title>
<para>This section describes directories where &app_t; searches dictionaries.
</para>
<para>Under <productname>Unix</productname>, &app_t; searches <filename>~/.stardict/dic</filename> and <filename>/usr/share/stardict/dic</filename> directories for index dictionaries and <filename>~/.stardict/treedict</filename> and <filename>/usr/share/stardict/treedict</filename> 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 <filename><varname>$(datadir)</varname>/dic</filename> for index dictionaries and <filename><varname>$(datadir)</varname>/treedict</filename> for tree dictionaries. Here <varname>$(datadir)</varname> is an <application>autoconf</application> directory variable.
</para>
<para>Under <productname>Windows</productname>, &app_t; searches <filename>C:\Program Files\StarDict\dic</filename> for index dictionaries and <filename>C:\Program Files\StarDict\treedict</filename> for tree dictionaries, assuming that &app_t; was installed into <filename>C:\Program Files\StarDict</filename>. If you've install &app_t; into a different directory, replace <filename>C:\Program Files\StarDict</filename> with real installation path.
</para>
<para>Under <productname>Windows</productname>, you may overwrite <varname>$data_dir</varname> variable, see <xref linkend="stardict-details-dirs"/>. By default it matches the &app_t; installation directory. In this case &app_t; will search <filename><varname>$data_dir</varname>\dic</filename> for index dictionaries and <filename><varname>$data_dir</varname>\treedict</filename> for tree dictionaries.
</para>
<note>
<para>All directories are processed recusively.
</para>
</note>
</sect3>
</sect2>
</sect1>
<sect1 id="stardict-portable">
<title>&app_port;</title>
<para>&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.
</para>
<para>
&app_port_t; relies on the <ulink url="http://portableapps.com" type="http">PortableApps.com Platform</ulink>. 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 <application>&app; Editor portable</application>. You may change interface language of the menu and &app_port_t;.
To do that click
<menuchoice>
<guibutton>Options</guibutton>
<guimenu>Language</guimenu>
</menuchoice>
and select the desired language.
</para>
<figure id="portable-apps-menu-fig">
<title>PortableApps.com menu</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/portable_apps_menu.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>PortableApps.com menu with &app_port_t;.</phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<sect2 id="stardict-portable-differences">
<title>Differences from non-portable version</title>
<para>
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.
</para>
<variablelist>
<title>&app_port; features</title>
<varlistentry>
<term>WordPick Adobe Acrobat plugin
</term>
<listitem>
<para>WordPick Adobe Acrobat plugin is disabled in portable version. Portable application policies forbids to modify the host machine.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Run &app_t; when Windows starts
</term>
<listitem>
<para>This option is disabled in portable version. It does not make sense to autostart application residing on removable storage.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="stardict-portable-install">
<title>Installing &app_port;</title>
<para>
This section describes &app_port_t; installation procedure.
</para>
<orderedlist>
<listitem>
<para>
Download and install <ulink url="http://portableapps.com" type="http">PortableApps.com Suite</ulink> on a USB flash drive or wherever you want.
</para>
</listitem>
<listitem>
<para>
Download &app_port_t; package from <ulink url="https://sourceforge.net/projects/stardict/files/" type="http">&app; website</ulink>. The package file ends with <filename>.paf.exe</filename>, for example, <filename>StarDictPortable-stardict.sourceforge.com_3.0.2.paf.exe</filename>.
</para>
</listitem>
<listitem>
<para>
Launch PortableApps.com menu.
</para>
</listitem>
<listitem>
<para>
Click
<menuchoice>
<guibutton>Options</guibutton>
<guimenu>Install a New Apps</guimenu>
</menuchoice>.
Select &app_port_t; package you've just downloaded, click <guibutton>OK</guibutton> and proceed with installer.
</para>
</listitem>
<listitem>
<para>
When installation completes, you will have two new items in the menu: &app_port_t; and <application>&app; Editor portable</application>. You are ready to use &app_port_t;.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="stardict-portable-no-menu">
<title>Launching &app_port; directly</title>
<para>
You may use &app_port_t; without PortableApps.com menu. In the <filename class="directory">$PortableAppsRoot\PortableApps\StarDictPortable-stardict.sourceforge.com</filename> directory you may find two executables: <filename>StarDictPortable.exe</filename> and <filename>StarDictEditorPortable.exe</filename>, they start &app_port_t; and <application>&app; Editor Portable</application> respectively. <varname>$PortableAppsRoot</varname> here is the directory where PortableApps.com suite was installed, normally this is the root of a drive, like <filename>X:\</filename>.
</para>
<para>
You may pass parameters to &app_port_t; as with normal &app_t;, see <xref linkend="stardict-details-command-line"/>. This maybe useful to enable logging, for example.
</para>
<caution>
<para>
Do not start files in the <filename class="directory">$PortableAppsRoot\PortableApps\StarDictPortable-stardict.sourceforge.com\App\StarDict</filename> 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.
</para>
</caution>
</sect2>
<sect2 id="stardict-portable-GUI-lang">
<title>Interface language</title>
<para>
This section describes the algorithm used to select interface language in &app_port_t;.
</para>
<orderedlist>
<listitem>
<anchor id="GUILangPortableAppsLang" xreflabel="1"/>
<para>Inspect PortableApps.com suite interface language
(<menuchoice>
<guibutton>Options</guibutton>
<guimenu>Language</guimenu>
</menuchoice>).
If the language is not selected, goto <xref linkend="GUILangSettingsFile"/>.
If the language is "en_US", goto <xref linkend="GUILangLanguageVariable"/>.
Check if &app_t; provides translation to the specified language. Goto <xref linkend="GUILangLanguageVariable"/> if yes, and goto <xref linkend="GUILangSettingsFile"/> otherwise.
</para>
</listitem>
<listitem>
<anchor id="GUILangSettingsFile" xreflabel="2"/>
<para>
Read the <filename class="directory">$PortableAppsRoot\PortableApps\StarDictPortable-stardict.sourceforge.com\Data\settings\StarDictPortableSettigns.ini</filename> file. Inspect value of the <varname>STARDICTLANG</varname> option in the <varname>Language</varname> section. If the option is not specified, goto <xref linkend="GUILangLaunchStarDict"/>. If the value is "en_US", goto <xref linkend="GUILangLanguageVariable"/>. Check if &app_t; provides translation to the specified language. Goto <xref linkend="GUILangLanguageVariable"/> if yes, and goto <xref linkend="GUILangLaunchStarDict"/> otherwise.
</para>
</listitem>
<listitem>
<anchor id="GUILangLanguageVariable" xreflabel="3"/>
<para>
Assign the language code to the <varname>STARDICTLANG</varname> environment variable.
</para>
</listitem>
<listitem>
<anchor id="GUILangLaunchStarDict" xreflabel="4"/>
<para>
Launch &app_t; executable, namely <filename>stardict.exe</filename>.
For subsequent steps see <xref linkend="stardict-details-GUI-lang"/>.
</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
<sect1 id="stardict-troubleshooting">
<title>Troubleshooting</title>
<para>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 <parameter class='command'>--message-level</parameter> command line option, see <xref linkend="stardict-details-command-line"/>.
</para>
<para>To see standard output and standard error on Windows, start &app_t; from windows console and pass non-zero parameter to the <parameter class='command'>--message-level</parameter> 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.
</para>
<figure id="stardict-windows-console-fig">
<title>Starting &app_t; from windows console</title>
<screenshot>
<mediaobject>
<imageobject><imagedata fileref="figures/stardict_windows_console.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Starting &app_t; from windows console with --message-level option specified. Typical &app_t; output. </phrase>
</textobject>
</mediaobject>
</screenshot>
</figure>
<para>In some cases, &app_t; prints nothing to console or console is not available.
Then turn on logging function, see <xref linkend="stardict-details-logging"/> for details.
</para>
<para>If &app_t; fails to start, it's recommended to set the output message level to the highest value so you can see all produced messages. They may help in diagnosing the cause of the problem.
&app_t; loads a number of plug-ins at startup.
A broken plug-in may crash or hang the entire application.
Each plug-in prints <computeroutput>Loading <symbol>PLUG-IN NAME</symbol> plug-in...</computeroutput> at the very begging of the plug-in initialization process. <computeroutput><symbol>PLUG-IN NAME</symbol> plug-in loaded.</computeroutput> message marks the end of the initialization process. If you do not see the paired message, the plug-in definitely fails to load.
Plug-ins normally print error messages, they may help you to identify and fix the problem.
On the other hand, you may simply remove the misbehaving plug-in. Just remove the corresponding library.
All plug-in are optional, &app_t; will work without plug-ins.
</para>
<para>Typical &app_t; output:
<screen>
[debug] Loading StarDict configuration...
[debug] StarDict configuration loaded.
[debug] Loading skin...
[debug] Skin loaded.
[debug] Loading Man plug-in...
Man plug-in loaded.
[debug] Loading WordNet dict rendering plug-in...
WordNet dict rendering plug-in loaded.
[debug] Loading Wiki data parsing plug-in...
Wiki data parsing plug-in loaded.
[debug] Loading Spelling plug-in...
Spelling plugin loaded.
[debug] Loading Gucharmap plug-in...
Gucharmap plug-in loaded.
[debug] Loading QQWry plug-in...
QQWry plug-in loaded.
[debug] Loading Dict.cn plug-in...
Dict.cn plug-in loaded.
[debug] Loading WordNet data parsing plug-in...
WordNet data parsing plug-in loaded.
[debug] Loading Festival plug-in...
Festival plug-in loaded.
[debug] Loading XDXF data parsing plug-in...
XDXF data parsing plug-in loaded.
[debug] Loading HTML data parsing plug-in...
HTML data parsing plug-in loaded.
[debug] Loading Espeak plug-in...
Espeak plug-in loaded.
[debug] Loading PowerWord data parsing plug-in...
PowerWord data parsing plug-in loaded.
bookname: StarDict dictionary, wordcount 9
</screen>
</para>
</sect1>
<sect1 id="stardict-projects">
<title>Related Projects</title>
<para>
&app_t; would not be possible without many other projects' contributions. Here is a short list of
projects that helped &app_t;.
</para>
<sect2 id="stardict-projects-stardict1.3">
<sect2info>
<authorgroup>
<author>
<firstname>Ma</firstname>
<surname>Su'an</surname>
<affiliation>
<address><email>msa@wri.com.cn</email></address>
</affiliation>
</author>
</authorgroup>
</sect2info>
<title>StarDict 1.31</title>
<para>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.</para>
</sect2>
<sect2 id="stardict-projects-stardict1.33-plus">
<sect2info>
<authorgroup>
<author>
<firstname>Opera</firstname>
<surname>Wang</surname>
<affiliation>
<address><email>Opera.Wang@motorola.com</email></address>
</affiliation>
</author>
</authorgroup>
</sect2info>
<title>StarDict 1.33+</title>
<para>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.</para>
</sect2>
<sect2 id="stardict-projects-dictd">
<title>The DICT Project</title>
<para>Many dictd dictionaries have been ported to &app_t;.
dictzip, which came from dictd, is also used by &app_t;.</para>
<para>
To find more information about the DICT Project, please visit
<ulink url="http://www.dict.org" type="http">www.dict.org</ulink>.
</para>
</sect2>
<sect2 id="stardict-projects-quick">
<title>*Quick</title>
<para>Many wquick dictionaries have been ported to &app_t;.</para>
<para>
To find more information about *Quick, please visit
<ulink url="http://www.futureware.at/quick.htm" type="http">*Quick</ulink>.
</para>
</sect2>
<sect2 id="stardict-projects-blowfish">
<sect2info>
<authorgroup>
<author>
<firstname>Terrence</firstname>
<surname>Miao</surname>
<affiliation>
<address><email>terence_miao@email.com</email></address>
</affiliation>
</author>
</authorgroup>
</sect2info>
<title>The Blowfish Project</title>
<para>The Blowfish Project provided the Oxford English-Chinese dictionary.</para>
<para>
To find more information about the Blowfish Project, please visit the
<ulink url="http://igloo.its.unimelb.edu.au/Blowfish/" type="http">Blowfish Project Web site</ulink>.
</para>
</sect2>
<sect2 id="stardict-projects-xdict">
<sect2info>
<authorgroup>
<author>
<firstname>Fu</firstname>
<surname>Jianjun</surname>
<affiliation>
<address><email>fujianjun@163.net</email></address>
</affiliation>
</author>
</authorgroup>
</sect2info>
<title>XDICT</title>
<para>XDICT's dictionary has been ported to &app_t;.</para>
</sect2>
<sect2 id="stardict-projects-cdict">
<title>cdict5</title>
<para>cdict5's dictionary has been ported to &app_t;.</para>
<sect3 id="stardict-projects-cdict-xcdict-tcltk">
<sect3info>
<authorgroup>
<author>
<firstname>Leon</firstname>
<surname>Liang</surname>
<affiliation>
<address><email>Liang.Lu@CERN.CH</email></address>
</affiliation>
</author>
</authorgroup>
</sect3info>
<title>xcdict-tcltk</title>
<para><ulink url="http://luliang.dhs.org/" type="http">xcdict-tcltk Web site</ulink></para>
</sect3>
<sect3 id="stardict-projects-cdict-cdict5-v1.3">
<sect3info>
<authorgroup>
<author>
<firstname>Borg</firstname>
<surname>LU</surname>
<affiliation>
<address><email>dystopia@iname.com</email></address>
</affiliation>
</author>
</authorgroup>
</sect3info>
<title>cdict5 v1.3</title>
<para>
To find more information about the cdict5 Project, please visit the
<ulink url="http://www.freshports.org/chinese/cdict5/" type="http">cdict5 on freshports</ulink>.
</para>
</sect3>
</sect2>
<sect2 id="stardict-projects-cedict">
<sect2info>
<authorgroup>
<author>
<firstname>Paul</firstname>
<surname>Denisowski</surname>
<affiliation>
<address><email>cedict@chinesetools.com</email></address>
</affiliation>
</author>
</authorgroup>
</sect2info>
<title>CEDICT</title>
<para>CEDICT's dictionary has been ported to &app_t;.</para>
<para>
To find more information about the CEDICT Project, please visit the
<ulink url="http://www.mandarintools.com/cedict.html" type="http">CEDICT Project Web site</ulink>.
</para>
</sect2>
<sect2 id="stardict-projects-cffd">
<sect2info>
<authorgroup>
<author>
<firstname>Kong</firstname>
<surname>Hui</surname>
<affiliation>
<address><email>konghui@xinhuanet.com</email></address>
</affiliation>
</author>
</authorgroup>
</sect2info>
<title>CFFD</title>
<para>&app_t;'s icon was created with this software. CFFD also provided some useful
information to me. </para>
<para>
To find more information about the CFFD Project, please visit the
<ulink url="http://cffd.cosoft.org.cn" type="http">CFFD Project Web site</ulink>.
</para>
</sect2>
</sect1>
<sect1 id="stardict-authors">
<sect1info>
<authorgroup>
<author>
<firstname>Hu</firstname>
<surname>Zheng</surname>
<affiliation>
<address><email>huzheng001@gmail.com</email></address>
</affiliation>
</author>
</authorgroup>
</sect1info>
<title>Developers</title>
<para>
To find more information about
&app_t;, please visit the <ulink
url="http://stardict-4.sourceforge.net" type="http">StarDict Web
site</ulink>.
</para>
<para>
Send all comments, suggestions, and bug reports to
Hu Zheng (<email>huzheng001@gmail.com</email>).
</para>
<para>
Македонскиот превод е направен од Новица Наков
(<email>acivon@mail.com.mk</email>). Сите коментари
и предлози околу овој превод праќајте ги на горната адреса.
</para>
<para>
Nederlandse vertaling is gedaan door Ruud Slaats
(<email>ruudslaats@eurotechgroup.nl</email>). Stuur al u commentaar, suggesties betreffende deze vertaling naar <email>ruudslaats@eurotechgroup.nl</email>.
</para>
<para>
На русский язык переведено Александром Мурыгиным
(<email>murygin@aitoc.com</email>). Пожалуйста присылайте все комментарии и
предложения относящиеся к этому переводу на этот адрес.
</para>
<para>
На українську мову перекладено Сергієм Дубиком
(<email>dubyk@library.lviv.ua</email>). Будь ласка присилайте всі коментарі та
пропозиції, що відносяться до цього перекладу, на цю адресу.
</para>
<para>
中文翻译由耿军军完成
(<email>geng82@163.com</email>)。请将有关本翻译的评论和建议发到我的邮箱。
</para>
<para>
繁體中文翻譯由陳曉陽完成
(<email>roy.chan@debian.org.hk</email>)。請將有關本翻譯的評論和建議電郵給我。
</para>
<para>
Latin translation was done by ME
(<email>MYNAME@MYADDRESS</email>). Please send all comments and
suggestions regarding this translation to SOMEWHERE.
</para>
-->
</sect1>
</article>