<!doctype linuxdoc system>

<!-- The KFind Handbook.-->

<article>

<!-- Title information -->

<title> The KFind Documentation
<author>
Miroslav Flídr <tt/flidr@kky.zcu.cz/,
Martin Hartig <tt/hartig@mathematik.uni-kl.de/,
Mark Roberts <tt/mar2@scigen.co.uk/
<date>Version 0.3.2, 31 July 1997
<abstract>This Handbook describes KFind Version 0.3.2
<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<!-- NEW SECTION	NEW SECTION		NEW SECTION		NEW SECTION		 -->


<sect>Introduction

<p>
<bf/Kfind/ is designed to help find files within a directory hierarchy.
i.e if you know that a file is 'out there somewhere' but don't know exactly
where it is, then <bf/kfind/ is the tool for you. Having found the
required file(s), you can save, delete, change file properties, store them
to archives and/ or open the directory containing the file in the file
manager (<bf/Kfm/)

<p>
I hope you will find this program somehow useful and I would
appreciate any suggestions and comments.
<p>
<tt/Miroslav Flídr/
<htmlurl url="mailto:flidr@kky.zcu.cz" name="flidr@kky.zcu.cz">.
<p>

<sect>Installation
<p>

<sect1>How to obtain KFind
<p>
KFind is a core application of the KDE project <url
url="http://www.kde.org">.  KFind can be found on <url
url="ftp://ftp.kde.org/pub/kde/">, the main ftp site of the KDE
project.

<sect1>Requirements
<p>
In order to successfully compile KFind, you need the latest versions
of <tt> libkdecore</tt> and <tt> libkfm</tt>. All required libraries
as well as KFind itself can be found on <url
url="ftp://ftp.kde.org/pub/kde/">.

<sect1>Compilation and installation
<p>
<bf/Kfind/ 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.

In order to compile and install KFind on your system, type the
following in the base directory of the KFind distribution:
<tscreen>
<verb> 
% ./configure 
% make 
% make install 
</verb>
</tscreen>

Since KFind uses <tt/autoconf/ you should have not trouble
compiling it.  Should you run into problems please report them to the
<bf/KDE/ mailing lists.

<sect1>Configuration
<p>
Configuration is normally performed by means of the Preferences dialog;
see the user section of this manual for more details. A technical description
of <bf/kfind/ configuration follows for interested parties.

<p>
<bf/Kfind/ reads from configuration parameters from a configuration
file (normally <tt>~/.kfindrc</tt>).

This file contains information about saving search results, available
archivers and other configuration parameters; these parameters can be edited
from the <tt/Kfind/ <bf/Preferences/ dialog. 

<p>
<bf/General information:/ the resource file consists of sections.
Each section is started by a header title in square braces
e.g.<tt/[Saving]/

<p>
Information following the header relates to a specific aspect of
<tt/Kfind/ operation.

<p>
<bf/Saving configuration:/ The confiuration file holds the filename
and format of the file to be used for saving search results. This parameter
is stored within the .<it>kfindrc</it> file in entry <tt/[Saving] /as
follows:
<tscreen>
<verb>
[Saving]
Format=HTML
Filename=/root/result.html
</verb>
</tscreen>
Where <tt/Format/ entry can have values <tt/HTML /or <tt/Plain Text/.

<p><bf/Archiver configuration:/ Archivers available for <tt/kfind /are
specified in <it>.kfindrc</it> entry <tt/[Archiver Types]/ as follows:
<tscreen>
<verb>
[Archiver Types]
Archivers=tar;zip;zoo;
</verb>
</tscreen>

And each archiver is detaily described by its own entry:
<tscreen>
<verb>
[tar]
ExecOnCreate=tar cf %a -C %d %n
ExecOnUpdate=tar uf %a -C %d %n
Comment=Tar
</verb>
</tscreen>

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 <bf/Preferences/ dialog.
Variables may be used in these commands, and are denoted by a leading %
sign.
<p>
The following is a list of legal command line variables:

<p><tt/%a/ The complete name of the archive

<p><tt/%f/ The normal file name

<p><tt/%d/ The parent directory. If the given argument is a file (
not a directory ) then this will give you the directory this file is in.

<p><tt/%n/ The name of the file. If the given argument is a directory
then this is the name of this directory.
<p>

<sect>Onscreen Fundamentals
<p>
In this section will be briefly described Kfind user interface. 
<p>
The Kfind window separated in four areas: toolbar, search parameters
dialog, viewing area and statusbar. The viewing area and
statusbar are visible only after receiving search results.
<p>

<sect1>Toolbar
<p>
<descrip>
	<tag/Start Search/
	Starts new search using parameters specified in parameters
	dialog.	
	<tag/New Search/
	Clears results and hides viewing area.
	<tag/Stop Search/
	Stops runing search process.
	<tag/Open/
	Asks <bf/Kfm/ to start default binding for selected file.
	<tag/Add to Archive/
	Adds selected file to chosen archive.
	<tag/Delete/
	Deletes selected files and asks <bf/Kfm/ to refresh directory.
	<tag/Properties/
	Shows properties of selected file.
	<tag/Open Containing Folder/
	Asks <bf/Kfm/ to open folder containing selected file.
	<tag/Save Search Results/
	Saves results to file specified in <bf/Options->Preferences/ dialog.
	<tag/Help/
	Shows <bf/KFind/ documentation.
	<tag/Quit/
	Exits KFind.
</descrip>

<sect1>Search Parameters Dialog
<p>
This dialog is the main part of <tt/KFind/. It's used for specifying
parameter for find utility. There are three find parameters groups:

<descrip>
	<tag/Name and location/
	This dialog is used to specify filename user is looking
for. Filename is entered into combobox and can contain following
wildcards:
<tscreen>
      ? matches any character 
<p>
      * matches any sequence of characters 
<p>
      [[]] matches a defines set of characters, e.g. [a-zA-Z0-9\.]
matches upper and lower case ASCII letters, digits, and dot.
</tscreen>
The combo box stores names history.  The <bf/Look in/ combo box and
<bf/Browse/ button are used to specify directory where the search will
be performed. Whether the <tt/find/ should look into subdirectories
is specified by <bf/Include subfolders/ check button.
	<tag/Date Modified/
	This dialog allows searching for files created within a
specified time period.
	<tag/Advanced/
	This page allows file searches for specific types of files e.g
Postscript-documents, JPEG image files or WAV sound files. The search
can also be restricted to files above or below a certain size.

</descrip>

 <sect1>Viewing Area
<p>
The viewing area contains results of find
process. After clicking on item the functions open, add to
archive,delete, properties and  open containing folder will be enabled.
Double clicking causes executing default binding.

<sect>The Menu Entries
<p>

<sect1>File
<p>
The following functions are available from the file menu:
<descrip>
	<tag/Open/ 
	This option calls kfm 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.
	<tag/Add to archive/ 
	Adds the selected file to an archive
	<tag/Delete/
	Deletes the selected file
	<tag/Properties/
	Allows the propertes of the selected file to be altered.
	<tag/Open Containing Folder/
	Opens the directory containing the selected file in a file
manager (KFM) window
	<tag/Save Search/
	Saves the list of selected files
	<tag/Quit/
	Exit <tt>Kfind</tt>
</descrip>

<sect1>Edit
<p>
Entries in this menu are disabled.

<sect1>Options 
<p>

From this menu you can start the preferences dialog. This dialog lets
the user determine in which file and file format <tt/KFind/ should
store search results. User can also look at avaiable filetypes and
archivers details.

<descrip>
	<tag/Saving/
	This dialog lets the user specify a file to save the results
of a search to. The <bf/File format/ button makes it possible to say
whether the results are saved in raw text format or HTML format. The
<bf/Save Results to file/ radio buttons determine whether search
results are saved to the default file, or a file specified by the
user. Pressing button <bf/File Format/ lists the types of file a
list of files matching the search parameters can be output to.
Currently HTML format and Text (.txt) format are supported
	<tag/Filetypes/
	This dialog allows viewing (editing probably in future) of the
association between filenames and their types. The left selection
box lists all possible file types. Selecting an option from that list
places the attributes of the file type in the other boxes.
	<tag/Archivers/
	This dialog allows viewing (editing probably in future) of
archiver definition used by <it/Add to Archive/ function.
</descrip>

<sect1>Help
<p>
From this menu user can show information about KFind and KFind documentation.

</article>








