<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [
  <!ENTITY kappname "&kfind;">
  <!ENTITY package "kdebase">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"> 
]>

<book id="kfind" lang="&language;">

<bookinfo>
<title>The &kfind; Handbook</title>

<authorgroup>
<author>&Dirk.Doerflinger; &Dirk.Doerflinger.mail;</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2001</year>
<holder>&Dirk.Doerflinger;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2013-05-29</date>
<releaseinfo>&kde; 4.11</releaseinfo>

<abstract>
<para>
&kfind; is &kde;'s file find utility.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeutils</keyword>
<keyword>kfind</keyword>
<keyword>find</keyword>
<keyword>search</keyword>
</keywordset>
</bookinfo>

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

<para>
&kfind; is the &kde; file find utility.
</para>

<sect1 id="starting">
<title>Launching &kfind;</title>

<para>
The Find Files tool is a useful method of searching for specific files on your
computer, or for searching for files that match a pattern. An example of
this could include searching for files of a particular type or with certain
letters in the filename.

You can load this utility in &konqueror; (in file manager mode) 
by selecting <menuchoice><shortcut><keycombo action="simul">&Ctrl;
<keycap>F</keycap></keycombo></shortcut><guimenu>Tools</guimenu>
<guimenuitem>Find File</guimenuitem></menuchoice> from the menu. 
If you want to use &kfind; as a standalone search tool, launch it by using &krunner;.
</para>

</sect1>
</chapter>

<chapter id="using-kfind">
<title>Finding Files</title>

<sect1 id="name-tab">
<title>The Name/Location Tab</title>

<para>
When starting &kfind;, you will see a quite simple window. Type in the
name of the file you are searching for in the text box labeled
<guilabel>Named:</guilabel>. You can use wildcard matching and 
a semicolon (<quote>;</quote>) for separating multiple names.</para>
<para>Choose a folder where you want to search
by typing it in the field <guilabel>Look in:</guilabel>
or by clicking <guibutton>Browse...</guibutton> (you can toggle the 
display of the hidden files and folder in the dialog using the shortcuts 
<keycombo action="simul">&Alt;<keycap>.</keycap></keycombo> or <keycap>F8</keycap>) 
and press &Enter; or click the <guibutton>Find</guibutton> button. 
Use the <guibutton>Stop</guibutton> button to cancel a search.
A search result can be saved in &HTML; format or as plain text with the
<guibutton>Save As...</guibutton> button.</para>
<para>
If <guilabel>Include subfolders</guilabel> is checked all
subfolders starting from your chosen folder will be searched
too. If you enable <guilabel>Case sensitive search</guilabel>, &kfind; will
only find files with the exact case matching names.
Enable the option <guilabel>Show hidden files</guilabel> to include
them in your search.
Selecting <guilabel>Use files index</guilabel> lets you use the 
files' index created by the <quote>locate</quote> package 
to speed-up the search.</para>
<para>
You can use the following wildcards for file or folder names:
</para>

<variablelist>
<varlistentry>
<term>The Asterisk <quote><keycap>*</keycap></quote></term>
<listitem>
<para>
The asterisk stands for any number of missing characters (even zero),
that means &eg; searching for <userinput>marc*</userinput> may find the
files <filename>marc</filename>, <filename>marc.png</filename> and
<filename> marc_must_not_read_this.kwd</filename>. 
<userinput>mar*.kwd</userinput> may find
<filename>marketplace.kwd</filename> and
<filename>marc_must_not_read_this.kwd</filename>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>The Question Mark <quote><keycap>?</keycap></quote></term>
<listitem>
<para>
In contrast to the asterisk, the question mark stands for exactly one
character, so <userinput>mar?</userinput> will find
<filename>marc</filename>, but <userinput>marc?</userinput> will not find
anything, as our files are called <filename>marc</filename> and
<filename>marc.png</filename>. You can put as many question marks in the
term as you want, it will find exactly that number of characters.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>The Character Set <quote>[...]</quote></term>
<listitem>
<para>
This matches any of the characters between the braces.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
Of course you can combine two or more wildcard symbols in a search term.
</para>

<para>
The results of your search will be displayed in the box below. A click with the
&RMB; on a selection in this box opens a context menu with a list of
actions for the selected files or folders.
</para>

</sect1>

<sect1 id="kfind-date-range">
<title>The Contents Tab</title>

<variablelist>
<varlistentry>
<term><guilabel>File type</guilabel></term>
<listitem>
<para>
Here you can specify the type of file you are searching for.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Containing text</guilabel></term>
<listitem>
<para>
Type in the word or phrase the files you are searching for must
contain. Note: If you do this in a large folder or checked
<guilabel>Include subfolders</guilabel> in the
<guilabel>Name/Location</guilabel> tab, this may take a long time.
</para>

<note>
<para>This option will <emphasis>not</emphasis> work for all files listed 
under <guilabel>File type</guilabel>. Only the following file types
are supported:
<itemizedlist>
<listitem><para>Text files, &eg; source code and <filename>README</filename> files</para></listitem>
<listitem><para>&kword; &gt;= 1.2</para></listitem>
<listitem><para>&kpresenter; &gt;= 1.2</para></listitem>
<listitem><para>&kspread; &gt;= 1.2</para></listitem>
<listitem><para>OpenOffice.org Writer / LibreOffice Writer</para></listitem>
<listitem><para>OpenOffice.org Impress / LibreOffice Impress</para></listitem>
<listitem><para>OpenOffice.org Calc / LibreOffice Calc</para></listitem>
<listitem><para>Calligra Words</para></listitem>
<listitem><para>Calligra Sheets</para></listitem>
<listitem><para>Calligra Stage</para></listitem>
</itemizedlist>

</para>
</note>

</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Case sensitive</guilabel></term>
<listitem>
<para>
If you enable this option, &kfind; will
only find text in files with the exact case matching, &eg;
<userinput>MARC</userinput> will only match
<quote>MARC</quote>, not <quote>Marc</quote>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Regular expression</guilabel></term>
<listitem><para>If you have installed the &kregexpeditor; tool from
playground/utils on the &kde; git server, you will have this additional option.  Enabling
it will allow you to search for a <firstterm>regexp</firstterm> or
regular expression.  A regexp is a way to specify conditions for your
search, and they can be very complex, and equally they can be very
powerful.  If you are unfamiliar with regular expressions, you can
choose <guibutton>Edit</guibutton> button to open
&kregexpeditor;.  This tool allows you to construct your set of
conditions graphically, and then generates the expression for
you.</para>

<para>&kregexpeditor; is a very useful tool, and can be used from within
many &kde; applications other than &kfind;.  You can find more
information from within its own help file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Include binary files</guilabel></term>
<listitem><para>This lets you search in any type of file, even those that 
usually do not contain text (for example program files and images).</para>
</listitem>
</varlistentry>

<!-- FIXME: "Search metainfo sections" 
Search within files' specific comments/metainfo<br />These are some "
"examples:<br /><ul><li><b>Audio files (mp3...)</b> Search in id3 tag for a "
"title, an album</li><li><b>Images (png...)</b> Search images with a special "
"resolution, comment...</li></ul></qt>"

"<qt>If specified, search only in this field<br /><ul><li><b>Audio files "
"(mp3...)</b> This can be Title, Album...</li><li><b>Images (png...)</b> "
"Search only in Resolution, Bitdepth...</li></ul></qt>"
Broken in 4.11? kfile4 + kfilemetadatareader give no output
-->
</variablelist>

</sect1>

<sect1 id="kfind-advanced">
<title>The Properties Tab</title>

<para>
Here you can refine your search. These are the special refinements 
you can choose:
</para>

<variablelist>

<varlistentry>
<term><guilabel>Find all files created or modified</guilabel></term>
<listitem>
<para>
Here you can either enter two dates, between which the
files were created or modified, or specify a time period.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>File size is</guilabel></term>
<listitem>
<para>Here you can specify if the file has to be at least or at most as
big as the size you entered in the following box, or else equal
to the size.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Files owned by user</guilabel>, <guilabel>Files owned by group</guilabel></term>
<listitem>
<para>Here you can specify user and group names as owner of the files.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&kfind; 
</para>

<para>
Program copyright:
</para>

<itemizedlist>
<title>Developers</title>
<listitem>
<para>Martin Hartig</para>
</listitem>

<listitem>
<para>&Stephan.Kulow; &Stephan.Kulow.mail;</para>
</listitem>

<listitem>
<para>&Mario.Weilguni; &Mario.Weilguni.mail;</para>
</listitem>

<listitem>
<para>&Alex.Zepeda; <email>jazepeda@pacbell.net</email></para>
</listitem>

<listitem>
<para>Miroslav Flídr <email>flidr@kky.zcu.cz</email></para>
</listitem>

<listitem>
<para>&Harri.Porten; &Harri.Porten.mail;</para>
</listitem>

<listitem>
<para>Dima Rogozin <email>dima@mercury.co.il</email></para>
</listitem>

<listitem>
<para>&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;</para>
</listitem>

<listitem>
<para>Hans Petter Bieker <email>bieker@kde.org</email></para>
</listitem>

<listitem>
<para>&Waldo.Bastian; &Waldo.Bastian.mail;</para>
</listitem>
    
</itemizedlist>

<para>
Documentation copyright 2001 &Dirk.Doerflinger; 
&Dirk.Doerflinger.mail;</para> 

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->
&underGPL;               <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kfind">
<title>How to obtain &kfind;</title>

&install.intro.documentation;

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
In order to successfully use &kfind;, you need &kde; 4.x.
</para>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

</sect1>

</appendix>

&documentation.index;

</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

// vim:ts=0:sw=2:tw=78:noet
-->
