<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY komparator "<application>Komparator</application>">
  <!ENTITY kappname "&komparator;"><!-- Do *not* replace kappname-->
  <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book lang="&language;">

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

<authorgroup>
<author>
<firstname></firstname>
<othername></othername>
<surname>Georg Hennig</surname>
<affiliation>
<address><email>georg.hennig@web.de</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>2005-2008</year>
<holder>Georg Hennig</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2008-02-25</date>
<releaseinfo>0.9</releaseinfo>

<abstract>
<para>
&komparator; an application that searches and synchronizes two directories,
discovering duplicate, newer or missing files and empty folders.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>Komparator</keyword>
<keyword>synchronize</keyword>
<keyword>compare</keyword>
<keyword>folders</keyword>
<keyword>directories</keyword>
</keywordset>

</bookinfo>


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

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para>
&komparator; is a &kde; application that allows the user to search two directories and
synchronize them interactively.
Unlike other (command line) tools the user has intuitive control over what is done.
</para>
<para>
An easy way to get help about &komparator; is the <emphasis>"What's this"</emphasis>
help option. First enable this help by clicking on the <keycap>?</keycap> in the
title bar, or hit the <keycap>What's this</keycap> button at the bottom of the
GUI. Then click on the item that you want to have information about.
</para>
</chapter>

<chapter id="using-komparator">
<title>Using &komparator;</title>

<para>
Before starting to search, you need at least specify the two folders that you want to
compare. The terms "left" and "right" refer to the positions of the file lists in the
<emphasis>Newer files</emphasis> and <emphasis>Missing files</emphasis> tabs.
The selection of the URLs is done in the URL selection boxes.
They accept drops from konqueror or other applications where you can drag URLs from.
Valid URLs are absolute paths like <filename>/path/to/your/directory</filename> and
kioslave objects like <filename>media:/sda1</filename> or <filename>ftp://ftp.yourserver.com</filename>.
Non-local files will be downloaded to calculate their MD5 checksum or perform
binary comparison.

<screenshot>
<screeninfo>URL boxes</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_url.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>URL boxes</phrase>
		</textobject>
	</mediaobject>
</screenshot>

The virtual subfolders behave as if they were linked inside the right URL.
For example, the right URL <filename>/path/to/your/directory</filename> with the
virtual subfolder <filename>/path/to/virtual/subfolder</filename> will behave as if you
were searching the folder <filename>/path/to/your/directory</filename> with a subfolder
<filename>/path/to/your/directory/subfolder</filename>.
The folder <filename>/path/to/your/directory/subfolder</filename> should not exist
in reality, as all file actions will only be performed on the virtual subfolder.
It is also a bad idea to use real subfolders as virtual subfolders.

This option is useful, if you want to create a backup of several different folders
into one single backup folder.

</para>

<para>
Apart from this, you can specify various search/compare options and general settings:
</para>

<sect1 id="komparator-basic-search-options">
<title>Basic search options</title>

<screenshot>
<screeninfo>Basic search options</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_search_options_basic.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Basic search options</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<sect2 id="komparator-search-options">
<title>Search Options</title>

<sect3 id="komparator-include-subfolders">
<title>Include subfolders</title>
<para>
If checked, files in subfolders are also found. Soft-linked directories are only
searched, if <keycap>Follow soft links</keycap> is enabled.
</para>
</sect3>

<sect3 id="komparator-include-hidden-items">
<title>Include hidden items</title>
<para>
If checked, all files will be displayed. Otherwise all hidden files, and files, that are in a hidden
subfolder (relative to the folder you are comparing), will be excluded from the search.
</para>
</sect3>

<sect3 id="komparator-file-index">
<title>Use file index</title>
<para>
This options allows you to use <keycap>locate</keycap> to find files instead of
the internal search. Usually this is faster if there are very many files.
Only files that are in the current database are found. Update it regularly
with <keycap>updatedb</keycap> (this is usually done by a <keycap>cron</keycap> job).
</para>
</sect3>

<sect3 id="komparator-case-sensitive">
<title>Case sensitive search</title>
<para>
If enabled the regular expression provided in the <keycap>Extended Search Options</keycap> tab
will be taken exactly as they are. Otherwise <keycap>[a-d]*[^1-3]</keycap> equals
<keycap>[a-dA-D]*[^1-3]</keycap>, for example.
This affects the comparison of relative paths, too. Therefore a relative path
<keycap>path/to/example_file</keycap> is not equal to <keycap>PATH/TO/EXAMPLE_FILE</keycap>,
if this check box is enabled.
</para>
</sect3>

<sect3 id="komparator-empty-folders">
<title>Find empty folders</title>
<para>
If enabled, empty folders will be displayed in the duplicate files list.
</para>
</sect3>

<sect3 id="komparator-soft-links">
<title>Follow soft links</title>
<para>
If enabled, soft links are considered as the file that they are linked to.
This <keycap>does</keycap> affect the search for missing / newer files.
If a link is copied, in reality the file that it is linked to is copied.
The target file's name will be the link's name.
</para>
<para>
This enables the search within linked directories, too.
</para>
</sect3>

</sect2>

<sect2 id="komparator-duplicates-search-options">
<title>Duplicate Files Search Options</title>

<sect3 id="komparator-ignore-empty">
<title>Ignore empty files</title>
<para>
If checked, &komparator; won't display empty files as duplicate files.
This does not affect whether they are displayed as missing / newer files
if necessary.
</para>
</sect3>

<sect3 id="komparator-size-comparison">
<title>Size comparison</title>
<para>
This is enabled by default, so duplicate files are <emphasis>only </emphasis> found
by file size comparison, and not by comparison of their paths relative to their parent
directories (the directories you are searching).
</para>
<para>
Disable this to find duplicates <emphasis>only</emphasis> by comparison of relative
paths. &komparator; won't be able to detect real duplicates. This is also necessary
to show you if a newer / older file pair is not different.
</para>
<para>
Size comparison is necessary for MD5 checksum and binary comparison to work.
</para>
</sect3>

<sect3 id="komparator-md5">
<title>Calculate MD5 checksum</title>
<para>
If you have a slow system, or many files to search or comparing with a
remote folder, it can be useful to turn off the MD5 checksum check.
Remote files (=all non-local files, also kioslave protocols other than file://)
must be downloaded to temporary files to calculate their checksum.
This can take some time, especially if you're connected over a slow network
like the internet.
</para>
<para>
Without MD5 checksum you will find duplicate files that have the same
size but are not really equal.
</para>
<para>
MD5 checksum comparison is necessary for binary comparison.
</para>
</sect3>

<sect3 id="komparator-binary-comparison">
<title>Binary comparison</title>
<para>
This will compare the files byte by byte. This can be really slow on
large files. Therefore you can set a size threshold for files to be compared.
Files that are larger than this threshold are assumed to be equal without
real comparison.
</para>
</sect3>

<sect3 id="komparator-duplicates-only">
<title>Duplicates in right URL only</title>
<para>
Only search for duplicate files (and empty folders), and only in the right URL.
The left URL is not searched at all, and therefore no missing / newer files are reported.
</para>
</sect3>

</sect2>


</sect1>

<sect1 id="komparator-search-options-extended">
<title>Extended Search Options</title>

<screenshot>
<screeninfo>Search options</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_search_options_extended.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Search options</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
Only files that match the following specifications are
considered during the search.
</para>

<note><para>
These settings can have an extreme effect on the
search result: If a file exists in both folders, but the newer one is
not considered according to your time interval settings, the older file
will appear as missing file and you could overwrite the newer file
unintentionally.
<remark>Use these settings with care and always think before
deleting or overwriting files!</remark>
</para></note>

<sect2 id="komparator-regex">
<title>File name contains ... and not ...</title>
<para>
The regex fields can be used to narrow the search result down.
For example <keycap>*</keycap> can be used for a string of any length
(also zero length) and <keycap>?</keycap> for
exactly one character. For further information about regular expressions
please consult your friendly internet.
The regular expressions only apply to the file name.
All files are reported that match the first expression and at the same time not the second one.
If a file name matches both fields, it will be excluded.
</para>

<example><title>Regex example</title><para>
<userinput>[a-d]*[^1-3]</userinput> will find files that
begin with a character <keycap>a</keycap> through <keycap>d</keycap>,
have any length plus 2 (the first and the last character), and don't have
the numbers <keycap>1</keycap> through <keycap>3</keycap> as the last character.
</para></example>

</sect2>

<sect2 id="komparator-size">
<title>Size</title>
<para>
The size input section can be used to find only files that have at least, at most
or exactly the spezified size.
<note><para><keycap>1 KB = 1024 Bytes</keycap>
and <keycap>1 MB = 1024 KB = 1,048,576 Bytes</keycap>.
</para></note>
</para>

</sect2>

<sect2 id="komparator-time">
<title>Modification or creation time</title>
<para>
Here you can select the time interval when the files you want to find
were created or modified.
</para>

<note><para>
On remote / not *nix file systems, this might not be displayed correctly, as copying
can change the modification time on these systems.
</para></note>

<para>
You can choose:
<itemizedlist>

<listitem><para><emphasis>any</emphasis>: No restriction. (default)
</para></listitem>

<listitem><para><emphasis>between date x and date y</emphasis>:
Files that were created or modified between date x and date y
are found (including date x and y).
</para></listitem>

<listitem><para><emphasis>during the last z ...</emphasis>:
Files that were created or modified during the last z minutes, hours, days, months
or years are found, including the current minute, hour, day, month, year.
</para>
<example id="mod_time_example">
<title>Modified during the last ...</title>
<para>
If you are searching on 10th of July for files created or modified during the last 5 days,
files from 6th of July are found but not from 5th.
</para>
</example>
</listitem>

</itemizedlist>
</para>

</sect2>

</sect1>

<sect1 id="komparator-settings">
<title>Settings</title>

<screenshot>
<screeninfo>Settings</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_settings.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Settings</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<sect2 id="komparator-settings-warnings">
<title>Warnings</title>

<para>
Show warning dialogs when
<itemizedlist>
<listitem><para>Trashing files</para></listitem>
<listitem><para>Deleting files</para></listitem>
<listitem><para>Overwriting files when copying files</para></listitem>
<listitem><para>Overwriting files when moving files</para></listitem>
<listitem><para>Reloading the search result</para></listitem>
<listitem><para>Removing a preset</para></listitem>
</itemizedlist>
These warnings can also be switched off in the warning dialogs directly.
</para>

</sect2>

<sect2 id="komparator-settings-misc">
<title>Misc</title>

<sect3 id="komparator-settings-misc-systray">
<title>System tray icon</title>

<para>
Show an icon in the system tray.
If the system tray icon is shown, notifications will appear close to it.
</para>

</sect3>

<sect3 id="komparator-settings-misc-notification">
<title>Notifications</title>

<para>
Show passive notifications, if a user interaction, such as searching, copying or deleting, was completed.
These notifications will only appear, if the program window is not the active window
(e.g. is minimized or reduced to the system tray icon).
</para>

</sect3>

<sect3 id="komparator-settings-misc-text-color">
<title>Komparator text color theme</title>

<para>
Enable komparator text color theme, used to show differences in duplicate files and newer files.
Disable it, if you want to use a KDE color theme, that has bad contrast with komparator text colors.
</para>

</sect3>

</sect2>

</sect1>

<sect1 id="komparator-preset">
<title>Preset</title>

<screenshot>
<screeninfo>Preset</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_preset.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Preset</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
Presets can simplify your life, if you perform a specific
kind of search regularly. Choosing a preset will set the gui to the preset's settings.
If the preset has empty URLs, the current URLs aren't changed, if it is selected.
</para>

<para>

You can

<itemizedlist>
<listitem><para>
<emphasis>Add a preset</emphasis>: All current settings will be saved as they are.
You can choose a name for the preset (that will be displayed in the combo box), and the URLs.
If URLs are given, choosing the preset later will set the URL fields to these URLs.
If the given URLs are empty, choosing the preset won't change the currently selected URLs.
</para>
</listitem>

<listitem><para>
<emphasis>Save to the current preset</emphasis>: Overwrite the currently selected preset by
the current settings of the GUI. You cannot change the name but the URLs.
</para></listitem>

<listitem><para>
<emphasis>Remove the current preset</emphasis>: Remove the current preset selecting the preset above.
</para></listitem>
</itemizedlist>

<note><para>
No changes can be done to the <emphasis>default</emphasis> preset.
</para></note>

</para>

</sect1>

<sect1 id="komparator-enable-tab">
<title>Enable/Disable result tab</title>

<screenshot>
<screeninfo>Enable tab</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_enable_tab.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Enable tab</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
Enable or disable tabs by clicking on the icons. If you don't need the result of one tab,
you can disable it to have a slight search speed improvement. Disabling both
<emphasis>missing</emphasis> and <emphasis>newer tab</emphasis> (with enabled
<emphasis>Size comparison</emphasis> check box) disables the sub path comparison, which
will lead to a significant search speed improvement.
</para>
</sect1>

<sect1 id="komparator-search-button">
<title>Search button</title>

<screenshot>
<screeninfo>Search button</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_search_button.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Search button</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
When you have made all settings just hit the <keycap>Search</keycap> button to start the search.
You can cancel the operation at any time. It might take some time to cancel,
as &komparator; needs to finish the ongoing sub-process and delete temporary files.
If the search has finished, you can clear the search and start a new one.
</para>

</sect1>

</chapter>


<chapter id="komparator-result">
<title>Search result</title>

<para>
After a successful search and compare operation, &komparator; shows the search result.
The <emphasis>duplicates search options</emphasis>, the <emphasis>presets</emphasis>
and the <emphasis>find empty folders</emphasis> option are not changable in this stage,
as these settings can affect the program's reaction on delete / copy / move events.
</para>
<para>
Now you can interact with the found files, which can be done in
five ways:

<itemizedlist>
<listitem><para>
Using the context menu which will appear when you right-click on any file. This is
an important way, because some options are only available in this menu: Trash or delete
files from the <link linkend="komparator-result-duplicates-coref">non-reference folder</link>
(only in the <emphasis>Duplicate files</emphasis> tab),
compare the two selected files (only in the <emphasis>Missing files</emphasis> and the
<emphasis>Newer files</emphasis> tabs) and compare the newer files pair
(only in the <emphasis>Newer files</emphasis> tab).
</para></listitem>

<listitem><para>
Using the keyboard with the shortcuts
<keycap>Enter</keycap> or <keycap>Return</keycap> for opening selected files,
<keycap>Del</keycap> to throw the selected files away,
<keycap>Ctrl+Del</keycap> to delete the selected files and
<keycap>Ctrl+C</keycap> to copy the selected files (to paste them in konqueror,
for example).
</para></listitem>

<listitem><para>
Double click on a file will open it.
</para></listitem>

<listitem><para>
Using the buttons on the GUI. For example, the <keycap>>> Remove</keycap> buttons
remove the selected files from the list (here from the list on the left), but don't delete them.
</para></listitem>

<listitem><para>
Using drag and drop. This option is only available for missing or newer files,
where you can drag files from one side to the other. Holding a <keycap>Shift</keycap>
button down will move the selected files to the other side, a <keycap>Control</keycap>
button will copy them. Otherwise you will be asked what to do.
</para></listitem>

</itemizedlist>
</para>

<sect1 id="komparator-result-duplicates">
<title>Duplicate files</title>

<screenshot>
<screeninfo>Duplicate files tab</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_duplicates.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Duplicate files tab</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
In the uppermost list view all files that have duplicates are displayed.
The filename / path displayed is the one that was found first.
</para>
<para>
<anchor id="duplicates_black"/>
Black colored items are duplicates, that appear in both searched folders
and only in them. That means, there are exactly two duplicate files, and
both have the same relative path.
</para>
<para>
<anchor id="duplicates_blue"/>
Blue colored ones are duplicates by file size (and MD5 checksum and binary
comparison), that <emphasis>do not</emphasis> match the restrictions
mentioned above.
</para>
<para>
If one item is selected, all files that are equal will appear in the
lower list view (also the file that is listed in the upper list view).
Single file interactions done in the upper list view affect only the file that
is displayed.
</para>
<para>
If several files are selected in the upper list view, the last file that was selected
is displayed in the lower list view, together with its duplicate files.
</para>
<para>
If there is only one file in the duplicate list view left, it is removed
from the upper list view, because it is no duplicate file any more, and
it is displayed in the <emphasis>missing files</emphasis> list.
A single empty folder remains until it is deleted.
</para>

<sect2 id="komparator-result-duplicates-coref">
<title>Reference and non-reference folders</title>
<para>
The blue / green color of the items in the lower list view is useful
to identify which searched folder is the parent of the duplicate file.
You can set one of the parent folders (left URL or right URL) as the
<emphasis>reference folder</emphasis> (the folder, you want to keep as it is).
The other folder is the <emphasis>non-reference folder</emphasis>
(the folder, you want to remove duplicate files from).
When selecting a new file in the upper list view, the files from the <emphasis>non-reference folder</emphasis>
are automatically selected in the lower list view, to make it easier for you to delete them.
</para>
<para>
You can directly delete all duplicate files of the selected files
in the upper list view, that are in the <link linkend="komparator-result-duplicates-coref">non-reference folder</link>.
This option is only available in the context menu (right click on a file to see this menu):
<emphasis>Trash non-reference files</emphasis> or <emphasis>Delete non-reference files</emphasis>.
</para>
</sect2>

</sect1>

<sect1 id="komparator-result-missing">
<title>Missing files</title>

<screenshot>
<screeninfo>Missing files tab</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_missing.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Missing files tab</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
Here all files are listed that appear only in one folder. The search for
missing files is done only be comparing relative paths and file names.
Files can be missing in the other folder but - at the same time - be
duplicates by file size, and therefore appear in both lists.
</para>
<para>
You can compare two selected files, if theres exactly one selected file on
each side. The file compare dialog is opened by right clicking on one of the
selected items and choosing <emphasis>Compare selected files</emphasis>.
</para>

</sect1>

<sect1 id="komparator-result-newer">
<title>Newer files</title>

<screenshot>
<screeninfo>Newer files tab</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_newer.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Newer files tab</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
All files that do not appear as duplicate or missing files (or even if they are
duplicates but one of them is newer) appear here.
</para>
<para>
<anchor id="newer_blue"/>
If two relative paths and filenames are equal, but one file is newer than the other,
the newer item is colored black and the older one blue.
</para>
<para>
<anchor id="newer_purple"/>
But the timestamp can be treacherous: On non-local filesystems, the
timestamp can be the time when you copied the file, but not when you modified it.
On these filesystems you will always find newer files, although they are duplicates.
&komparator; will warn you in this case: If the two files are duplicates, the
older file will be colored purple instead of blue.
</para>
<para>
<anchor id="newer_red"/>
If two files have the same relative path and filename and also the same timestamp, but
are different, both files are displayed in red.
</para>
<para>
The last two color options are only available if you at least
enabled <keycap>Size comparison</keycap> in the
<keycap>Duplicate Files Search Options</keycap>.
</para>
<para>
You can compare two selected files as in the <keycap>Missing files</keycap> tab.
Additionally, you can compare the two files that have the same relative paths.
In this case, only one file may be selected in the current list view.
</para>

</sect1>

<sect1 id="komparator-result-filters">
<title>Filters</title>

<para>
Filters are used to display only files, that match your filter settings. The corresponding counter
displays the number of the currently shown items. If not all files are displayed
(and some are filtered out), the filter button and the counter have a blue background color:
</para>

<screenshot>
<screeninfo>Filters</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_filters.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Filters</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
Some self-explaining filter options are available in each filter widget:
</para>

<screenshot>
<screeninfo>Missing Files Filter</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_filter_missing.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Missing Files Filter</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
The filter for the duplicate files has two extra options:
<itemizedlist>
<listitem><para><keycap>Duplicate files pair</keycap>: Show all black colored items as explained
<link linkend="duplicates_black">above</link>.</para></listitem>
<listitem><para><keycap>Multiple duplicates</keycap>: Show all blue colored items as explained
<link linkend="duplicates_blue">above</link>.</para></listitem>
</itemizedlist>
</para>

<screenshot>
<screeninfo>Duplicate Files Filter</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_filter_duplicates.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Duplicate Files Filter</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<para>
The filter for newer files has three extra options:
<itemizedlist>
<listitem><para><keycap>Real newer files</keycap>: Show all blue colored items (or the correspondig black
colored items) as explained <link linkend="newer_blue">above</link>.</para></listitem>
<listitem><para><keycap>Newer but equal files</keycap>: Show all purple colored items (or the correspondig black
colored items) as explained.<link linkend="newer_purple">above</link>.</para></listitem>
<listitem><para><keycap>Different files with same time stamp</keycap>: Show all red colored items as explained
<link linkend="newer_red">above</link>.</para></listitem>
</itemizedlist>
</para>

<screenshot>
<screeninfo>Newer Files Filter</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="komparator_filter_newer.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Newer Files Filter</phrase>
		</textobject>
	</mediaobject>
</screenshot>

</sect1>

</chapter>


<chapter id="komparator-background">
<title>Background information</title>

<para>
This chapter intends to give you an overview, how &komparator; works
<quote>behind the scenes</quote>.
</para>

<sect1 id="komparator-background-files-search">
<title>Files search</title>

<para>
&komparator; uses the same search engine as KFind. Komparator will have the
same (search related) bugs as KFind.
</para>

<para>
This search engine reports an object that it has found (and that matched
user's parameters like regular expressions, ...) to the main program.
The main program checks, whether the reported object is a file /
link to a file or a folder. If it is a linked folder, it is searched
seperately. If this would lead to an infinitive loop (the link points to
its parent directory in some way), it is not searched.
</para>
<para>
If it's a folder and if it is empty, it is stored in memory,
if you decided to search for empty folders.
</para>
<para>
If it's a file (or a symlink, if you decided to "Follow symlinks") it is
stored in memory for duplicate / missing / newer file search.
If you decided to find empty folders, empty folders are added to
duplicates list view now.
</para>

</sect1>

<sect1 id="komparator-background-duplicate-files-search">
<title>Duplicate files search</title>

<para>
In this second step all files found with the search engine are searched for duplicate files.
</para>
<para>
This is done in the following way: The files are sorted by size; if two files
have the same size, an (optional) MD5 checksum and binary comparison is calculated
and only if all parameters (size, MD5, bin) were equal, the file is recorded as
duplicate of the other one.
</para>

</sect1>

<sect1 id="komparator-background-missing-files-search">
<title>Missing / newer files search</title>

<para>
This third step compares the paths + filenames relative to the searched directory.
</para>
<para>
An example: If you are searching the URLs <filename>/mnt/backup</filename> and
<filename>/home/user</filename>, the files <filename>/mnt/backup/emails</filename>
and <filename>/home/user/emails</filename> both have the relative file name
<filename>./emails</filename> and are therefore equal.
</para>
<para>
These relative paths + file names are sorted by length, and if they have the same
length, they are sorted alphabetically.
</para>

<para>
Now different possibilities must be considered:
</para>

<itemizedlist>

<listitem>
<para>
A file can have no duplicate by relative path + file name, so the file is missing
in the other folder.
</para>
</listitem>

<listitem>
<para>
It can have a duplicate by file name and one file is newer than the other one.
In this case, the files can be real duplicates (and appear in the duplicate list view),
but are also shown in the "Newer files" list view.
</para>
</listitem>

<listitem>
<para>
It can have a duplicate by file name, but both files have the same timestamp.
If the files are equal (checked by MD5 checksum and binary comparison),
they are not considered any more, as they were found in the duplicate files search
(before).
</para>
</listitem>

<listitem>
<para>
If the files have the same file name and timestamp, but are <emphasis>not</emphasis>
equal (very unlikely), they are reported in the "Newer files" list view, but marked
red to warn the user, that there is something wrong.
</para>
</listitem>

</itemizedlist>

</sect1>

</chapter>


<!--<chapter id="faq">
<title>Questions and Answers</title>-->

<!--&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question>
<para>My Mouse doesn't work. How do I quit &komparator;?</para>
</question>
<answer>
<para>You silly goose! Check out the <link linkend="commands">Commands
Section</link> for the answer.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why can't I twiddle my documents?</para>
</question>
<answer>
<para>You can only twiddle your documents if you have the foobar.lib
installed.</para>
</answer>
</qandaentry>
</qandaset>
</chapter>-->

<chapter id="credits">

<title>Credits and License</title>

<para>
&komparator;
</para>
<para>
Program copyright 2005-2006 Georg Hennig <email>georg.hennig@web.de</email>
</para>
<!--<para>
Contributors:
<itemizedlist>
<listitem><para>Konqui the KDE Dragon <email>konqui@kde.org</email></para>
</listitem>
<listitem><para>Tux the Linux Penguin <email>tux@linux.org</email></para>
</listitem>
</itemizedlist>
</para>-->

<para>
Documentation copyright 2005-2006 Georg Hennig <email>georg.hennig@web.de</email>
</para>

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

&underGPL; <!-- GPL License -->

</chapter>

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

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

<para>
&komparator; can be downloaded from the <ulink url="http://sourceforge.net/projects/komparator">
Sourceforge project page</ulink>.
</para>

<para>
For news or bug reports visit the <ulink url="http://komparator.sourceforge.net">
&komparator; sourceforge home page</ulink>.
</para>

</sect1>

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

<!--
List any special requirements for your application here. This should include:
.Libraries or other software that is not included in kdesupport,
kdelibs, or kdebase.
.Hardware requirements like amount of RAM, disk space, graphics card
capabilities, screen resolution, special expansion cards, etc.
.Operating systems the app will run on. If your app is designed only for a
specific OS, (you wrote a graphical LILO configurator for example) put this
information here.
-->

<para>
In order to use &komparator;, you need &kde; 3.4 or higher.
</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:tabstop=2:shiftwidth=2:expandtab 
-->