1 files changed, 214 insertions, 0 deletions
diff --git a/doc/kbabel/catman.docbook b/doc/kbabel/catman.docbook
new file mode 100644
index 00000000..a55d46ec
--- /dev/null
+++ b/doc/kbabel/catman.docbook
@@ -0,0 +1,214 @@
+<!-- <?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="using-catalogmanager">
+
+<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>Using &catalogmanager;</title>
+<anchor id="catalogmanager"/>
+
+<screenshot>
+<screeninfo>Screenshot of &catalogmanager;</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="snap_catalogmanager.png" format="PNG"/>
+</imageobject>
+<textobject><phrase>Screenshot of &catalogmanager;</phrase></textobject>
+</mediaobject>
+</screenshot>
+<para>
+The Catalog Manager merges two folders into one tree and displays
+all the <acronym>PO</acronym>  and <acronym>POT</acronym> files in
+these folders.  The display allows you to easily see if a new
+template has been added or an old one has been removed.  Some
+information is shown along with each file name: total number of
+entries, number of fuzzy entries, number of untranslated entries, the
+date of the last revision and the last translator of the file.
+</para>
+
+<important><para>
+KBabel's Catalog Manager is meant for projects structured like KDE,
+where the <acronym>POT</acronym> and <acronym>PO</acronym> files
+share a same name, save the extensions. However this is not the
+case of &GNU; projects and of many projects structured like &GNU; ones.
+Typically in such projects, the <acronym>PO</acronym> file is named
+following the language code and so is very different than the name
+of the <acronym>POT</acronym> files. Also such projects have
+one <acronym>POT</acronym> file sharing a directory with all its
+translated <acronym>PO</acronym> files. Unfortunately, all these reasons
+mean that the Catalog Manager is <emphasis>not</emphasis> suitable for
+such projects. (See <ulink url="http://bugs.kde.org/show_bug.cgi?id=76495">KDE bug #76495</ulink>.)
+</para></important>
+
+<para>
+To make it easier for you to find files that need work or are
+missing the status of each file is also displayed using an icon:
+</para>
+
+<itemizedlist>
+   <listitem>
+      <para>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="catalogmanager_ok.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject> All the messages in this file are translated.</para>
+   </listitem>
+   <listitem>
+      <para>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="catalogmanager_needwork.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+Some of the messages in this file are fuzzy or untranslated
+      </para>
+   </listitem>
+   <listitem>
+      <para>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="catalogmanager_missing.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+This file does not exist in the folder of the <acronym>PO</acronym> files.
+      </para>
+   </listitem>
+   <listitem>
+      <para>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="catalogmanager_broken.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+This file contains syntax errors.
+      </para>
+   </listitem>
+   <listitem>
+      <para>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="catalogmanager_reload.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+Information about this file is being currently updated. When the update is
+finished, it will get one of the icons listed above to reflect its state.
+      </para>
+   </listitem>
+</itemizedlist>
+
+<para>
+If an icon is marked with this icon
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="catalogmanager_nopot.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>, like
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="catalogmanager_nopot_ok.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>,
+it indicates that this file or folder does not exist in the
+folder of the <acronym>POT</acronym> files.</para>
+
+<para> You can mark or unmark a file by selecting <guimenuitem>Toggle
+Marking</guimenuitem> in the context menu of a file.</para>
+
+<para>If you want to toggle or remove all markings in a folder,
+press the right mouse button over the folder and select
+<guimenuitem>Toggle Markings</guimenuitem> or <guimenuitem>Remove
+Markings</guimenuitem>.  The markings are automatically saved when
+leaving &kbabel;.</para>
+
+<para>To open a file either double-click on the file, select
+<menuchoice><guimenuitem>Open</guimenuitem></menuchoice> from the
+context menu or press either <keycap>Return</keycap> or <keycombo
+action="simul">&Ctrl;<keycap>O</keycap> </keycombo>.</para>
+
+<para>You can configure the &catalogmanager; by
+<menuchoice><guimenu>Project</guimenu><guimenuitem>
+Configure...</guimenuitem></menuchoice>.
+See section <link linkend="preferences-project-settings">Project Settings</link> for more
+details.</para>
+
+<sect1 id="catman-features">
+<title>&catalogmanager; Features</title>
+<para>
+Besides the main feature for opening the files in &kbabel; &catalogmanager;
+supports number of other features for maintaining a tree of
+<acronym>PO</acronym>-files.
+</para>
+
+<sect2 id="catman-find">
+<title>Find and replace in multiple files</title>
+<para>
+One of the most requested features for &kbabel; was a possibility to search and replace in
+multiple files at once. &catalogmanager; supports this feature with
+a tight integration with &kbabel;
+</para>
+</sect2>
+
+<sect2 id="catman-statistics">
+<title>Statistics</title>
+<para>
+&catalogmanager; can show you a number of statistics about a single file
+or about the whole folders. The statistics contain number of files,
+how many of the files have their templates, how many templates are missing.
+It also counts number of messages in the files and shows statistics about
+how large parts of the messages are translated, fuzzy-translated or
+untranslated.
+</para>
+</sect2>
+
+<sect2 id="catman-syntax">
+<title>Checking the syntax</title>
+<para>
+This allows you to check the syntax of multiple <acronym>PO</acronym>-files
+using <command>msgfmt</command>. If a file fails this check, it cannot
+be used for generating a <acronym>MO</acronym>-file for binary distribution.
+Such an incorrect file will typically result in failing compilation of the package
+the <acronym>PO</acronym>-file belongs to.
+</para>
+</sect2>
+
+<sect2 id="catman-commands">
+<title>User-defined commands</title>
+<para>
+Because &catalogmanager; cannot provide any functionality you would like
+to use, you can extend it by defining your own commands.
+</para>
+<!-- ### TODO: we should lik to preferences-project-file-commands too -->
+<para>
+There are two sets of commands. One for folders and one for single files.
+You can set them in <link
+linkend="preferences-project-folder-commands">configuration dialog </link> and
+access by pressing &RMB; on an entry in the file list.</para>
+</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 
+-->