<!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
  <!ENTITY kappname "&kfind;" -- replace kapp here. This only *seems* redundant -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" -- change language only here -->
  <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
  %ents;
]>



<book lang="&language;">
<bookinfo>
<title>The &kfind; Handbook</title>
<authorgroup>
<author>
<firstname>Miroslav</firstname>
<surname>Flídr</surname>
<affiliation>
<address><email>flidr@kky.zcu.cz</email></address>
</affiliation>
</author>
<author>
<firstname>Martin</firstname>
<surname>Hartig</surname>
<affiliation>
<address><email>hartig@mathematik.uni-kl.de</email></address>
</affiliation>
</author>
<author>
<firstname>Mark</firstname>
<surname>Roberts</surname>
<affiliation>
<address><email>mar2@scigen.co.uk</email></address>
</affiliation>
</author>
</authorgroup>
<date>21/06/1998</date>
<releaseinfo>0.04.00</releaseinfo>
<abstract>
<para>This Handbook describes KFind Version 0.4</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>KFind</keyword>
<keyword>File searching</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para><emphasis remap="bf">Kfind</emphasis> looks for files matching search criteria within a directory hierarchy.</para>
<para>Often you know that a file is 'out there somewhere', but you can't remember where it is, even with a good effort.
So <emphasis remap="bf">KFind</emphasis> is exactly the tool for that problem. Having found 
the required file(s), you can:
<itemizedlist>
<listitem>
<para>save them,</para>
</listitem>
<listitem>
<para>delete them,</para>
</listitem>
<listitem>
<para>change their file properties,</para>
</listitem>
<listitem>
<para>store them to archives and/or</para>
</listitem>
<listitem>
<para>open the directory containing the file(s) in the file manager (<emphasis remap="bf">Kfm</emphasis>).</para>
</listitem>
</itemizedlist>
</para>
<para>I hope you find this program useful and I would appreciate any suggestions and comments.</para>
<para><literal remap="tt">Miroslav Flídr</literal>
<ulink url="mailto:flidr@kky.zcu.cz">flidr@kky.zcu.cz</ulink>.</para>
</chapter>

<chapter id="configuration">
<title>Configuration</title>
<para>Configuration is normally performed by means of the Preferences dialog;
see the user section of this manual for more details. A technical description
of <emphasis remap="bf">kfind</emphasis> configuration follows for interested parties:</para>
<para><emphasis remap="bf">Kfind</emphasis> reads configuration parameters from a configuration
file (normally <literal remap="tt">&tilde;/.kde/share/config/kfindrc</literal>).</para>
<para>This file contains information about saving search results, available
archivers and other configuration parameters; these parameters can be edited
from the <literal remap="tt">Kfind</literal> <emphasis remap="bf">Preferences</emphasis> dialog. </para>
<para><emphasis remap="bf">General information:</emphasis> the resource file consists of sections.
Each section is started by a header title in square braces e.g.<literal remap="tt">[Saving]</literal></para>
<para>Information following the header relates to a specific aspect of
<literal remap="tt">Kfind</literal> operation.</para>
<para><emphasis remap="bf">Saving configuration:</emphasis> The configuration file holds the filename
and format of the file to be used for saving search results. These parameters
are stored as follows:
<screen>[Saving]
Format=HTML
Filename=/root/result.html
</screen>

Where <literal remap="tt">Format</literal> entry can have values <literal remap="tt">HTML </literal>or <literal remap="tt">Plain Text</literal>.</para>
<para><emphasis remap="bf">Archiver configuration:</emphasis> Archivers available for <literal remap="tt">kfind</literal> are
specified in <emphasis remap="it">kfindrc</emphasis> entry <literal remap="tt">[Archiver Types]</literal> as follows:
<screen>[Archiver Types]
Archivers=tar;zip;zoo;
</screen>
</para>
<para>And each archiver is detaily described by its own entry:
<screen>[tar]
ExecOnCreate=tar cf %a -C %d %n
ExecOnUpdate=tar uf %a -C %d %n
Comment=Tar
</screen>
</para>
<para>The first line contains the command to be executed when creating a new
archive and the second is for updating existing archives. The third one
is the comment used for archiver description in <emphasis remap="bf">Preferences</emphasis> dialog.
Variables may be used in these commands, and are denoted by a leading &percnt;
sign.</para>
<para>The following is a list of legal command line variables:</para>
<para><literal remap="tt">&percnt;a</literal> The complete name of the archive</para>
<para><literal remap="tt">&percnt;f</literal> The normal file name</para>
<para><literal remap="tt">&percnt;d</literal> The parent directory. If the given argument is a file
( not a directory ) then this will give you the directory this file is in.</para>
<para><literal remap="tt">&percnt;n</literal> The name of the file. If the given argument is a directory
then this is the name of this directory.</para>
</chapter>
<chapter id="OnscreenFundamentals">
<title>Onscreen Fundamentals</title>
<para>In this section will be briefly described Kfind user interface. </para>
<para>The <emphasis remap="bf">Kfind</emphasis> window is separated into three areas: toolbar, search parameters
dialog, and viewing area. The viewing area and statusbar are visible only
after receiving search results.</para>
<sect1 id="toolbar">
<title>Toolbar</title>
<para><variablelist>
<varlistentry>
<term>Start Search</term>
<listitem>
<para>Starts new search using parameters specified in parameters
dialog.	</para>
</listitem>
</varlistentry>
<varlistentry>
<term>New Search</term>
<listitem>
<para>Clears results and starts with new parameters.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Stop Search</term>
<listitem>
<para>Stops running search process.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Open</term>
<listitem>
<para>Asks <emphasis remap="bf">Kfm</emphasis> to start default binding for selected file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Add to Archive</term>
<listitem>
<para>Adds selected file to chosen archive.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Delete</term>
<listitem>
<para>Deletes selected files and asks <emphasis remap="bf">Kfm</emphasis> to refresh directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Properties</term>
<listitem>
<para>Shows properties of selected file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Open Containing Folder</term>
<listitem>
<para>Asks <emphasis remap="bf">Kfm</emphasis> to open folder containing selected file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Save Search Results</term>
<listitem>
<para>Saves results to file specified in <emphasis remap="bf">Options-&gt;Preferences</emphasis> dialog.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Help</term>
<listitem>
<para>Shows <emphasis remap="bf">KFind</emphasis> documentation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Quit</term>
<listitem>
<para>Exits KFind.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="search-parameters-dialog">
<title>Search Parameters Dialog</title>
<para>This dialog is the main part of <literal remap="tt">KFind</literal>. It's used for specifying
parameter for find utility. There are three find parameters groups:</para>
<para><variablelist>
<varlistentry>
<term>Name and location</term>
<listitem>
<para>This dialog is used to specify a filename to look
for. This Filename is entered into combobox and can contain following
wildcards:
<itemizedlist>
<listitem><para> ? matches any character </para></listitem>
<listitem><para> * matches any sequence of characters </para></listitem>
<listitem><para>&lsqb; ] matches a defines set of characters, e.g. &lsqb;a-zA-Z0-9]
matches upper and lower case ASCII letters and digits.</para></listitem>
<listitem><para>\  sign is alphanumerical or a point</para></listitem>
</itemizedlist>

The combo box stores names history.  The <emphasis remap="bf">Browse</emphasis> button is used to specify directory
where the search will be performed. Whether the find should look into subdirectories
is specified by <emphasis remap="bf">Include subfolders</emphasis> check button.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Date Modified</term>
<listitem>
<para>This dialog allows searching for files created or modified within a
specified time period.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Advanced</term>
<listitem>
<para>This dialog allows file searches for specific types of files e.g
Postscript-documents, JPEG image files or WAV sound files.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="viewing-area">
<title>Viewing Area</title>
<para>The viewing area contains results of find process. After a file has been 
selected, the functions open, add to archive,delete, properties and open 
containing folder are enabled.  Double clicking causes execution.</para>
</sect1>
</chapter>
<chapter id="TheMenuEntries">
<title>The Menu Entries</title>
<sect1 id="file">
<title>File</title>
<para>The following functions are available from the file menu:
<variablelist>
<varlistentry>
<term>Open</term>
<listitem>
<para>This option calls <emphasis remap="bf">kfm</emphasis> to open the currently selected file,
using the default binding e.g Program files will be executed, text
files will start the text editor, etc. This action can also be
performed by double-clicking on the filename in the list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Add to archive</term>
<listitem>
<para>Adds the selected file to an archive.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Delete</term>
<listitem>
<para>Deletes the selected file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Properties</term>
<listitem>
<para>Allows the properties of the selected file to be altered.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Open Containing Folder</term>
<listitem>
<para>Opens the directory containing the selected file in a file
manager (KFM) window</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Save Search</term>
<listitem>
<para>Saves the list of selected files</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Quit</term>
<listitem>
<para>Exit <literal remap="tt">Kfind</literal></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="edit">
<title>Edit</title>
<para>Entries in this menu are disabled.</para>
</sect1>
<sect1 id="options">
<title>Options </title>
<para>From this menu you can start the preferences dialog.  The first tab
of the preferences dialog allows one to select the name and format of
the file where search results are stored. The second tab shows available 
filetypes and archivers details.</para>
<para><variablelist>
<varlistentry>
<term>Saving</term>
<listitem>
<para>Specify the file name where the the search results are stored. 
The default is <literal remap="tt">.kfind-results.html</literal> in the user's home directory.
If another name is chosen, one can specify the format of the stored results.
HTML and Text (.txt) are the currently supported formats. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Archivers</term>
<listitem>
<para>This dialog allows viewing (and in the future, probably editing)
of the archiver definitions used by <emphasis remap="it">Add to Archive</emphasis> function.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="help">
<title>Help</title>
<para>&gt;Show information about KFind and KFind documentation.</para>
</sect1>
</chapter>
<chapter id="Epilog">
<title>Epilog</title>
<sect1 id="developers">
<title>Developers</title>
<para><variablelist>
<varlistentry>
<term>Miroslav Fl&iacute;dr</term>
<listitem>
<para><ulink url="mailto:flidr@kky.zcu.cz">E-Mail: flidr@kky.zcu.cz</ulink></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Mario Weilguni;</term>
<listitem>
<para><ulink url="mailto:mweilguni@kde.org">E-Mail: mweilguni@kde.org</ulink></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="authors">
<title>Authors</title>
<para><variablelist>
<varlistentry>
<term>Miroslav Fl&iacute;dr</term>
<listitem>
<para><ulink url="mailto:flidr@kky.zcu.cz">E-Mail: flidr@kky.zcu.cz</ulink></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Martin Hartig</term>
<listitem>
<para><ulink url="hartig@mathematik.uni-kl.de">E-Mail: hartig@mathematik.uni-kl.de</ulink></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Mark Roberts</term>
<listitem>
<para><ulink url="mailto:mar2@scigen.co.uk">E-Mail: mar2@scigen.co.uk</ulink></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Eric Bischoff</term>
<listitem>
<para>- Editor
<ulink url="mailto:e.bischoff@noos.fr">E-mail: e.bischoff@noos.fr</ulink></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
</chapter>

<appendix id="Installation">
<title>Installation</title>
<sect1 id="how-to-obtain-kfind">
<title>How to Obtain KFind</title>
<para>KFind is a part of the KDE project <ulink url="http://www.kde.org">http://www.kde.org</ulink>. KFind can be found on
<ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the main ftp site of the KDE project.
There are links to many FTP mirrors there as well.</para>
</sect1>
<sect1 id="requirements">
<title>Requirements</title>
<para>In order to successfully compile KFind, you need the latest versions
of <literal remap="tt">libkdecore</literal> and <literal remap="tt">libkfm</literal>. All required libraries
as well as KFind itself can be found on <ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>.</para>
</sect1>
<sect1 id="compilation-and-installation">
<title>Compilation and installation</title>
<para><emphasis remap="bf">Kfind</emphasis> is normally an integrated part of a KDE release and therefore
will be automatically installed with other KDE applications in the normal
course of KDE installation.</para>
<para>If you need to compile and install KFind yourself on your system, type the
following in the base directory of the KFind distribution:
<screen> 
% ./configure 
% make 
% make install 
</screen>
</para>
<para>Since KFind uses <literal remap="tt">autoconf</literal>, you should not have trouble compiling it.
Should you run into problems, please report them to the <emphasis remap="bf">KDE</emphasis> mailing lists.</para>
</sect1>
</appendix>


</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
