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/kdeadmin@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

18 files changed, 1233 insertions, 0 deletions

diff --git a/doc/kpackage/Makefile.am b/doc/kpackage/Makefile.am
new file mode 100644
index 0000000..085981d
--- /dev/null
+++ b/doc/kpackage/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kpackage/bsdloc.png b/doc/kpackage/bsdloc.png
new file mode 100644
index 0000000..b498b7f
--- /dev/null
+++ b/doc/kpackage/bsdloc.png
diff --git a/doc/kpackage/debaptloc.png b/doc/kpackage/debaptloc.png
new file mode 100644
index 0000000..965b2ef
--- /dev/null
+++ b/doc/kpackage/debaptloc.png
diff --git a/doc/kpackage/debloc.png b/doc/kpackage/debloc.png
new file mode 100644
index 0000000..bcc96d0
--- /dev/null
+++ b/doc/kpackage/debloc.png
diff --git a/doc/kpackage/handle.png b/doc/kpackage/handle.png
new file mode 100644
index 0000000..58caf2d
--- /dev/null
+++ b/doc/kpackage/handle.png
diff --git a/doc/kpackage/index.docbook b/doc/kpackage/index.docbook
new file mode 100644
index 0000000..2112411
--- /dev/null
+++ b/doc/kpackage/index.docbook
@@ -0,0 +1,1229 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" 
+"dtd/kdex.dtd" [
+  <!ENTITY kappname "&kpackage;">
+  <!ENTITY package "kdeadmin">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &kpackage; Handbook</title>
+<authorgroup>
+<author>
+<firstname>Toivo</firstname>
+<surname>Pedaste</surname>
+<affiliation>
+<address><email>toivo@ucs.uwa.edu.au</email></address>
+</affiliation>
+</author>
+
+<othercredit role="reviewer">
+<firstname>Lauri</firstname>
+<surname>Watts</surname>
+<affiliation>
+<address><email>lauri@kde.org</email></address>
+</affiliation>
+<contrib>Reviewer</contrib>
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2000</year>
+<holder>Toivo Pedaste</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2006-12-04</date>
+<releaseinfo>3.5.5</releaseinfo>
+
+<abstract><para>&kpackage; is a &GUI; interface to the
+<acronym>RPM</acronym>, Debian, Slackware and BSD package
+managers.</para></abstract>
+
+<keywordset>
+<keyword>kpackage</keyword>
+<keyword>package</keyword>
+<keyword>package manager</keyword>
+<keyword>RPM</keyword>
+<keyword>deb</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kpackage; is a &GUI; interface to the <acronym>RPM</acronym>,
+Debian, Slackware and <acronym>BSD</acronym> package managers.  &kpackage; is part of the K Desktop
+Environment and, as a result, it is designed to integrate with the &kde;
+file manager. </para>
+
+</chapter>
+
+<chapter id="onscreen-fundamentals">
+
+<title>Onscreen Fundamentals</title>
+
+<para>&kpackage; has two panels. The left panel displays a tree of the
+installed and available packages, the right panel displays information
+on the packages.</para>
+
+
+<sect1 id="the-main-window-left">
+<title>The Main Window - Package Tree</title>
+
+<para>When &kpackage; is started normally (that is it has not been
+invoked via drag and drop and has not been given any parameters) it
+displays two panels with the package tree on the left, this tree shows
+installed packages and optionally new and updated packages as
+well.</para>
+
+<screenshot>
+<screeninfo>&kpackage; Left Panel</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="left.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Left Panel - Package Tree</phrase>
+</textobject>
+<caption>
+<para>Left Panel - Package Tree</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para>The left panel displays the list of packages, the tabs along
+the top determines which packages are displayed:</para>
+
+<itemizedlist>
+
+<listitem><para><guilabel>Installed</guilabel> - Show installed packages</para></listitem>
+
+<listitem><para><guilabel>Updated</guilabel> - Show packages for which newer versions are available</para></listitem>
+
+<listitem><para><guilabel>New</guilabel> - Show uninstalled packages</para></listitem>
+
+<listitem><para><guilabel>All</guilabel> - All packages</para></listitem>
+
+</itemizedlist>
+<para>Below the tabs is the <guilabel>Search</guilabel> line, this filters the package tree so that only those packages whose name or summary contains the search string are displayed.</para>
+
+<para>The package tree is based on the sections of the distribution
+and shows summary information about the packages:</para>
+<itemizedlist>
+
+<listitem><para><guilabel>Package</guilabel> - Name of the package</para></listitem>
+<listitem><para><guilabel>Mark</guilabel> - Shows a tick if the package has
+been marked. Marking allows multiple packages to be installed or
+uninstalled at once using the buttons located below the package tree.</para></listitem>
+<listitem><para><guilabel>Summary</guilabel>- A short description of the package.</para></listitem>
+<listitem><para><guilabel>Size</guilabel>- The package size</para></listitem>
+<listitem><para><guilabel>Version</guilabel> - The package version</para></listitem>
+<listitem><para><guilabel>Old Version</guilabel> - If the package updates an installed package, the
+version of the old package</para></listitem>
+
+</itemizedlist>
+
+<para>The packages have graphical labels to indicate their state, an
+image representing the package type means an installed package, a
+<guilabel>N</guilabel> indicates an available package and a <guilabel>U</guilabel>
+means a package that can upgrade an installed package.</para>
+
+<para>A single package is selected by clicking on the name. Clicking on
+the dot in the <guilabel>Mark</guilabel> column marks the package with a
+tick, a second click unmarks it, while <keycombo
+action="simul">&Shift;<mousebutton>left</mousebutton></keycombo> click
+can be used to mark a range of packages and <keycombo
+action="simul">&Ctrl;<mousebutton>left</mousebutton></keycombo> click
+can be used to add and remove marks on packages.</para>
+
+<para>Selecting a package from the tree displays information about it in
+the right panel.</para>
+
+</sect1>
+
+<sect1 id="package-information-panel">
+<title>The Main Window - Package Information Panel</title>
+
+<para>The right panel has tabs for displaying three different types of
+information about selected packages </para>
+
+<itemizedlist>
+<listitem>
+<screenshot>
+<screeninfo>&kpackage; Right Panel - Properties</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="right-prop.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Right Panel - Package Properties</phrase>
+</textobject>
+<caption>
+<para>The <guilabel>Properties</guilabel> tab which displays
+information on the selected package. In the dependency information there are
+hyper-links to the packages listed, installed packages are in standard font,
+uninstalled but available packages are in italic and dependencies that aren't
+available are normal text.</para>
+</caption>
+</mediaobject>
+</screenshot>
+</listitem>
+
+<listitem>
+
+<screenshot>
+<screeninfo>&kpackage; Right Panel - Properties</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="right-files.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Right Panel - The Files in the Package</phrase>
+</textobject>
+<caption>
+<para>The <guilabel>File List</guilabel> tab shows the files in the
+package and for installed packages (provided the information is
+available) shows the state of the
+files. Files that exist are marked with a tick, those that are
+missing are marked with a cross.</para>
+
+</caption>
+</mediaobject>
+</screenshot>
+
+</listitem>
+
+<listitem>
+<screenshot>
+<screeninfo>&kpackage; Right Panel - Properties</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="right-change.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Right Panel - The Files in the Package</phrase>
+</textobject>
+<caption>
+<para>The <guilabel>Change Log</guilabel> tab shows the change log
+for the package.</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+</listitem>
+
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="installing-packages">
+<title>Installing Packages</title>
+
+<para>To install a package you can</para>
+<itemizedlist>
+<listitem>
+<para>locate the package you wish to install in &konqueror;, drag it
+onto a running copy of &kpackage;</para>
+</listitem>
+<listitem>
+<para>click on a package file in &konqueror; and start a new copy of
+&kpackage;</para>
+</listitem>
+<listitem>
+<para>use on the <guimenu>Open</guimenu> menu items in
+&kpackage;</para>
+</listitem>
+<listitem>
+<para>selecting an available package in the package tree</para>
+</listitem>
+</itemizedlist>
+
+<para>For a selected package, use the buttons in the right panel, the
+<guibutton>Fetch</guibutton> button will fetch the package from a remote
+source and display detailed information, the
+<guibutton>Install</guibutton> button pops up the installation
+window. </para>
+
+<para>For marked packages, use the
+<guibutton>Install Marked</guibutton> button on the left panel,
+which pops up the install
+window.</para>
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="install.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Install Dialog</phrase>
+</textobject>
+<caption>
+<para>Install Dialog</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para>The install window lists the packages to be selected to
+be installed in a panel in the top left, if Debian <acronym>APT</acronym>
+is being used the packages needed to satisfy any dependencies are
+also shown. Below this there are a set of check boxes which set options for
+the install program. For <acronym>RPM</acronym> packages the options
+are:</para>
+<itemizedlist>
+<listitem>
+<para><guilabel>Upgrade</guilabel> - Will upgrade any already
+installed package.</para>
+</listitem>
+<listitem>
+<para><guilabel>Replace Files</guilabel> - Install  the  packages  even
+if they replace files from other, already installed, packages.</para>
+</listitem>
+<listitem>
+<para><guilabel>Check Dependencies</guilabel> - Verify dependencies.</para>
+</listitem>
+<listitem>
+<para><guilabel>Test (do not install)</guilabel></para>
+</listitem>
+</itemizedlist>
+
+<para>For Debian <acronym>APT</acronym> the options are:</para>
+<itemizedlist>
+<listitem>
+<para><guilabel>Download only</guilabel> - Fetch the packages but
+don't install them.</para>
+</listitem>
+<listitem>
+<para><guilabel>No download</guilabel> - Only use packages that
+are locally available</para>
+</listitem>
+<listitem>
+<para><guilabel>Ignore missing</guilabel> - Do the install even if
+some packages are missing</para>
+</listitem>
+<listitem>
+<para><guilabel>Ignore hold</guilabel> - Ignore holds that have been
+placed on packages</para>
+</listitem>
+<listitem>
+<para><guilabel>Allow Unauthenticated</guilabel> - Ignore any requirements that
+the packages must be signed.</para>
+</listitem>
+<listitem>
+<para><guilabel>Assume yes</guilabel> - Answer yes for any questions
+the install program would ask.</para>
+</listitem>
+<listitem>
+<para><guilabel>Test (do not install)</guilabel></para>
+</listitem>
+</itemizedlist>
+
+<para>The <guibutton>Install</guibutton> button will start the
+actual install. Normally the install window will be deleted after
+a successful install but if the
+<guibutton>Keep this window</guibutton> check box is selected the
+window will stay around.</para>
+
+<para>The panel on the right is an integrated
+terminal window in which the installation programs are run, for
+interactive installation programs the interaction is done in this
+window. </para>
+
+</sect1>
+
+<sect1 id="uninstalling-packages">
+<title>Uninstalling Packages</title>
+
+<para>A selected package can be uninstalled by using the
+<guibutton>Uninstall</guibutton> button in the right panel, the
+<guibutton>Uninstall Marked</guibutton> in the right panel
+can be used to uninstall marked packages. The buttons bring
+up the uninstall window.</para>
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="uninstall.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Uninstall Dialog</phrase>
+</textobject>
+<caption>
+<para>Uninstall Dialog</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para>The
+<guibutton>Uninstall</guibutton> button in the window causes the
+packages to be uninstalled, and the right panel provides an integrated
+terminal window for the uninstall program.</para>
+
+<para>For <acronym>RPM</acronym> packages the options
+are:</para>
+<itemizedlist>
+<listitem>
+<para><guilabel>Use scripts</guilabel> - Execute any unistall scripts</para>
+</listitem>
+<listitem>
+<para><guilabel>Check Dependencies</guilabel> - Verify dependencies.</para>
+</listitem>
+<listitem>
+<para><guilabel>Test (do not uninstall)</guilabel></para>
+</listitem>
+</itemizedlist>
+
+<para>For Debian <acronym>APT</acronym> the options are:</para>
+<itemizedlist>
+<listitem>
+<para><guilabel>Purge Config Files</guilabel> - Remove any package
+configuration files.</para>
+</listitem>
+<listitem>
+<para><guilabel>Assume yes</guilabel> - Answer yes for any questions
+the install program would ask.</para>
+</listitem>
+<listitem>
+<para><guilabel>Test (do not uninstall)</guilabel></para>
+</listitem>
+</itemizedlist>
+
+
+</sect1>
+
+<sect1 id="integrating-available-packages-in-the-tree">
+<title>Integrating available packages in the tree</title>
+
+<para>Access to available packages is setup in the menu with <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kpackage;...</guimenuitem></menuchoice>.
+</para>
+
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="handle.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Package Handler Panel</phrase>
+</textobject>
+<caption>
+<para>Package Handler Panel </para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para>The top part of the panel has the <guilabel>Remote Host</guilabel>
+box which allows &kpackage; to operate on the packages on a remote computer,
+this functionality requires <command>ssh</command> and is only available
+when using Debian apt. The name of the remote
+computer is entered into the combobox and &kpackage; will access
+it when the <guilabel>Use remote host</guilabel> checkbox is
+selected.</para>
+
+<para>The rest of the panel allows the enabling and disabling of
+the various package types that &kpackage; can handle. If a package
+type is enabled the <guibutton>Location of Packages</guibutton> button
+will bring up a dialog for setting the location of available packages.
+If the programs required for handling a package type is not available the package
+type will be automatically disabled.
+</para>
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="rpmloc.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>RPM Location Dialog</phrase>
+</textobject>
+<caption>
+<para>RPM Location Dialog</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para>For <acronym>RPM</acronym> packages &kpackage; can read a
+folder containing packages and add these to the package tree as
+either new or updated packages. It is possible to examine or install
+these packages from the package tree. By default the information about
+the packages is extracted from the standard format of the file names and
+so it is necessary to use the <guibutton>Examine</guibutton> button to
+see the full description, it is possible though to set an option so that
+for local folders each package file is read, this is slower but
+gives a full description.</para>
+
+<para>The <acronym>RPM</acronym> locations dialog allows the specification
+of folders containing <acronym>RPM</acronym> packages, it's divided
+up into a number of tabbed panels for convenience of management. Each
+line in the panel specifies a folder, the <guilabel>Use</guilabel>
+checkbox is selected the folder is used, otherwise it's ignored.
+The text entry field can take either a folder path or an <command>ftp</command>
+URL.  The <guilabel>Subfolders</guilabel> checkbox determines
+whether subfolders are searched for packages. The <guibutton>...</guibutton>
+button will pop up a folder selection dialog.</para>
+
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="debaptloc.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Debian Apt Location Dialog</phrase>
+</textobject>
+<caption>
+<para>Debian Apt Location Dialog</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para><guilabel>APT: Debian</guilabel> means that Debian packages
+are handled using the <command>deb-apt</command> command which
+can automatically fetch packages from repositories and
+resolve dependencies.</para>
+
+<para>The location of
+uninstalled package repositories can be set in the "A" panel, this is
+used to write the <filename>/etc/apt/sources.list</filename> file
+which controls where <command>deb-apt</command> searches for packages,
+each entry corresponds to a line in the file, if the
+<guilabel>Use</guilabel> checkbox is not set the line is commented
+out.</para>
+
+<para>The "D" panel allows the specification of folders containing
+Debian packages.</para>
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="debloc.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Debian DPKG Location Dialog: L and P panels</phrase>
+</textobject>
+<caption>
+<para>Debian DPKG Location Dialog: L and P panels</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+
+<para>DPKG: Debian means that packages are handled using <command>dpkg</command>
+command, there are three ways of accessing available packages, these can be
+selected in three different types of location setting panels. </para>
+
+<itemizedlist>
+<listitem>
+<para>The "I" panel specifies the location of the Debian package tree
+and selects the
+distribution and architecture. &kpackage; will look in the standard
+places for the Package files describing the available packages and these
+packages are then added to the package tree and can be examined or
+installed</para>
+</listitem> 
+<listitem>
+<para>The "P" panel specifies the location of the Debian distribution along with the
+<filename>Packages</filename> files for the parts of the distribution that are of
+interest. If the <command>dselect</command> program is being
+used then the file <filename>/var/lib/dpkg/available</filename> can be
+used as a <filename>Packages</filename> file that describes the distribution that
+<command>dselect</command> uses.</para>
+</listitem>
+<listitem><para>The "D" panel specifies folders that are handled in the same way as with
+<acronym>RPM</acronym> packages.</para></listitem>
+</itemizedlist>
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="slackloc.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>Slackware Location Dialog</phrase>
+</textobject>
+<caption>
+<para>Slackware Location Dialog</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para>For Slackware packages there is very little information stored on
+installed packages, but it is possible to use a
+<filename>PACKAGE.TXT</filename> file as a source of information about
+the installed packages. The <filename>PACKAGES.TXT</filename> file is
+the equivalent of a Debian Packages file and Slackware distributions are
+structured with a folder tree containing the <literal
+role="extension">.tgz</literal> packages and a
+<filename>PACKAGES.TXT</filename> file that describes the
+packages.</para>
+
+<para>As with Debian distributions the packages in a Slackware
+distribution can be integrated into the package tree. Unfortunately the
+Slackware packages don't carry version information so it is not possible
+to tell with available packages are newer than installed ones.</para>
+
+<itemizedlist>
+<listitem><para>The "I" panel is the location of a
+<filename>PACKAGES.TXT</filename> file which is used to provided information on
+the installed packages</para></listitem>
+<listitem><para>The "P" panels can be used to specify the location of
+distributions with the folder tree containing the <literal
+role="extension">.tgz</literal> files and the location of the corresponding
+<filename>PACKAGES.TXT</filename> file</para></listitem>
+<listitem><para>The "D" panels are for folders that do
+<emphasis>not</emphasis> have a corresponding <filename>PACKAGES.TXT</filename>
+fi
+le</para></listitem>
+</itemizedlist>
+
+<screenshot>
+<screeninfo>&kpackage; Install dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="bsdloc.png" format="PNG"/> </imageobject>
+<textobject>
+<phrase>BSD Location Dialog</phrase>
+</textobject>
+<caption>
+<para>BSD Location Dialog</para>
+</caption>
+</mediaobject>
+</screenshot>
+
+<para>For <acronym>BSD</acronym> packages &kpackage; will understand a
+packages distribution folder that contains an
+<filename>INDEX</filename> file (which describes all the packages) and
+also contains an <filename>All</filename> folder (with all the
+package files in it). </para>
+
+<para>The "Ports" panel gives the location of the ports tree in
+the file system </para>
+<para>The "Packages" panel allows the specifying the location of packages
+folders &ie; those containing <filename>INDEX</filename>
+files</para>
+
+<para>For remote folders and package files (&ie; those fetched via
+&FTP;) &kpackage; will do caching, the packages are by default cached in
+<filename>~/.kpackage</filename> and the folders in
+<filename>~/.kpackage/dir</filename>.</para>
+
+<note><para>For the handling of remote (&FTP;) folders to work, it
+may be necessary to not have the <guilabel>FTP Proxy</guilabel> set in the
+Browser Settings.</para></note>
+
+</sect1>
+
+<sect1 id="Searching">
+<title>Searching</title>
+<sect2>
+<title>Package Search Line</title>
+
+<screenshot>
+  <screeninfo>&kpackage; Search Line</screeninfo>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="searchl.png" format="PNG"/> </imageobject>
+    <textobject>
+      <phrase>Search Line</phrase>
+    </textobject>
+    <caption>
+      <para>Search Line</para>
+    </caption>
+  </mediaobject>
+</screenshot>
+
+<para>The Search line filters the package tree so that only those packages whose name or summary contains the search string are displayed.</para>
+</sect2>
+
+
+<sect2>
+  <title>Find Package</title>
+  
+  <screenshot>
+    <screeninfo>&kpackage; Find Package</screeninfo>
+    <mediaobject>
+      <imageobject>
+	<imagedata fileref="search.png" format="PNG"/> </imageobject>
+      <textobject>
+	<phrase>Find Package</phrase>
+      </textobject>
+      <caption>
+	<para>Find Package</para>
+	</caption>
+      </mediaobject>
+    </screenshot>
+    
+    <para>The <guilabel>Find Package</guilabel> dialog searches the names 
+    of the packages in the package tree and moves to the next matching package.
+    If <guilabel>Sub string</guilabel> is not set then it will find only exact 
+    matches against packages names. If <guilabel>Wrap search</guilabel> is not
+    set the search doesn't wrap around the end of the package tree.
+  </para>
+</sect2>
+
+<sect2>
+  <title>Find File</title>
+  
+  <screenshot>
+    <screeninfo>&kpackage; Find File</screeninfo>
+    <mediaobject>
+      <imageobject>
+	<imagedata fileref="searchf.png" format="PNG"/> </imageobject>
+      <textobject>
+	<phrase>Find File</phrase>
+      </textobject>
+      <caption>
+	<para>Find File</para>
+      </caption>
+    </mediaobject>
+  </screenshot>
+  
+  <para>The <guilabel>Find File</guilabel> dialog searches for files the names of 
+    which contain the search string. 
+    The columns in the display are:</para>
+    <itemizedlist>
+      <listitem>
+	<para><guilabel>Installed</guilabel> - Ticked if it is an installed package.</para>
+      </listitem>
+      <listitem>
+	<para><guilabel>Type</guilabel> - The type of the package.</para>
+      </listitem>
+      <listitem>
+	<para><guilabel>Package</guilabel> - The name of the package</para>
+      </listitem>
+      <listitem>
+	<para><guilabel>File Name</guilabel> - The name of the matched file</para>
+      </listitem>
+    </itemizedlist>
+    <para>Only the files in installed packages are shown unless <guilabel>Also search uninstalled packages</guilabel> is set, this will only work with Debian APT
+      packages and only if the <command>apt-file</command> command is installed.
+      The database used by the <command>apt-file</command> command is updated
+      by the <guimenuitem>Apt-File Update</guimenuitem> menu item.
+    </para>
+
+</sect2>
+
+
+</sect1>
+
+<sect1 id="Misc">
+  <title>Misc</title>
+  <sect2>
+    <title>Root Access</title>
+
+    <para>&kpackage; requires <systemitem class="username">root</systemitem>
+      access for installing/uninstalling packages, this can be can be done by
+      running &kpackage; as <systemitem class="username">root</systemitem>,
+      say by using &kdesu;.</para>
+
+    <para>Alternatively, if &kpackage; is running as a normal user it will
+      try to run the install/uninstall programs as root by logging in to a
+      pseudo terminal, it will use either <command>su</command>, <command>sudo</command> or
+      <command>ssh</command> to do this and if needed it will pop up a
+      prompt window where the <systemitem class="username">root</systemitem>
+      password or <command>ssh</command> key can be typed. For this to work the root prompt has to end in
+      <prompt># </prompt>. The <guimenuitem>Keep password</guimenuitem> option causes &kpackage; to
+      remember the password that is entered. </para>
+  <screenshot>
+    <screeninfo>&kpackage; Password prompt</screeninfo>
+    <mediaobject>
+      <imageobject>
+	<imagedata fileref="root-prompt.png" format="PNG"/> </imageobject>
+      <textobject>
+	<phrase>Password prompt</phrase>
+      </textobject>
+      <caption>
+	<para>Password prompt</para>
+      </caption>
+    </mediaobject>
+  </screenshot>
+
+  </sect2>
+
+
+  <sect2>
+    <title>Drag and Drop</title>
+
+    <para>&kpackage; makes use of the &kde; Drag and Drop protocol. This
+      means that you can drag and drop packages onto &kpackage; to open
+      them. Dropping a file onto the <guilabel>Find File</guilabel> dialog
+      will find the package that contains the file.</para>
+
+  </sect2>
+</sect1>
+
+</chapter>
+<chapter id="menus">
+
+<title>Menus</title>
+
+<para>This describes the &kpackage; menus. </para>
+
+<sect1 id="file-menu">
+<title><guimenu>File</guimenu> menu</title>
+
+<para>The items in the <guimenu>File</guimenu> menu are:</para>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul">
+&Ctrl;<keycap>O</keycap></keycombo></shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Open...</guimenuitem></menuchoice></term>
+<listitem><para>Brings up file selector for local and &FTP;
+files</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>File</guimenu>
+<guisubmenu>Open Recent</guisubmenu></menuchoice></term>
+<listitem><para>A list of the most recently open package files</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul">
+&Ctrl;<keycap>F</keycap></keycombo></shortcut>
+<guimenu>File</guimenu><guimenuitem>Find
+Package...</guimenuitem></menuchoice></term>
+<listitem><para>Search the installed package list for a package, the name
+of which contains the entered string </para> </listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>File</guimenu>
+<guimenuitem>Find File...</guimenuitem></menuchoice></term>
+<listitem><para>Produces a list of packages that contain the entered
+file name, selecting a line will display the information on that
+package. It behaves slightly differently for <acronym>RPM</acronym>
+(where you have to enter the exact file name) and <abbrev>DEB</abbrev>
+(where you can enter a regular expression).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><shortcut><keycap>F5</keycap></shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Reload</guimenuitem></menuchoice></term>
+<listitem><para>Reread the package data and rebuild the package
+tree</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><shortcut><keycombo action="simul">
+&Ctrl;<keycap>Q</keycap></keycombo></shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem></menuchoice></term>
+<listitem><para>Quit &kpackage; </para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="packages-menu">
+<title><guimenu>Packages</guimenu> menu</title>
+
+<para>The items in the <guimenu>Packages</guimenu> menu are:</para>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice><shortcut>
+<keycombo action="simul">&Alt;<keycap>Left</keycap>
+</keycombo></shortcut>
+<guimenu>Packages</guimenu>
+<guimenuitem>Back</guimenuitem></menuchoice></term>
+<listitem><para>Back button for navigation using the links in
+<guilabel>Properties</guilabel> entries in the right panel.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo action="simul">&Alt;<keycap>Right</keycap>
+</keycombo></shortcut>
+<guimenu>Packages</guimenu>
+<guimenuitem>Forward</guimenuitem></menuchoice></term>
+<listitem><para>Forward button for navigation using the links in
+<guilabel>Properties</guilabel> entries in the right panel.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Packages</guimenu>
+<guimenuitem>Expand Tree</guimenuitem></menuchoice></term>
+<listitem><para>Fully expands the packages tree</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Packages</guimenu>
+<guimenuitem>Collapse Tree</guimenuitem> </menuchoice></term>
+<listitem><para>Collapses the package tree so that only the tree structure is
+shown</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice> <guimenu>Packages</guimenu>
+<guimenuitem>Clear Marked</guimenuitem> </menuchoice></term>
+<listitem><para>Unmarks all packages</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice> <guimenu>Packages</guimenu>
+<guimenuitem>Mark All</guimenuitem> </menuchoice></term>
+<listitem><para>Marks all packages that are members of the selected view</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Package</guimenu>
+<guimenuitem>Install</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Install the currently selected package</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Package</guimenu>
+<guimenuitem>Install Marked</guimenuitem></menuchoice></term>
+<listitem>
+<para>Install all marked packages</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Package</guimenu>
+<guimenuitem>Uninstall</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Uninstall the currently selected package</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Package</guimenu>
+<guimenuitem>Uninstall Marked</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Uninstall all marked packages</para>
+</listitem>
+</varlistentry>
+
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="cache-menu">
+<title><guimenu>Cache</guimenu> menu</title>
+
+<para>The items in the <guimenu>Cache</guimenu> menu are: </para>
+<variablelist>
+<varlistentry>
+<term><menuchoice><guimenu>Cache</guimenu> <guimenuitem>Clear
+Package Folder Cache</guimenuitem></menuchoice></term>
+<listitem><para>Delete cached copies of remote package folders and Packages
+files</para> </listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Cache</guimenu><guimenuitem>Clear Package
+Cache</guimenuitem>
+</menuchoice></term>
+<listitem><para>Delete cached copies of remote package files that have been
+fetched</para> </listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="special-menu">
+<title><guimenu>Special</guimenu> menu</title>
+
+<para>The <guimenu>Special</guimenu> contains actions
+related to specific package types:</para>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Special</guimenu><guimenuitem>
+APT: Debian</guimenuitem>
+</menuchoice></term>
+<listitem>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Update</guilabel></term>
+<listitem><para>Update <command>apt</command> indexes from package
+repositories.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Upgrade</guilabel></term>
+<listitem><para>Upgrade the Debian installation to the latest versions
+of all the packages.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Fixup</guilabel></term>
+<listitem><para><command>apt</command> is extremely strict about
+dependencies, attempt to fixup dependency problems</para></listitem>
+</varlistentry>
+
+<varlistentry>
+  <term><guilabel>Apt-File Update</guilabel></term>
+  <listitem><para>Searching for uninstall files uses the <command>apt-file</command> command, this updates the database that <command>apt-file</command> uses.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</listitem>
+
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="settings-menu">
+<title><guimenu>Settings</guimenu> menu</title>
+
+<para>The items in the <guimenu>Settings</guimenu> menu are:</para>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Show
+Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem><para>Toggle displaying the toolbar</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Save
+Settings</guimenuitem></menuchoice></term>
+<listitem><para>Save options immediately</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure
+Shortcuts...</guimenuitem></menuchoice></term>
+<listitem><para>The standard &kde; dialog for setting shortcut
+keys</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure
+Toolbars...</guimenuitem></menuchoice></term>
+<listitem><para>The standard &kde; dialog for configuring tool
+bars</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kpackage;...</guimenuitem></menuchoice></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Types</guilabel></term>
+<listitem><para>Which package types to handle, Debian using DPKG and
+Debian using APT are listed separately, it is not a good idea to
+enable both at the same time. It also sets whether to access
+a remote host for Debian apt.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Cache</guilabel></term>
+<listitem><para>Controls caching of remote (&FTP;ed)  folders and Package
+files.</para>
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Cache Remote Package Folders</guilabel></term>
+<listitem><para>Whether to cache remote (&FTP;ed)  folders and Package
+files.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Cache Remote Package Files</guilabel></term>
+<listitem><para>Whether to cache remote package files that have been fetched
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Cache Folder</guilabel></term>
+<listitem><para>Where to cache package files and folders
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>misc</guilabel></term>
+<listitem>
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Execute Privileged Commands Using</guilabel></term>
+<listitem><para>Use <command>su</command>, <command>sudo</command> or
+<command>ssh</command> for running privileged commands. For remote Debian APT <command>ssh</command>
+is always used.</para> </listitem> 
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Verify file list</guilabel></term>
+<listitem><para>If set the list of files in the package is checked to see if
+they are actually installed</para> </listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Read information from all local package files</guilabel></term>
+<listitem><para>If set all the files from a (local) package folder are read
+instead of just using the files names, this is slower but shows more
+information.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+
+</variablelist>
+</sect1>
+
+<sect1 id="help-menu">
+<title><guimenu>Help</guimenu> menu</title>
+
+<para>The items in the <guimenu>Help</guimenu> menu are: </para>
+
+&help.menu.documentation;
+
+</sect1>
+
+<sect1 id="toolbar">
+<title>Toolbar</title>
+
+<itemizedlist>
+<listitem><para><guiicon>Open</guiicon></para></listitem>
+<listitem><para><guiicon>Back</guiicon></para></listitem>
+<listitem><para><guiicon>Forward</guiicon></para></listitem>
+<listitem><para><guiicon>Expand Tree</guiicon></para></listitem>
+<listitem><para><guiicon>Collapse Tree</guiicon></para></listitem>
+<listitem><para><guiicon>Find Package</guiicon></para></listitem>
+<listitem><para><guiicon>Find File</guiicon></para></listitem>
+<listitem><para><guiicon>Reload</guiicon></para></listitem>
+</itemizedlist>
+</sect1>
+</chapter>
+
+<chapter id="credits-and-licenses">
+<title>Credits and Licenses</title>
+
+<para>
+&kpackage;
+</para>
+
+<para>Documentation copyright 2005 Toivo Pedaste
+<email>toivo@ucs.uwa.edu.au</email></para>
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="how-to-obtain-kpackage">
+<title>How to obtain &kpackage;</title>
+
+&install.intro.documentation;
+
+<para>For information on how to obtain and compile it see <ulink
+url="http://www.kde.org/install-source.html">
+http://www.kde.org/install-source.html</ulink></para>
+
+<para>There is more information on compilation at <ulink
+url="http://www.kde.org/compilationfaq.html">
+http://www.kde.org/compilationfaq.html</ulink></para>
+
+<para>There is a web page at <ulink
+url="http://www.general.uwa.edu.au/u/toivo/kpackage">
+http://www.general.uwa.edu.au/u/toivo/kpackage</ulink></para>
+
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>For installing &kpackage; you need:</para>
+
+<itemizedlist>
+<listitem><para>&Qt; 3 and &kde; 3</para></listitem>
+</itemizedlist>
+
+<para>For listing Debian packages no other software is needed but to
+install and uninstall the packages you need:</para>
+
+<itemizedlist>
+<listitem><para>the <command>dpkg</command> package
+manager or</para></listitem>
+
+<listitem><para> <command>apt-get</command> and
+<command>apt-cache</command></para></listitem>
+</itemizedlist>
+
+<para>For <acronym>BSD</acronym> packages you need the package
+management programs: </para>
+
+<itemizedlist>
+<listitem><para><command>pkg_info</command></para></listitem>
+<listitem><para><command>pkg_add</command></para></listitem>
+<listitem><para><command>pkg_delete</command></para></listitem>
+</itemizedlist>
+
+<para>For Slackware packages  you need: </para>
+
+<itemizedlist>
+<listitem><para><command>installpkg</command> </para></listitem>
+<listitem><para><command>removepkg</command></para></listitem>
+</itemizedlist>
+
+<para>For dealing with Redhat packages you need:</para>
+
+<itemizedlist>
+
+<listitem><para><command>rpm</command> </para></listitem>
+</itemizedlist>
+
+<para>For &kpackage; to work correctly with <acronym>RPM</acronym>
+packages the <acronym>RPM</acronym> database must be initialized. If
+typing <userinput><command>rpm</command>
+<option>-qa</option></userinput> gives an error about
+<computeroutput>unable to open....</computeroutput> then try
+<userinput><command>rpm</command>
+<option>--rebuilddb</option></userinput>.</para>
+
+</sect1>
+
+</appendix>
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag: nil
+sgml-shorttag: t
+End:
+-->
+
diff --git a/doc/kpackage/install.png b/doc/kpackage/install.png
new file mode 100644
index 0000000..958dc44
--- /dev/null
+++ b/doc/kpackage/install.png
diff --git a/doc/kpackage/left.png b/doc/kpackage/left.png
new file mode 100644
index 0000000..ad665c2
--- /dev/null
+++ b/doc/kpackage/left.png
diff --git a/doc/kpackage/right-change.png b/doc/kpackage/right-change.png
new file mode 100644
index 0000000..303dd62
--- /dev/null
+++ b/doc/kpackage/right-change.png
diff --git a/doc/kpackage/right-files.png b/doc/kpackage/right-files.png
new file mode 100644
index 0000000..e986caf
--- /dev/null
+++ b/doc/kpackage/right-files.png
diff --git a/doc/kpackage/right-prop.png b/doc/kpackage/right-prop.png
new file mode 100644
index 0000000..94b01de
--- /dev/null
+++ b/doc/kpackage/right-prop.png
diff --git a/doc/kpackage/root-prompt.png b/doc/kpackage/root-prompt.png
new file mode 100644
index 0000000..b954963
--- /dev/null
+++ b/doc/kpackage/root-prompt.png
diff --git a/doc/kpackage/rpmloc.png b/doc/kpackage/rpmloc.png
new file mode 100644
index 0000000..52b03b1
--- /dev/null
+++ b/doc/kpackage/rpmloc.png
diff --git a/doc/kpackage/search.png b/doc/kpackage/search.png
new file mode 100644
index 0000000..4d77cc1
--- /dev/null
+++ b/doc/kpackage/search.png
diff --git a/doc/kpackage/searchf.png b/doc/kpackage/searchf.png
new file mode 100644
index 0000000..135f89b
--- /dev/null
+++ b/doc/kpackage/searchf.png
diff --git a/doc/kpackage/searchl.png b/doc/kpackage/searchl.png
new file mode 100644
index 0000000..fc47d07
--- /dev/null
+++ b/doc/kpackage/searchl.png
diff --git a/doc/kpackage/slackloc.png b/doc/kpackage/slackloc.png
new file mode 100644
index 0000000..210cf6b
--- /dev/null
+++ b/doc/kpackage/slackloc.png
diff --git a/doc/kpackage/uninstall.png b/doc/kpackage/uninstall.png
new file mode 100644
index 0000000..b30ed5c
--- /dev/null
+++ b/doc/kpackage/uninstall.png