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

3 files changed, 446 insertions, 0 deletions

diff --git a/doc/kfind/Makefile.am b/doc/kfind/Makefile.am
new file mode 100644
index 000000000..da8216ae4
--- /dev/null
+++ b/doc/kfind/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+KDE_MANS = AUTO
diff --git a/doc/kfind/index.docbook b/doc/kfind/index.docbook
new file mode 100644
index 000000000..ecfa5921d
--- /dev/null
+++ b/doc/kfind/index.docbook
@@ -0,0 +1,363 @@
+<?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 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>2004-04-11</date>
+<releaseinfo>1.20.01</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 by clicking on <guimenuitem>Find Files</guimenuitem>. This will
+launch &kfind;.
+</para>
+
+</sect1>
+</chapter>
+
+<chapter id="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 in the textbox labeled
+<guilabel>Named:</guilabel>. Choose a folder where you want to search
+by typing it in the field <guilabel>Look in:</guilabel>
+or by clicking <guibutton>Browse...</guibutton> and press
+<keycap>Enter</keycap> or click <guibutton>Find</guibutton>. If
+<guilabel>Include subfolders</guilabel> is checked all
+subfolders starting from your chosen folder will be searched
+too. The results will be displayed in the box below.
+</para>
+
+<para>
+You can use the following wildcards:
+</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>
+
+</variablelist>
+
+<para>
+Of course you can combine those two wildcard symbols in a search term.
+</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</para></listitem>
+<listitem><para>OpenOffice.org Impress</para></listitem>
+<listitem><para>OpenOffice.org Calc</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 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
+the kdeutils package, 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 <guilabel>Edit Regular Expression</guilabel> 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>
+
+<!-- TODO: "Search metainfo sections" -->
+
+</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 as most as
+big as the size you entered in the following box.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Files owned by user, Files owned by group</guilabel></term>
+<listitem>
+<para>Here you can specify user and group names.
+</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 <email>coolo@kde.org</email></para>
+</listitem>
+
+<listitem>
+<para>Mario Weilguni <email>mweilguni@sime.com</email></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 <email>porten@kde.org</email></para>
+</listitem>
+
+<listitem>
+<para>Dima Rogozin <email>dima@mercury.co.il</email></para>
+</listitem>
+
+<listitem>
+<para>Carsten Pfeiffer <email>pfeiffer@kde.org</email></para>
+</listitem>
+
+<listitem>
+<para>Hans Petter Bieker <email>bieker@kde.org</email></para>
+</listitem>
+
+<listitem>
+<para>Waldo Bastian <email>bastian@kde.org</email></para>
+</listitem>
+    
+</itemizedlist>
+
+<para>
+Documentation copyright 2001 &Dirk.Doerflinger;
+&Dirk.Doerflinger.mail;</para> 
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove -->
+&underBSDLicense;        <!-- BSD 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; 3.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
+-->
diff --git a/doc/kfind/man-kfind.1.docbook b/doc/kfind/man-kfind.1.docbook
new file mode 100644
index 000000000..bab220749
--- /dev/null
+++ b/doc/kfind/man-kfind.1.docbook
@@ -0,0 +1,79 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+<title>KDE User's Manual</title>
+<author>&Lauri.Watts; &Lauri.Watts.mail;</author>
+<date>June 07, 2005</date>
+<productname>K Desktop Environment</productname>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>kfind</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>kfind</command></refname>
+<refpurpose>file find utility for &kde;</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>kfind</command>
+<group choice="opt"><option>searchpath</option></group>
+<arg choice="opt">KDE Generic Options</arg>
+<arg choice="opt">Qt Generic Options</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</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, or that contain a certain piece of
+text in their contents.</para> 
+<para>&kfind; is a graphical tool, and not normally run from the command
+line.</para>
+
+</refsect1>
+
+<refsect1>
+<title>Options</title>
+<variablelist>
+<varlistentry>
+<term><option>searchpath</option></term>
+<listitem><para>You may optionally supply a colon separated path to prefill
+the dialog.  You might use this ability to set up different icons on your
+panel or desktop to quickly run searches in different locations.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>App options, in a variablelist</para>
+
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+<para>More detailed user documentation is available from <ulink
+url="help:/kfind">help:/kfind</ulink>
+(either enter this <acronym>URL</acronym> into &konqueror;, or run
+<userinput><command>khelpcenter</command>
+<parameter>help:/kfind</parameter></userinput>).</para>
+</refsect1>
+
+<refsect1>
+<title>Authors</title>
+<para>The current maintainer of &kfind; is <!-- FIXME: Who? -->.  A list of
+previous contributors is available in the complete user manual available in
+khelpcenter.</para>
+<para>This documentation was prepared by &Lauri.Watts;
+&Lauri.Watts.mail;</para>
+</refsect1>
+
+</refentry>