Open Source Projects Europe

  Jean-Francois Dockes

  Jean-Francois Dockes

   <jfd@recoll.org>

   <jfd@recoll.org>

   This document introduces full text search notions and describes the

   This document introduces full text search notions and describes the

   installation and use of the Recoll application. It currently describes

   installation and use of the Recoll application. It currently describes

   [ Split HTML / Single HTML ]

   [ Split HTML / Single HTML ]

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

   4. Programming interface

   4. Programming interface

                4.1. Writing a document filter

                4.1. Writing a document filter

                4.2. Field data processing

                4.2. Field data processing

                4.3. API

                4.3. API

   something like /usr/[local/]share/recoll/examples) during installation.

   something like /usr/[local/]share/recoll/examples) during installation.

   The default parameters from this file may be overridden by values that you

   The default parameters from this file may be overridden by values that you

   set inside your personal configuration, found by default in the .recoll

   set inside your personal configuration, found by default in the .recoll

   sub-directory of your home directory. The default configuration will index

   sub-directory of your home directory. The default configuration will index

   your home directory with default parameters and should be sufficient for

   your home directory with default parameters and should be sufficient for

   Indexing is started automatically the first time you execute the recoll

   Indexing is started automatically the first time you execute the recoll

   search graphical user interface, or by executing the recollindex command.

   search graphical user interface, or by executing the recollindex command.

   Searches are usually performed inside the recoll graphical user interface

   Searches are usually performed inside the recoll graphical user interface

2.1. Introduction

2.1. Introduction

   Indexing is the process by which the set of documents is analyzed and the

   Indexing is the process by which the set of documents is analyzed and the

   data entered into the database. Recoll indexing is normally incremental:

   data entered into the database. Recoll indexing is normally incremental:

   documents will only be processed if they have been modified. On the first

   documents will only be processed if they have been modified. On the first

   Recoll indexing can be performed with two different methods:

   Recoll indexing can be performed with two different methods:

     * Periodic indexing: indexing takes place at discrete times, by

     * Periodic indexing: indexing takes place at discrete times, by

       executing the recollindex command. The typical usage is to have a

       executing the recollindex command. The typical usage is to have a

   The choice between the two methods is mostly a matter of preference, and

   The choice between the two methods is mostly a matter of preference, and

   they can be combined by setting up multiple indexes (ie: use periodic

   they can be combined by setting up multiple indexes (ie: use periodic

   indexing on a big documentation directory, and real time indexing on a

   indexing on a big documentation directory, and real time indexing on a

   small home directory). Monitoring a big file system tree can consume

   small home directory). Monitoring a big file system tree can consume

   significant system resources.

   significant system resources.

   Recoll knows about quite a few different document types. The parameters

   Recoll knows about quite a few different document types. The parameters

   for document types recognition and processing are set in configuration

   for document types recognition and processing are set in configuration

   files.

   files.

   compound ones. Such hierarchies can go quite deep, and Recoll has no

   compound ones. Such hierarchies can go quite deep, and Recoll has no

   problem processing, for example, an ms-word document which would be an

   problem processing, for example, an ms-word document which would be an

   attachment to an email message part of a folder file archived inside a zip

   attachment to an email message part of a folder file archived inside a zip

   file...

   file...

   Recoll indexing processes plain text, HTML, openoffice and e-mail files

   Other file types (ie: postscript, pdf, ms-word, rtf ...) need external

   Other file types (ie: postscript, pdf, ms-word, rtf ...) need external

   applications for preprocessing. The list is in the installation section.

   applications for preprocessing. The list is in the installation section.

   After every indexing operation, Recoll updates a list of commands that

   After every indexing operation, Recoll updates a list of commands that

   would be needed for indexing existing files types. This list can be

   would be needed for indexing existing files types. This list can be

       different areas of the file system to different indexes. For example,

       different areas of the file system to different indexes. For example,

       if you were to issue the following commands:

       if you were to issue the following commands:

 export RECOLL_CONFDIR=~/.indexes-email

 export RECOLL_CONFDIR=~/.indexes-email

 recoll

 recoll

       Then Recoll would use configuration files stored in ~/.indexes-email/

       Then Recoll would use configuration files stored in ~/.indexes-email/

       and, (unless specified otherwise in recoll.conf) would look for the

       and, (unless specified otherwise in recoll.conf) would look for the

       index in ~/.indexes-email/xapiandb/.

       index in ~/.indexes-email/xapiandb/.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

  2.2.1. Xapian index formats

  2.2.1. Xapian index formats

   Unfortunately, using the -z option to recollindex is not sufficient to

   Unfortunately, using the -z option to recollindex is not sufficient to

   (typically ~/.recoll/xapiandb) before starting indexing.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

  2.2.2. Security aspects

  2.2.2. Security aspects

   The Recoll index does not hold copies of the indexed documents. But it

   The Recoll index does not hold copies of the indexed documents. But it

   does hold enough data to allow for an almost complete reconstruction. If

   does hold enough data to allow for an almost complete reconstruction. If

   confidential data is indexed, access to the database directory should be

   confidential data is indexed, access to the database directory should be

   restricted.

   restricted.

   mode of 0700 (access by owner only). As the index data directory is by

   mode of 0700 (access by owner only). As the index data directory is by

   default a sub-directory of the configuration directory, this should result

   default a sub-directory of the configuration directory, this should result

   in appropriate protection.

   in appropriate protection.

   If you use another setup, you should think of the kind of protection you

   If you use another setup, you should think of the kind of protection you

2.5. Periodic indexing

2.5. Periodic indexing

  2.5.1. Running indexing

  2.5.1. Running indexing

   Indexing is performed either by the recollindex program, or by the

   Indexing is performed either by the recollindex program, or by the

   programs will use the RECOLL_CONFDIR variable or accept a -c confdir

   option to specify a non-default configuration directory.

   option to specify a non-default configuration directory.

     * Starting the indexing thread is more convenient, being just one click

     * Starting the indexing thread is more convenient, being just one click

       away.

       away.

     * The recollindex command has more options, especially the one to reset

     * The recollindex command has more options, especially the one to reset

     * The recollindex command will not take down your GUI if it crashes (a

     * The recollindex command will not take down your GUI if it crashes (a

       rare occurrence, but who knows...)

       rare occurrence, but who knows...)

     * The recollindex command uses setpriority/nice to lower its priority

     * The recollindex command uses setpriority/nice to lower its priority

       interface.

   If the recoll program finds no index when it starts, it will automatically

   If the recoll program finds no index when it starts, it will automatically

   start indexing (except if canceled).

   start indexing (except if canceled).

   The recollindex indexing process can be interrupted by sending an

   The recollindex indexing process can be interrupted by sending an

   index.

   index.

   The real time indexing support can be customised during package

   The real time indexing support can be customised during package

   configuration with the --with[out]-fam or --with[out]-inotify options. The

   configuration with the --with[out]-fam or --with[out]-inotify options. The

   default is currently to include inotify monitoring on systems that support

   default is currently to include inotify monitoring on systems that support

   The rclmon.sh script can be used to easily start and stop the daemon. It

   The rclmon.sh script can be used to easily start and stop the daemon. It

   can be found in the examples directory (typically

   can be found in the examples directory (typically

   /usr/local/[share/]recoll/examples).

   /usr/local/[share/]recoll/examples).

 recollconf=$HOME/.recoll-home

 recollconf=$HOME/.recoll-home

 recolldata=/usr/local/share/recoll

 recolldata=/usr/local/share/recoll

 RECOLL_CONFDIR=$recollconf $recolldata/examples/rclmon.sh start

 RECOLL_CONFDIR=$recollconf $recolldata/examples/rclmon.sh start

 fvwm

   The indexing daemon gets started, then the window manager, for which the

   The indexing daemon gets started, then the window manager, for which the

   session waits.

   session waits.

   By default the indexing daemon will monitor the state of the X11 session,

   By default the indexing daemon will monitor the state of the X11 session,

   Under KDE, you can place a small script to start recollindex -m under

   Under KDE, you can place a small script to start recollindex -m under

   $HOME/.kde/Autostart. This will be executed when the session begins.

   $HOME/.kde/Autostart. This will be executed when the session begins.

   There is a similar mechanism under Gnome (find the session control tool in

   There is a similar mechanism under Gnome (find the session control tool in

   the menus and use the "Startup programs" tab).

   the menus and use the "Startup programs" tab).

   By default, the messages from the indexing daemon will be discarded. You

   By default, the messages from the indexing daemon will be discarded. You

   may want to change this by setting the daemlogfilename and daemloglevel

   may want to change this by setting the daemlogfilename and daemloglevel

   configuration parameters. Also the log file will only be truncated when

   configuration parameters. Also the log file will only be truncated when

   the daemon starts. If the daemon runs permanently, the log file may grow

   the daemon starts. If the daemon runs permanently, the log file may grow

   can be resized, and their order can be changed (by dragging). All the

   can be resized, and their order can be changed (by dragging). All the

   changes are recorded when you quit recoll

   changes are recorded when you quit recoll

   Hovering over a table row will update the detail area at the bottom of the

   Hovering over a table row will update the detail area at the bottom of the

   window with the corresponding values. You can click the row to freeze the

   window with the corresponding values. You can click the row to freeze the

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

  3.1.4. The preview window

  3.1.4. The preview window

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

  3.1.9. Sorting search results and collapsing duplicates

  3.1.9. Sorting search results and collapsing duplicates

   The documents in a result list are normally sorted in order of relevance.

   The documents in a result list are normally sorted in order of relevance.

   Sort parameters are remembered between program invocations, but result

   Sort parameters are remembered between program invocations, but result

   sorting is normally always inactive when the program starts. It is

   sorting is normally always inactive when the program starts. It is

   possible to keep the sorting activation state between program invocations

   possible to keep the sorting activation state between program invocations

   by checking the Remember sort activation state option in the preferences.

   by checking the Remember sort activation state option in the preferences.

   but will give a relevance boost to the results where the search terms

   but will give a relevance boost to the results where the search terms

   appear as a phrase. Ie: searching for virtual reality will still find all

   appear as a phrase. Ie: searching for virtual reality will still find all

   documents where either virtual or reality or both appear, but those which

   documents where either virtual or reality or both appear, but those which

   contain virtual reality should appear sooner in the list.

   contain virtual reality should appear sooner in the list.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

    3.1.10.3. Others

    3.1.10.3. Others

   Using fields. You can use the query language and field specifications to

   Using fields. You can use the query language and field specifications to

   the parameters used for searching and returning results, and what indexes

   the parameters used for searching and returning results, and what indexes

   are searched.

   are searched.

   User interface parameters:

   User interface parameters:

     * Highlight color for query terms: Terms from the user query are

     * Highlight color for query terms: Terms from the user query are

       highlighted in the result list samples and the preview window. The

       highlighted in the result list samples and the preview window. The

       color can be chosen here. Any Qt color string should work (ie red,

       color can be chosen here. Any Qt color string should work (ie red,

       #ff0000). The default is blue.

       #ff0000). The default is blue.

     * Maximum text size highlighted for preview Inserting highlights on

     * Maximum text size highlighted for preview Inserting highlights on

       search term inside the text before inserting it in the preview window

       search term inside the text before inserting it in the preview window

       involves quite a lot of processing, and can be disabled over the given

       involves quite a lot of processing, and can be disabled over the given

       text size to speed up loading.

       text size to speed up loading.

     * Use desktop preferences to choose document editor: if this is checked,

     * Use desktop preferences to choose document editor: if this is checked,

       the xdg-open utility will be used to open files when you click the

       the xdg-open utility will be used to open files when you click the

       Open link in the result list, instead of the application defined in

       Open link in the result list, instead of the application defined in

       mimeview. xdg-open will in term use your desktop preferences to choose

       mimeview. xdg-open will in term use your desktop preferences to choose

     * Remember sort activation state if set, Recoll will remember the sort

     * Remember sort activation state if set, Recoll will remember the sort

       tool stat between invocations. It normally starts with sorting

       tool stat between invocations. It normally starts with sorting

       disabled.

       disabled.

   Search parameters:

   Search parameters:

     * Stemming language: stemming obviously depends on the document's

     * Stemming language: stemming obviously depends on the document's

       language. This listbox will let you chose among the stemming databases

       language. This listbox will let you chose among the stemming databases

       which were built during indexing (this is set in the main

       which were built during indexing (this is set in the main

       configuration file), or later added with recollindex -s (See the

       configuration file), or later added with recollindex -s (See the

       recollindex manual). Stemming languages which are dynamically added

       recollindex manual). Stemming languages which are dynamically added

       will be deleted at the next indexing pass unless they are also added

       will be deleted at the next indexing pass unless they are also added

       in the configuration file.

       in the configuration file.

       automatically built and added to simple searches when looking for Any

       automatically built and added to simple searches when looking for Any

       terms. This will give a relevance boost to the results where the

       terms. This will give a relevance boost to the results where the

       search terms appear as a phrase (consecutive and in order).

       search terms appear as a phrase (consecutive and in order).

     * Replace abstracts from documents: this decides if we should synthesize

     * Replace abstracts from documents: this decides if we should synthesize

       and display an abstract in place of an explicit abstract found within

       and display an abstract in place of an explicit abstract found within

       the document itself.

       the document itself.

   alternative indexer may also need to implement a way of purging the index

   alternative indexer may also need to implement a way of purging the index

   from stale data,

   from stale data,

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

    3.1.11.1. The result list format

   will be performed:

     * %A. Abstract

     * %A. Abstract

     * %D. Date

     * %D. Date

     * %K. Keywords (if any)

     * %K. Keywords (if any)

     * %L. Preview and Edit links

     * %M. Mime type

     * %M. Mime type

     * %R. Relevance percentage

     * %R. Relevance percentage

     * %S. Size information

     * %S. Size information

     * %T. Title

     * %T. Title

     * %U. Url

     * %U. Url

   The format of the Preview and Edit links is <a href="P%N"> and <a

   The format of the Preview and Edit links is <a href="P%N"> and <a

   href="E%N"> where docnum (%N expands to the document number inside the

   In addition to the predefined values above, all strings like %(fieldname)

   In addition to the predefined values above, all strings like %(fieldname)

   will be replaced by the value of the field named fieldname for this

   will be replaced by the value of the field named fieldname for this

   document. Only stored fields can be accessed in this way, the value of

   document. Only stored fields can be accessed in this way, the value of

   indexed but not stored fields is not known at this point in the search

   indexed but not stored fields is not known at this point in the search

   The default value for the paragraph format string is:

   The default value for the paragraph format string is:

 <img src="%I" align="left">%R %S %L &nbsp;&nbsp;<b>%T</b><br>

 <img src="%I" align="left">%R %S %L &nbsp;&nbsp;<b>%T</b><br>

 %M&nbsp;%D&nbsp;&nbsp;&nbsp;<i>%U</i>&nbsp;%i<br>

 %M&nbsp;%D&nbsp;&nbsp;&nbsp;<i>%U</i>&nbsp;%i<br>

 %A %K

 %A %K

   You may, for example, try the following for a more web-like experience:

   You may, for example, try the following for a more web-like experience:

 <u><b><a href="P%N">%T</a></b></u><br>

 <u><b><a href="P%N">%T</a></b></u><br>

 %A<font color=#008000>%U - %S</font> - %L

 %A<font color=#008000>%U - %S</font> - %L

   Or the clean looking:

   Or the clean looking:

 <img src="%I" align="left">%L <font color="#900000">%R</font>

 <img src="%I" align="left">%L <font color="#900000">%R</font>

   <b>%T</b><br>%S

 <font color="#808080"><i>%U</i></font>

 <font color="#808080"><i>%U</i></font>

 <table bgcolor="#e0e0e0">

 <table bgcolor="#e0e0e0">

 <tr><td><div>%A</div></td></tr>

 <tr><td><div>%A</div></td></tr>

 </table>%K

 </table>%K

   Note that the P%N link in the above paragraph makes the title a preview

   Note that the P%N link in the above paragraph makes the title a preview

   link.

   link.

   It is also possible to define the value of the snippet separator inside

   It is also possible to define the value of the snippet separator inside

   the abstract section.

   the abstract section.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

         window.location.href = 'recoll://search/query?qtp=a&p=0&q=' +

         window.location.href = 'recoll://search/query?qtp=a&p=0&q=' +

             encodeURIComponent(t);

             encodeURIComponent(t);

     }

     }

 </script>

 </script>

  ....

  ....

 <body ondblclick="recollsearch()">

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

3.3. Searching on the command line

3.3. Searching on the command line

   The query language processor is activated in the GUI simple search entry

   The query language processor is activated in the GUI simple search entry

   when the search mode selector is set to Query Language. It can also be

   when the search mode selector is set to Query Language. It can also be

   used with the KIO slave or the command line search. It broadly has the

   used with the KIO slave or the command line search. It broadly has the

   same capabilities as the complex search interface in the GUI.

   same capabilities as the complex search interface in the GUI.

   specification.

   If the results of a query language search puzzle you and you doubt what

   If the results of a query language search puzzle you and you doubt what

   has been actually searched for, you can use the GUI show query link at the

   has been actually searched for, you can use the GUI show query link at the

   top of the result list to check the exact query which was finally executed

   top of the result list to check the exact query which was finally executed

   by Xapian.

   by Xapian.

   Here follows a sample request that we are going to explain:

   Here follows a sample request that we are going to explain:

           author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes

           author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes

   This would search for all documents with John Doe appearing as a phrase in

   This would search for all documents with John Doe appearing as a phrase in

   the author field (exactly what this is would depend on the document type,

   the author field (exactly what this is would depend on the document type,

   ie: the From: header, for an email message), and containing either beatles

   ie: the From: header, for an email message), and containing either beatles

   or lennon and either live or unplugged but not potatoes (in any part of

   or lennon and either live or unplugged but not potatoes (in any part of

   As usual, words inside quotes define a phrase (the order of words is

   As usual, words inside quotes define a phrase (the order of words is

   significant), so that title:"prejudice pride" is not the same as

   significant), so that title:"prejudice pride" is not the same as

   title:prejudice title:pride, and is unlikely to find a result.

   title:prejudice title:pride, and is unlikely to find a result.

   Recoll currently manages the following default fields:

   Recoll currently manages the following default fields:

     * title, subject or caption are synonyms which specify data to be

     * title, subject or caption are synonyms which specify data to be

       searched for in the document title or subject.

       searched for in the document title or subject.

   The field syntax also supports a few field-like, but special, criteria:

   The field syntax also supports a few field-like, but special, criteria:

     * dir for filtering the results on file location (Ex:

     * dir for filtering the results on file location (Ex:

       dir:/home/me/somedir). -dir also works to find results out of the

       dir:/home/me/somedir). -dir also works to find results out of the

       specified directory, only after release 1.15.8.

     * date for searching or filtering on dates. The syntax for the argument

     * date for searching or filtering on dates. The syntax for the argument

       is based on the ISO8601 standard for dates and time intervals. Only

       is based on the ISO8601 standard for dates and time intervals. Only

       dates are supported, no times. The general syntax is 2 elements

       dates are supported, no times. The general syntax is 2 elements

       separated by a / character. Each element can be a date or a period of

       separated by a / character. Each element can be a date or a period of

       documents per file (ie: for zip or chm files). They communicate with

       documents per file (ie: for zip or chm files). They communicate with

       the indexer through a simple protocol, but are nevertheless a bit more

       the indexer through a simple protocol, but are nevertheless a bit more

       complicated than the older kind. Most of these new filters are written

       complicated than the older kind. Most of these new filters are written

       in Python, using a common module to handle the protocol.

       in Python, using a common module to handle the protocol.

   Recoll simple filters are usually shell-scripts, but this is in no way

   Recoll simple filters are usually shell-scripts, but this is in no way

   Filters are called with a single argument which is the source file name.

   Filters are called with a single argument which is the source file name.

   They should output the result to stdout.

   They should output the result to stdout.

   The RECOLL_FILTER_FORPREVIEW environment variable (values yes, no) tells

   The RECOLL_FILTER_FORPREVIEW environment variable (values yes, no) tells

   the filter if the operation is for indexing or previewing. Some filters

   the filter if the operation is for indexing or previewing. Some filters

   The association of file types to filters is performed in the mimeconf

   The association of file types to filters is performed in the mimeconf

 [index]

 application/msword = exec antiword -t -i 1 -m UTF-8;\

 application/msword = exec antiword -t -i 1 -m UTF-8;\

      mimetype = text/plain ; charset=utf-8

      mimetype = text/plain ; charset=utf-8

 application/ogg = exec rclogg

 application/ogg = exec rclogg

       and not output by unrtf in the HTML header section.

       and not output by unrtf in the HTML header section.

     * application/x-chm is processed by a persistant filter. This is

     * application/x-chm is processed by a persistant filter. This is

       determined by the execm keyword.

       determined by the execm keyword.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

   The output HTML could be very minimal like the following example:

   The output HTML could be very minimal like the following example:

 <html><head>

 <html><head>

 <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">

 <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">

 </head>

 </head>

 <body>some text content</body></html>

 <body>some text content</body></html>

   You should take care to escape some characters inside the text by

   You should take care to escape some characters inside the text by

   transforming them into appropriate entities. "&" should be transformed

   transforming them into appropriate entities. "&" should be transformed

   into "&amp;", "<" should be transformed into "&lt;". This is not always

   into "&amp;", "<" should be transformed into "&lt;". This is not always

   properly done by translating programs which output HTML, and of course

   properly done by translating programs which output HTML, and of course

           confdir specifies a Recoll configuration directory

           confdir specifies a Recoll configuration directory

           (the default is built like for any Recoll program).

           (the default is built like for any Recoll program).

           extra_dbs is a list of external databases (xapian directories)

           extra_dbs is a list of external databases (xapian directories)

           writable decides if we can index new data through this connection

           writable decides if we can index new data through this connection

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

    4.3.2.3. Example code

    4.3.2.3. Example code

   The following sample would query the index with a user language string.

   The following sample would query the index with a user language string.

         print k, ":", getattr(doc, k).encode('utf-8')

         print k, ":", getattr(doc, k).encode('utf-8')

     abs = db.makeDocAbstract(doc, query).encode('utf-8')

     abs = db.makeDocAbstract(doc, query).encode('utf-8')

     print abs

     print abs

     print

     print

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

                   Chapter 5. Installation and configuration

                   Chapter 5. Installation and configuration

     * --with-file-command Specify the version of the 'file' command to use

     * --with-file-command Specify the version of the 'file' command to use

       (ie: --with-file-command=/usr/local/bin/file). Can be useful to enable

       (ie: --with-file-command=/usr/local/bin/file). Can be useful to enable

       the gnu version on systems where the native one is bad.

       the gnu version on systems where the native one is bad.

     * Of course the usual autoconf configure options, like --prefix apply.

     * Of course the usual autoconf configure options, like --prefix apply.

   Normal procedure:

   Normal procedure:

         cd recoll-xxx

         cd recoll-xxx

         configure

         configure

         make

         make

         (practices usual hardship-repelling invocations)

         (practices usual hardship-repelling invocations)

   There is little auto-configuration. The configure script will mainly link

   There is little auto-configuration. The configure script will mainly link

   one of the system-specific files in the mk directory to mk/sysconf. If

   one of the system-specific files in the mk directory to mk/sysconf. If

   your system is not known yet, it will tell you as much, and you may want

   your system is not known yet, it will tell you as much, and you may want

   to manually copy and modify one of the existing files (the new file name

   to manually copy and modify one of the existing files (the new file name

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

5.4. Configuration overview

5.4. Configuration overview

   Most of the parameters specific to the recoll GUI are set through the

   Most of the parameters specific to the recoll GUI are set through the

   Preferences menu and stored in the standard Qt place

   Recoll indexing options are set inside text configuration files located in

   Recoll indexing options are set inside text configuration files located in

   a configuration directory. There can be several such directories, each of

   a configuration directory. There can be several such directories, each of

   which define the parameters for one index.

   which define the parameters for one index.

         # Space-separated list of directories to index.

         # Space-separated list of directories to index.

         topdirs =  ~/docs /usr/share/doc

         topdirs =  ~/docs /usr/share/doc

         [~/somedirectory-with-utf8-txt-files]

         [~/somedirectory-with-utf8-txt-files]

         defaultcharset = utf-8

         defaultcharset = utf-8

   There are three kinds of lines:

   There are three kinds of lines:

     * Comment (starts with #) or empty.

     * Comment (starts with #) or empty.

           A space-separated list of patterns for names of files or

           A space-separated list of patterns for names of files or

           directories that should be completely ignored. The list defined in

           directories that should be completely ignored. The list defined in

           the default file is:

           the default file is:

 skippedNames = #* bin CVS  Cache cache* caughtspam  tmp .thumbnails .svn \

 skippedNames = #* bin CVS  Cache cache* caughtspam  tmp .thumbnails .svn \

            *~ .beagle .git .hg .bzr loop.ps .xsession-errors \

            .recoll* xapiandb recollrc recoll.conf

           The list can be redefined at any sub-directory in the indexed

           The list can be redefined at any sub-directory in the indexed

           area.

           area.

           The top-level directories are not affected by this list (that is,

           The top-level directories are not affected by this list (that is,

           indexed at startup, but not monitored.

           indexed at startup, but not monitored.

           Example of use for skipping text files only in a specific

           Example of use for skipping text files only in a specific

           directory:

           directory:

   followLinks

   followLinks

           Specifies if the indexer should follow symbolic links while

           Specifies if the indexer should follow symbolic links while

           walking the file tree. The default is to ignore symbolic links to

           walking the file tree. The default is to ignore symbolic links to

           needed when the index is initialized. If this is not an absolute

           needed when the index is initialized. If this is not an absolute

           path, it will be interpreted relative to the configuration

           path, it will be interpreted relative to the configuration

           directory. The value can have embedded spaces but starting or

           directory. The value can have embedded spaces but starting or

           trailing spaces will be trimmed. You cannot use quotes here.

           trailing spaces will be trimmed. You cannot use quotes here.

   maxfsoccuppc

   maxfsoccuppc

           Maximum file system occupation before we stop indexing. The value

           Maximum file system occupation before we stop indexing. The value

           is a percentage, corresponding to what the "Capacity" df output

           is a percentage, corresponding to what the "Capacity" df output

           column shows. The default value is 0, meaning no checking.

           column shows. The default value is 0, meaning no checking.

           space-separated list, each entry being a pattern and a time in

           space-separated list, each entry being a pattern and a time in

           seconds, separated by a colon. You can use double quotes if a path

           seconds, separated by a colon. You can use double quotes if a path

           entry contains white space. Example:

           entry contains white space. Example:

 mondelaypatterns = *.log:20 "this one has spaces*:10"

 mondelaypatterns = *.log:20 "this one has spaces*:10"

   monixinterval

   monixinterval

           Minimum interval (seconds) for processing the indexing queue. The

           Minimum interval (seconds) for processing the indexing queue. The

           real time monitor does not process each event when it comes in,

           real time monitor does not process each event when it comes in,

 .blob = application/x-blobapp

 .blob = application/x-blobapp

       Note that the mime type is made up here, and you could call it

       Note that the mime type is made up here, and you could call it

       diesel/oil just the same.

       diesel/oil just the same.

     * In $RECOLL_CONFDIR/mimeview under the [view] section, add:

     * In $RECOLL_CONFDIR/mimeview under the [view] section, add:

 application/x-blobapp = blobviewer %f

 application/x-blobapp = blobviewer %f

       We are supposing that blobviewer wants a file name parameter here, you

       We are supposing that blobviewer wants a file name parameter here, you