<?xml version="1.0" ?>
<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<article id="nepomuk" lang="&language;">
<articleinfo>
<title>Nepomuk Desktop Search Configuration</title>

<authorgroup>
<author><firstname>Sebastian</firstname><surname>Trueg</surname><email>trueg@kde.org</email></author>
<author>&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<date>2013-11-01</date>
<releaseinfo>&kde; 4.12</releaseinfo>

<keywordset>
<keyword>KDE</keyword>
<keyword>KControl</keyword>
<keyword>nepomuk</keyword>
<keyword>desktop search</keyword>
</keywordset>
</articleinfo>
<!-- FIXME add links to 
http://techbase.kde.org/Projects/Nepomuk 
http://kdenepomukmanual.wordpress.com/2012/02/06/-->
<sect1 id="introduction">
<title>Introduction</title>

<para>This module allows to configure certain parts of the desktop search and the Nepomuk semantic desktop. More information
about the Nepomuk semantic desktop can be found at the <ulink url="http://nepomuk.kde.org/">Nepomuk homepage</ulink>.</para>

<sect2 id="basic">
<title>Basic Settings</title>

<para>The basic settings tab allows to enable or disable the semantic desktop and desktop search systems.</para>

<para>There are three checkboxes:</para>
<itemizedlist>
<listitem><para><guilabel>Enable Nepomuk Semantic Desktop</guilabel> Enabling the Nepomuk semantic desktop means that
the Nepomuk services are running. These services provide metadata/annotation storage (files can be tagged or rated in &dolphin;
for example) but also desktop search which can be used through the &kde; runner or again &dolphin;.</para></listitem>
<listitem><para><guilabel>Enable Nepomuk File Indexer</guilabel> Enabling the nepomuk file indexer means that
the file indexer service is started in addition to the standard services already running. The file indexer service will run through
all files in the configured folders (see below) and extract metadata from them (such as title or artist on music files or even
simple things like the creation date). This metadata is then exposed through the desktop search just like the manual annotations
mentioned earlier.</para></listitem>
<listitem><para><guilabel>Enable PIM Data Indexer</guilabel> This option has to be checked to allow full text search in 
&kmail;.</para></listitem>
</itemizedlist>

<para>On the right of <guilabel>Enable Nepomuk Semantic Desktop</guilabel> you can click on <guilabel>Details...</guilabel> and 
a dialog will inform you on the status of the KDE metadata store: how many files are indexed and the size of the store.</para>

<para>Under the <guilabel>Enable Nepomuk File Indexer</guilabel> checkbox the current status of the file indexing service is
shown. The service has four normal operation states:</para>
<itemizedlist>
<listitem><para><guilabel>File indexer is idle</guilabel> - The file indexer is currently not working and waiting for an event to
trigger an update (an event can be a newly created file or a changed file or a timeout for the recurring full check)</para></listitem>
<listitem><para><guilabel>Indexing files in folder foobar</guilabel> - The file indexer is currently running though
all files in folder foobar and analyzes new or changed files.</para></listitem>
<listitem><para><guilabel>Scanning for recent changes in files for desktop search</guilabel> - The file indexer is currently performing 
its recurring check for new files in all index folders. This check is intended to find files that were not caught through normal file 
system monitoring.</para></listitem>
<listitem><para><guilabel>File indexer is suspended</guilabel> - The file indexer has been suspended, &ie; it is in a paused state.
This can either be triggered by the user or due to low disk space or a laptop being in a power-saving state. In the two latter
cases the indexer will resume once the reason for the suspension has been resolved.</para></listitem>
</itemizedlist>

<para>Apart from the normal operation states the indexer service can have an erroneous state. There are two possibilities:</para>
<itemizedlist>
<listitem><para><guilabel>File indexing service failed to initialize, most likely due to an installation problem</guilabel> - This should rarely
occur that means that a mandatory plugin could not be loaded. This can be due to an installation problem (missing dependency) or due
to a faulty setup of the &kde; plugin system.</para></listitem>
<listitem><para>Any other error means a communication problem with the service. These errors are produced by the &DBus; subsystem and need
to be evaluated case by case.</para></listitem>
</itemizedlist>

</sect2>

<sect2 id="file-indexing">
<title>Indexing</title>

<para>This tab allows to select the files and folders that are to be analyzed by the file indexer explained
  above. By default Documents, Audio, Images and Videos are selected here. <!--Source Code-->
</para>

<para>Click the <guibutton>Customize Folders</guibutton> button to select and de-select folders that should be searched for files 
to be analyzed. By default the home folder and all subfolders are analyzed. By simply unchecking a folder it can be excluded. 
It is also possible to include a subfolder of an excluded one by checking it again. This allows a rather fine selection of the 
folders to be analyzed.</para>

<para>Clicking the <guibutton>Advanced</guibutton> button allows to define exclude filters using the mime type or the name of a file. 
The mime types and names of all files found in the configured folders will be matched against these filters. Only if none of them 
matches the file will be analyzed. This is very helpful to exclude log and backup files and the like.</para>

<para><guilabel>Removable media handling</guilabel>: Nepomuk can index files on removable devices like USB keys or external 
hard-disks for fast desktop searches. By default no files are indexed. Here this behaviour can be changed to one of two options:</para>
<itemizedlist>
<listitem><para><guilabel>Index files on all removable devices</guilabel> - Files on removable media are indexed as soon as the 
medium is mounted. Caution: this does not include media which have been rejected via the second option</para></listitem>
<listitem><para><guilabel>Ask individually when newly mounted</guilabel> - The user will be asked to decide if files on the 
newly mounted medium should be indexed or not. Once decided Nepomuk will not ask again.</para></listitem>
</itemizedlist>
</sect2>

<sect2 id="backup">
<title>Backup</title>

<para>On this tab you can decide to make a backup of all data that could not be restored otherwise. This includes
manually created tags, ratings but also statistical data. No backup is done as default so you need to decide what you want to do. 
You have two possibilities: automatic backups and manual ones.</para>

<sect3 id="automatic">
<title>Automatic Backups</title>
<para>First choose the <guilabel>Backup Frequency</guilabel>: this is set to <guilabel>Disable Automatic Backups</guilabel> but you 
can choose <guilabel>Daily Backup</guilabel> or <guilabel>Weekly Backup</guilabel>.
Then set the <guilabel>Backup Time:</guilabel> to anything convenient for you using the spinbox: you can set the hour and minutes 
and the day of the week for weekly backups.
Finally you can set a limit for the number of backup files using <guilabel>Max Number of Backups:</guilabel>.
This will ensure you do not waste disk space with the backup files and only the N last files will be kept, N being 
the number you set there, 10 as default.</para>
<para>Your automatic backups are saved locally in the following directory: 
<filename class="directory">$KDEHOME/share/apps/nepomuk/backupsync/backups/</filename>.</para>
</sect3>

<sect3 id="tools">
<title>Tools</title>
<itemizedlist>
<listitem><para><guilabel>Manual Backup...</guilabel>
You can also perform manual backups. Manual backups will be saved in your chosen location, as a file.
Click on <guilabel>Manual Backup...</guilabel> and a wizard will guide you. You first need to point to the location
of the backup file. Enter a full valid path in the field or use the file dialog to point to a file.</para>
<note><para>You can create a new file in the folder of your choice and then point to this new file.</para></note>
<para>Then click on the <guibutton>Next</guibutton> button and the dialog should report that the backup has been done.</para>
</listitem>
<listitem><para><guilabel>Restore Backup...</guilabel>
If you want to later restore your backup, use this button and follow the wizard. The backup will be merged
into the local Nepomuk database.
</para></listitem>
</itemizedlist>
</sect3>

</sect2>

</sect1>

</article>