Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdesdk@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 517 insertions, 0 deletions

diff --git a/doc/kbabel/dictionaries.docbook b/doc/kbabel/dictionaries.docbook
new file mode 100644
index 00000000..a9e5ed70
--- /dev/null
+++ b/doc/kbabel/dictionaries.docbook
@@ -0,0 +1,517 @@
+<!-- <?xml version="1.0" ?>
+<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> -->
+<!-- Uncomment the previous two lines to validate this document -->
+<!-- standalone.  Be sure to recomment them before attempting to -->
+<!-- process index.docbook -->
+
+<chapter id="dictionaries">
+
+<chapterinfo>
+<!-- Fill in this section if this document has a different author -->
+<authorgroup>
+<author>
+<personname><firstname></firstname><surname></surname></personname>
+</author>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</chapterinfo>
+
+<title>Dictionaries</title>
+
+<para>&kbabel; has 3 modes which can be used to search translated
+<acronym>PO</acronym> message strings:</para>
+
+<itemizedlist>
+     <listitem>
+       <para>Searching translation, using a translation database
+       </para>
+     </listitem>
+      <listitem>
+         <para>Rough translation
+	 </para>
+      </listitem>
+      <listitem>
+         <para>&kbabeldict;
+	 </para>
+      </listitem>
+</itemizedlist>
+
+<sect1 id="database">
+<!-- FIXME: settings -->
+<title>Translation database</title>
+
+<!-- ### TODO: only *one* file? Seems more to be four... -->
+<para>Translation database allows you to store translations in a
+database based on Berkeley Database IV, &ie; it is stored in a binary
+file on your disk. The database guarantees fast searching in a large
+number of translations.</para>
+
+<para>This mode is the one best integrated with &kbabel;. Besides
+searching and rough translation it also supports the following
+features:</para>
+
+<itemizedlist>
+<listitem>
+<para>Every new translation typed in the &kbabel; editor can be
+automatically stored in the database.</para>
+</listitem>
+<listitem>
+<para>This database can be used for <quote>diff</quote>-ing
+<acronym>msgid</acronym>.</para>
+</listitem>
+</itemizedlist>
+
+<para>Of course, the more translations are stored in the database, the
+more productive you can be. To fill the database, you can use the
+<guilabel>Database</guilabel> tab in the preferences dialog or you can
+turn on automatic addition of every translated messages on the same
+tab.</para>
+
+<sect2 id="database-settings">
+<title>Settings</title>
+<para>
+You can configure this searching mode and how it should be used by selecting
+<menuchoice>
+  <guisubmenu>Settings</guisubmenu>
+  <guisubmenu>Configure Dictionary</guisubmenu>
+  <guimenuitem>Translation Database</guimenuitem>
+</menuchoice>
+in &kbabel; menu.
+</para>
+<para>
+The <guilabel>Generic</guilabel> tab contains general settings for searching in the
+database.
+</para>
+<variablelist>
+  <varlistentry>
+    <term><guilabel>Search in whole database (slow)</guilabel></term>
+    <listitem>
+    <para>
+    Do not use <quote>good keys</quote>, search in the whole database.
+    This is slow, but will return the most precise results.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Search in list of "good keys" (best)</guilabel></term>
+    <listitem>
+    <para>
+    Use <quote>good keys</quote> strategy. This option will give you the
+    best tradeoff between speed and exact matching.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Return the list of "good keys" (fast)</guilabel></term>
+    <listitem>
+    <para>
+    Just return <quote>good keys</quote>, do not try to eliminate any more
+    texts. This is the fastest provided method, but can lead to a quite large
+    number of imprecise matches.
+    </para>
+    </listitem>
+  </varlistentry>
+<varlistentry>
+    <term><guibutton>Case sensitive</guibutton></term>
+    <listitem>
+    <para>
+    Distinguish case of letters when searching the text.
+    </para>
+    </listitem>
+  </varlistentry>
+<varlistentry>
+    <term><guibutton>Normalize white space</guibutton></term>
+    <listitem>
+    <para>
+    Skip unnecessary white space in the texts, so the searching will ignore small
+    differences of white space, &eg; number of spaces in the text.
+    </para>
+    </listitem>
+  </varlistentry>
+<varlistentry>
+    <term><guibutton>Remove context comment</guibutton></term>
+    <listitem>
+    <para>
+    Do not include context comments in search. You will want this to be turned on.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Character to be ignored</guilabel></term>
+    <listitem>
+    <para>Here you can enter characters, which should be ignored while searching.
+    Typical example would be accelerator mark, &ie; &amp; for &kde; texts.
+    </para>
+    </listitem>
+  </varlistentry>
+  </variablelist>
+<para>
+The <guilabel>Search</guilabel> tab contains finer specification for searching the text.
+You can define how to search and also allows to use another special way of searching
+called <emphasis><guilabel>Word substitution</guilabel></emphasis>. By substituting
+one or two words the approximate text can be found as well. For example, assume you
+are trying to find the text <userinput>My name is Andrea</userinput>.
+</para>
+<variablelist>
+  <varlistentry>
+    <term><guilabel>Equal</guilabel></term>
+    <listitem>
+    <para>
+    Text from database matches if it is the same as the searched string. In our example it can
+    be <emphasis>My name is &amp;Andrea</emphasis> (if &amp; is set as ignored character
+    in <guilabel>Characters to be ignored</guilabel> on <guilabel>Generic</guilabel> tab).
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Query is contained</guilabel></term>
+    <listitem>
+    <para>
+    Text from database matches if the searched string is contained in it. For our example it can
+    be <emphasis>My name is Andrea, you know?</emphasis>.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Query contains</guilabel></term>
+    <listitem>
+    <para>
+    Text from database matches if the searched string contains it. For our example it can
+    be <emphasis>Andrea</emphasis>. You can use this for enumerating the possibilities to
+    be found.
+    </para>
+    </listitem>
+  </varlistentry>
+<varlistentry>
+    <term><guibutton>Regular Expression</guibutton></term>
+    <listitem>
+    <para>
+    Consider searched text as a regular expression. This is mainly used for
+    &kbabeldict;. You can hardly expect regular expressions in PO files.
+    </para>
+    </listitem>
+  </varlistentry>
+<varlistentry>
+    <term><guibutton>Use one word substitution</guibutton></term>
+    <listitem>
+    <para>
+    If the query text contains less words than specified below, it also
+    tries to replace one of the words in the query. In our example it will
+    find <emphasis>Your name is Andrea</emphasis> as well.
+    </para>
+    </listitem>
+  </varlistentry>
+<varlistentry>
+    <term><guibutton>Max number of words in the query</guibutton></term>
+    <listitem>
+    <para>
+    Maximal number of words in a query to enable one word substitution.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Local characters for regular expressions</guilabel></term>
+    <listitem>
+    <para>
+    Characters to be considered part of regular expressions.
+    </para>
+    </listitem>
+  </varlistentry>
+  </variablelist>
+<note>
+<para>
+Two-word substitution is not implemented yet.
+</para>
+</note>
+</sect2>
+
+<sect2 id="database-fill">
+<title>Filling the database</title>
+<para>
+The <guilabel>Database</guilabel> tab allows to define where is the database stored on
+disk (<guilabel>Database folder</guilabel>) and if it should be used for automatic
+storing of the new translations (<guibutton>Auto add entry to database</guibutton>).
+In this case you should specify the author of the new translation in <guilabel>Auto added
+entry author</guilabel>.
+</para>
+<para>
+The rest of the tab allows you to fill the database from PO files that already exist. Use one
+of the buttons in the middle of the dialog box. The progress of the file load will be
+shown by progress bars below the buttons. The <guilabel>Repeated strings</guilabel>
+button should be used in the special case where one translated string is repeated many
+times, to prevent storing unnecessary copies. Here you can limit the stored strings.
+</para>
+<screenshot>
+<screeninfo>Filling the database</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="dbcan.png" format="PNG"/>
+</imageobject>
+<textobject><phrase>Filling the database by existing PO-files</phrase></textobject>
+</mediaobject>
+</screenshot></sect2>
+
+<sect2 id="database-goodkeys">
+<title>Defining good keys</title>
+<para>
+On the <guilabel>Good keys</guilabel> tab are the thresholds to specify how to fill 
+the list of good keys.
+<guilabel>Minimum number of query words in the key (%)</guilabel> specifies exactly that.
+Text will need to contain only this per cent of the words to qualify as good key. Opposite can
+be specified via <guilabel>Minimum number of words of the key also in the query (%)</guilabel>.
+The length of the words can be set by <guilabel>Max length</guilabel> spinbox.
+</para>
+<para>Searched text typically contains number of generic words, &eg; articles. You can
+eliminate the words based on the frequency. You can discard them by 
+<guilabel>Discard words more frequent than</guilabel> or consider as always present by
+<guilabel>frequent words are considered as in every key</guilabel>. This way the
+frequent words will be almost invisible for queries.
+</para>
+</sect2>
+</sect1>
+
+
+<sect1 id="auxiliary">
+<title>Auxiliary PO file</title>
+
+<para>This searching mode is based on matching the same original
+English string (the msgid) translated in some other language in an
+auxillary <acronym>PO</acronym> file.  It is very common for Romance
+<!-- ### TODO: is "Anglo-Saxon" not too Romance or too technical for an English text? -->
+languages to have similar words, similarly for Anglo-Saxon and
+Slavic ones.</para>
+
+<para>
+For example, say I wanted to translate the word
+<quote>on</quote>, from <filename>kdelibs.po</filename>, into Romanian
+but have no clue.  I look in the same file for French and find
+<foreignphrase lang="fr">actif</foreignphrase>, and in the Spanish one find
+<foreignphrase lang="es">activado</foreignphrase>.  So, I conclude that the best one in Romanian
+will be <foreignphrase lang="ro">active</foreignphrase>.
+(Of course, in English instead of <quote>on</quote> the word could have been
+<quote>active</quote> or <quote>activated</quote>,
+which would have made the translation process easier.)
+&kbabel; automates this task. Currently you can define only one auxiliary file to search.
+</para>
+
+<sect2 id="auxiliary-settings">
+<title>Settings</title>
+<para>
+You can configure this searching mode by selecting
+<menuchoice>
+  <guisubmenu>Settings</guisubmenu>
+  <guisubmenu>Configure Dictionary</guisubmenu>
+  <guimenuitem>PO Auxiliary</guimenuitem>
+</menuchoice>
+from the &kbabel; menu.</para>
+
+<para>In the <guilabel>Configure Dictionary PO Auxiliary</guilabel>
+dialog you can select the path to the auxiliary <acronym>PO</acronym>
+file.  To automate <acronym>PO</acronym>-file switching when you
+change current edited file there are many variables delimited by
+<literal>@</literal> char that are replaced by appropriate
+values:</para>
+
+<variablelist>
+  <varlistentry>
+    <term>@PACKAGE@</term>
+    <listitem><para>
+      The name of application or package currently being translated.
+      For example, it can expand to kbabel, kdelibs, konqueror
+      and so on.
+    </para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>@LANG@</term>
+    <listitem><para>
+      The language code.
+      For example can expand to: de, ro, fr etc.
+    </para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>@DIRn@</term>
+    <listitem><para>
+      where <quote>n</quote> is a positive integer.  This expands to
+      the <quote>n</quote>-th folder counted from the filename (right to 
+      left).
+    </para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>The edit line displays the actual path to the auxiliary
+<acronym>PO</acronym> file. While it is best to use the
+provided variables in a path it is possible to choose an absolute,
+real path to an existing <acronym>PO</acronym> file.  Let's take an
+example.</para>
+
+<para>I'm Romanian and I have some knowledge about French language and
+I work on &kde; translation.</para>
+
+<!-- ### TODO: check URL, especially the kde-l10n part -->
+<para>First step is to download a very fresh
+<filename>kde-l10n-fr.tar.bz2</filename> from the <ulink
+url="ftp://ftp.kde.org/pub/kde/snapshots/kde-l10n">&kde; &FTP;
+site</ulink> or to use the <acronym>CVS</acronym> system to put on my
+hard-disk a French translation tree. I do this into
+<filename>/home/clau/cvs-cvs.kde.org/kde-l10n/fr</filename>.</para>
+
+<para>My <acronym>PO</acronym> sources folder is in
+<filename>/home/clau/cvs-cvs.kde.org/kde-l10n/ro</filename>.  Do not
+forget to select <guilabel>PO Auxiliary</guilabel> as the default
+dictionary and check <guilabel>Automatically start search</guilabel>
+on the <guilabel>Search</guilabel> tab from &kbabel;'s
+<guilabel>Preferences</guilabel> dialog.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="compendium">
+<!-- FIXME: examples -->
+<title>PO compendium</title>
+
+<para>A compendium is a file containing a collection of all
+translation messages (pairs of <acronym>msgid</acronym> and
+<acronym>msgstr</acronym>) in a project, &eg; in &kde;. Typically,
+compendium for a given language is created by concatenating all
+<acronym>PO</acronym> files of the project for the
+language. Compendium can contain translated, untranslated and fuzzy
+messages. Untranslated ones are ignored by this module.  </para>
+
+<para>Similarly to Auxiliary <acronym>PO</acronym>, this searching
+mode is based on matching the <quote>same</quote> original string
+(<acronym>msgid</acronym>) in a compendium. Currently you can define
+only one compendium file to search.  </para>
+
+<para>This mode is very useful if you are not using the translation
+database and you want to achieve consistent translation with other
+translations. By the way, compendium files are much easier to share
+with other translators and even other translation projects because
+they can be generated for them as well.  </para>
+
+<sect2 id="compendium-settings">
+<title>Settings</title>
+
+<para>
+You can configure this searching mode by selecting
+<menuchoice>
+  <guisubmenu>Settings</guisubmenu>
+  <guisubmenu>Configure Dictionary</guisubmenu>
+  <guimenuitem>PO Compendium</guimenuitem>
+</menuchoice>
+in &kbabel;'s menu.
+</para>
+
+<para>In <guilabel>Configure Dictionary PO Compendium</guilabel>
+dialog you can select the path to a compendium file. To automate
+compendium file switching when you change the translation language,
+there is a variable delimited by <literal>@</literal> char which si
+replaced by appropriate value:</para>
+
+<variablelist>
+  <varlistentry>
+    <term>@LANG@</term>
+    <listitem><para>
+      The language code.
+      For example can expand to: de, ro, fr etc.
+    </para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>In the edit line is displayed the actual path to compendium
+<acronym>PO</acronym> file. While you had best use provided variables in
+path, it's possible to choose an absolute, real path to an existing
+<acronym>PO</acronym> file to be used as a compendium.</para>
+
+<!-- ### TODO: check URL, especially the kde-l10n part -->
+<para>A very fresh compendium for &kde; translation into &eg; French
+you can download <filename>fr.messages.bz2</filename> from the <ulink
+url="ftp://ftp.kde.org/pub/kde/snapshots/kde-l10n">&kde; &FTP;
+site</ulink>.  </para>
+
+<para>You can define how to search in the compendium using options
+below the path. They are divided into two groups: text-matching
+options, where you can specify how the text is compared and whether to
+ignore fuzzy translations, and message-matching options, which
+determine if the translation from compendium should be a substring of
+searching message or vice versa.</para>
+
+<variablelist>
+  <varlistentry>
+    <term><guilabel>Case sensitive</guilabel></term>
+    <listitem>
+    <para>
+    If the matching of message in compendium should distinguish between uppercase and lowercase letters.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Ignore fuzzy string</guilabel></term>
+    <listitem>
+    <para>
+    If the fuzzy messages in the compendium should be ignored for searching. The compendium can contain fuzzy messages, since it is typically created by concatenating the <acronym>PO</acronym> files of the project which can include fuzzy messages. Untranslated ones are ignored always (You can't search for translation in untranslated messages, right?)</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><guilabel>Only whole words</guilabel></term>
+    <listitem>
+    <para>
+    If the matching text should start and end at the boundaries of words.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>A text matches if it <guilabel>is equal to search text</guilabel></term> 
+    <listitem>
+    <para>
+    A text in compendium matches the search text only if it is exactly the same (of course using the options above).
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>A text matches if it <guilabel>is similar to search text</guilabel></term>
+    <listitem>
+    <para>
+    A text in compendium matches the search text only if it is <quote>similar</quote>. Both texts are compared by short chunks of letters (<quote>3-grams</quote>) and at least half of the chunks has to be same.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>A text matches if it <guilabel>contains search text</guilabel></term>
+    <listitem>
+    <para>
+    A text in compendium matches the search text if it contains the search text.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>A text matches if it <guilabel>is contained in search text</guilabel></term>
+    <listitem>
+    <para>
+    A text in compendium matches the search text if it is contained the search text.
+    </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>A text matches if it <guilabel>contains a word of search text</guilabel></term>
+    <listitem>
+    <para>
+    The texts are divided to words and a text in compendium matches the search text only if it contains some word from the search text.
+    </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+</sect2>
+</sect1>
+</chapter>
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab 
+-->
+