Added old KDE3 version of Krusader

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/krusader@1094427 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 328 insertions, 0 deletions

diff --git a/doc/en/search.docbook b/doc/en/search.docbook
new file mode 100644
index 0000000..8a9d087
--- /dev/null
+++ b/doc/en/search.docbook
@@ -0,0 +1,328 @@
+<sect1 id="krusearcher">
+  <title>KruSearcher: find what you are looking for</title>
+  <indexterm>
+    <primary>Search</primary>
+  </indexterm>
+  <para>Welcome to &krusader;'s powerful search module -
+  nicknamed KruSearcher. It is the most able tool (that we know of)
+  for &Linux;, since it allows so many different ways to
+  quickly find the file you are looking for. The search function is
+  also available on remote file systems. It is divided into two
+  levels, the general and the advanced. Let's take a look at the
+  general page.</para>
+  <!-- OLD
+<screenshot>
+  <screeninfo>Krusearcher General</screeninfo>
+  <mediaobject>
+  <imageobject><imagedata fileref="search_general.png" format="PNG"/></imageobject>
+  <imageobject><imagedata fileref="search_general.png" format="EPS"/></imageobject>
+  <textobject><phrase>Krusearcher General</phrase></textobject>
+  <caption><para>Krusearcher General.</para></caption>
+  </mediaobject>
+</screenshot>
+-->
+  <figure id="screenshot-search-general" float="1">
+    <title>General Search</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="search_general.png"></imagedata>
+      </imageobject>
+      <textobject>
+        <phrase>General Search</phrase>
+      </textobject>
+    </mediaobject>
+  </figure>
+  <para>The page is divided into four parts: top (search for) part,
+  bottom part - titled 'containing text', left part - titled
+  'search in' and right part which is called 'don't search in'.
+  Obviously, each part handles different aspects of the search.
+  Let's look at them closely.</para>
+  <itemizedlist>
+    <title>Top Part:</title>
+    <listitem>
+      <para>
+      <guilabel>Search for</guilabel>: here you enter the main
+      search criteria. You can enter a file name, a wildcard (
+      <literal role="extension">*.o.*</literal>, 
+      <literal role="extension">*.c</literal> &etc;) or
+      both - separated by a space. If you type 
+      <literal>'text'</literal> the results is the same as 
+      <literal>'*text*'</literal>. You can exclude files from the
+      search with '|' (&eg; 
+      <literal role="extension">'*.cpp *.h |
+      *.moc.cpp'</literal>) . You can use quotation marks for names
+            that contain spaces. Filter "Program Files" searches
+            out those files/directories the name of which is <filename>Program
+            Files</filename>.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Case sensitive</guilabel>: unchecking it will allow
+      lower and upper case search (&ie;: 
+      <literal role="extension">*.c</literal> interprets as 
+      <literal role="extension">*.c</literal> AND 
+      <literal role="extension">*.C</literal>).</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Of type</guilabel>: this box lets you search for a
+      file not only by its name, but also by its mime type. For
+      example, you can search for all the audio files whose name
+      begins with B. Usually this option defaults to 'all files',
+      but you can choose to search for archives, directories,
+      images, text files, videos and audio files.</para>
+    </listitem>
+  </itemizedlist>
+  <itemizedlist>
+    <title>Left and Right Part:</title>
+    <listitem>
+      <para>
+      <guilabel>Search in</guilabel> and 
+      <guilabel>Don't search in</guilabel>: Using those two parts,
+      you can specify a search exactly the way you want it. For
+      example, you might want to search for a file in the whole
+      file system (beginning with 
+      <filename>/</filename>), but do not want to search inside 
+      <filename>/mnt</filename>. All you need to do is write 
+      <filename>/</filename> in the 
+      <guilabel>search in</guilabel> box, and write 
+      <filename>/mnt</filename> in the 
+      <guilabel>dont search in</guilabel> box. If you want to enter
+      more than one directory in one of the boxes, just type the
+      first name and press &Enter;. The directory name
+      will be copied to the bigger box and youwill be able to enter
+      another name. 
+      <note>
+        <para>The input line has an auto-completion feature,
+        corresponding to &kde; global settings. If you
+        wish, you can click on the 
+        <guiicon>folder icon</guiicon>, and browse to the directory
+        you wish to add.</para>
+      </note></para>
+    </listitem>
+  </itemizedlist>
+  <itemizedlist>
+    <title>Bottom Part:</title>
+    <listitem>
+      <para>
+      <guilabel>Text</guilabel>: entering text here makes
+      &krusader; search for it inside the files (
+      <command>grep</command>). This way you can search for all
+      header files (
+      <literal role="extension">*.h</literal>) which include the
+      word 
+      <literal>'testing 123'</literal>.</para>
+    </listitem>
+    <listitem>
+      <para>
+        <guilabel>Match whole word only</guilabel>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Case sensitive</guilabel>: refers to your text
+      being searched for in upper and lower case or the exact
+      phrase you entered.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Search in subdirectories</guilabel>: perform a
+      recursive search and dive into every directory on the
+      way.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Search in archives</guilabel>:
+      &krusader; will search for your files inside every
+      supported archive. This, however, takes longer to perform. 
+      <note>
+        <para>If you check this checkbox, youwill notice you cannot 
+        <command>grep</command> inside files anymore. This is done,
+        since looking inside archived files forces
+        &krusader; to extract them, which results in an
+        extremely time-consuming search.</para>
+      </note></para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Follow links</guilabel>: if checked,
+      &krusader; will follow soft-links during the
+      search.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Profiles</guilabel>: if you have to regularly
+      perform the same search operation, you can save the search
+      settings &eg; include files, exclude files,
+      etc.... Press the 'profile' button, and you can
+      add/load/save/remove search profiles.</para>
+    </listitem>
+  </itemizedlist>
+  <para>The above screen shot shows a search for all the files which
+  end with 
+  <literal role="extension">c, cpp</literal> or 
+  <literal role="extension">h</literal> and include the string 
+  <literal>'testing 123'</literal>. &krusader; will
+  search in 
+  <filename class="directory">/root, /opt, /bin</filename> and 
+  <filename class="directory">/usr</filename>, but not in 
+  <filename class="directory">/usr/lib</filename> and 
+  <filename class="directory">/usr/share</filename>.</para>
+  <para>Clicking the 
+  <guibutton>Search</guibutton> button starts the search and
+  displays the results page. During the search, you may press the 
+  <guibutton>Stop</guibutton> button to stop the search. The 
+  <guibutton>Close</guibutton> button is not operational during a
+  search, so you must first stop the search and then 
+  <guibutton>Close</guibutton> the window. When a result is found,
+  double-clicking on it will take &krusader;'s active
+  panel point to the found files - but will not close the search
+  window, so you will be able to click on a different result.</para>
+  <para>Sometimes, you need to narrow your search even more.
+  Krusearcher allows a much finer search, and for that, let's look
+  at the 
+  <guilabel>Advanced Page</guilabel>...</para>
+  <!-- OLD
+<screenshot>
+  <screeninfo>Krusearcher Advanced</screeninfo>
+  <mediaobject>
+  <imageobject><imagedata fileref="search_advanced.png" format="PNG"/></imageobject>
+  <imageobject><imagedata fileref="search_advanced.png" format="EPS"/></imageobject>
+  <textobject><phrase>Krusearcher Advanced</phrase></textobject>
+  <caption><para>Krusearcher Advanced.</para></caption>
+  </mediaobject>
+</screenshot>
+-->
+  <figure id="screenshot-search-advanced" float="1">
+    <title>Advanced Search</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="search_advanced.png"></imagedata>
+      </imageobject>
+      <textobject>
+        <phrase>Advanced Search</phrase>
+      </textobject>
+    </mediaobject>
+  </figure>
+  <para>This screen shot shows a search for files whose size is
+  between 10KB and 150KB, which were modified between October 10th
+  and November 1st, which belong to any user in the 'users' group,
+  and are readable and writable by anyone in the 'users' group, but
+  only readable to the rest of the world.</para>
+  <para>The advanced page is divided into three parts: size, date
+  and ownership.</para>
+  <para>
+    <emphasis role="bold">Size</emphasis>
+  </para>
+  <para>Allows you to choose the size range of the file you are
+  looking for. By checking the check boxes, you can search for a
+  file which is bigger than XXX bytes (or KB, MB), smaller than XXX
+  bytes or, by checking both search for a file which size is bigger
+  than XXX but smaller than YYY.</para>
+  <para>
+    <emphasis role="bold">Date</emphasis>
+  </para>
+  <para>This part offers three different ways of defining a date
+  criteria: 
+  <itemizedlist>
+    <listitem>
+      <para>
+      <guilabel>Modified between</guilabel>: allows you to enter
+      two dates. &krusader; will search for files with a
+      modification date between the first date and the second one,
+      inclusive. If you only enter a date in the left box, you will
+      be searching for files older than that date. If you only
+      enter a date in the right box, you will be searching for files
+      newer than that date. 
+      <note>
+        <para>You can click on the date icon (near the input boxes)
+        to open a standard date window - which allows you to easily
+        browse through the calendar and search for the desired
+        date. Clicking on a date will close the window and the date
+        will appear in the input box.</para>
+      </note></para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Not modified after</guilabel>: choosing this option
+      makes &krusader; search for files that were NOT
+      modified after a given date, which is the same as searching
+      for files older than that date.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Modified in the last/not modified in the
+      last</guilabel>: in these input boxes, you do not enter a date
+      but a number. This number represents days/weeks/months (as
+      chosen in the near drop box). Entering the number 5 in the
+      upper input box, makes &krusader; search for files
+      that were modified in the last 5 days. Entering the number 2
+      in the lower input box makes &krusader; search for
+      files that did NOT change in the last 2 days. The combination
+      of both results in a search for files that were changed in
+      the last 5 days, but NOT in the last 2 days.</para>
+    </listitem>
+  </itemizedlist></para>
+  <para>
+    <emphasis role="bold">Ownership</emphasis>
+  </para>
+  <itemizedlist>
+    <listitem>
+      <para>
+      <guilabel>Belongs to user/group</guilabel>: by checking each
+      of the corresponding check boxes, you can search for files
+      which belong to a certain user and/or group. The drop box
+      lists all the user names and group names in the system, just
+      choose one and go ahead.</para>
+    </listitem>
+    <listitem>
+      <para>
+      <guilabel>Permissions</guilabel>: divided into owner, group
+      and all - it allows you to choose certain permissions for the
+      file. You can choose to specify permissions for the owner,
+      group, all or any combination. The question mark (?) is a
+      wildcard - which means that any permission is valid.</para>
+    </listitem>
+  </itemizedlist>
+  <note>
+    <para>To clarify, the screen shot above (the permissions part)
+    describes a search for files that belong to any user in group
+    'users', are readable, writable but not executable to any user
+    in the group, are readable but not writable or executable to
+    the rest of the world and have unknown permissions to its
+    owner.</para>
+  </note>
+  <para>
+    <emphasis role="bold">Results</emphasis>
+  </para>
+  <para>Clicking on the 
+  <guibutton>Search</guibutton> button to start the search and open
+  the Results window. Here you can see the progress and the the
+  results of the search action. If you want you can stop the
+  current search action with the 
+  <guibutton>Stop</guibutton>button. In the result list select the
+  file and use 
+  <keycap>F3</keycap>/
+  <keycap>F4</keycap> to view/edit or use the right-click menu. When
+  you click on a found item, the directory of the active panel will
+  change if the selected item is not in the current panel
+  directory. The results window supports dragging items to other windows 
+  and copy to clipboard (<keycombo action="simul">&Ctrl;<keycap>c</keycap></keycombo>).
+  When you close the Krusearcher window, the selected
+  item is selected in the active panel.</para>
+  <para>
+    <emphasis role="bold">Feed to listbox</emphasis>
+  </para>
+  <para>When you click the 
+  <guibutton>Feed to listbox</guibutton> button after the results
+  are displayed, then &krusader; ask for a Query Name,
+  this name will be used in the Results-Tab in the List Panel that
+  holds the search results. You can do whatever you want on the
+  files in the new tab. The location toolbar will display
+  &eg; 
+  <filename>virt:/Search results 1</filename>.</para>
+  <warning>
+    <para>The files in the Results-Tab are actually the original
+    files. if you delete a file - it is removed!</para>
+  </warning>
+</sect1>