Most of the parameters specific to the
recoll GUI are set through the
Preferences menu and stored in the standard Qt
place ($HOME/.config/Recoll.org/recoll.conf
).
You probably do not want to edit this by hand.
Recoll indexing options are set inside text configuration files located in a configuration directory. There can be several such directories, each of which defines the parameters for one index.
The configuration files can be edited by hand or through the Index configuration dialog (Preferences menu). The GUI tool will try to respect your formatting and comments as much as possible, so it is quite possible to use both approaches on the same configuration.
The most accurate documentation for the configuration parameters is given by comments inside the default files, and we will just give a general overview here.
For each index, there are at least two sets of
configuration files. System-wide configuration files are kept
in a directory named
like /usr/share/recoll/examples
,
and define default values, shared by all indexes. For each
index, a parallel set of files defines the customized
parameters.
The default location of the customized configuration is the
.recoll
directory in your home. Most people will only use this
directory.
This location can be changed, or others can be added with the
RECOLL_CONFDIR
environment variable or the
-c
option parameter to recoll and
recollindex.
In addition (as of Recoll version 1.19.7), it is possible
to specify two additional configuration directories which will
be stacked before and after the user configuration
directory. These are defined by
the RECOLL_CONFTOP
and RECOLL_CONFMID
environment
variables. Values from configuration files inside the top
directory will override user ones, values from configuration
files inside the middle directory will override system ones
and be overridden by user ones. These two variables may be of
use to applications which augment Recoll functionality, and
need to add configuration data without disturbing the user's
files. Please note that the two, currently single, values will
probably be interpreted as colon-separated lists in the
future: do not use colon characters inside the directory
paths.
If the .recoll
directory does not
exist when recoll or
recollindex are started, it will be created
with a set of empty configuration files.
recoll will give you a chance to edit the
configuration file before starting
indexing. recollindex will proceed
immediately. To avoid mistakes, the automatic directory
creation will only occur for the
default location, not if -c
or
RECOLL_CONFDIR
were used (in the latter
cases, you will have to create the directory).
All configuration files share the same format. For example, a short extract of the main configuration file might look as follows:
# Space-separated list of files and directories to index. topdirs = ~/docs /usr/share/doc [~/somedirectory-with-utf8-txt-files] defaultcharset = utf-8
There are three kinds of lines:
Comment (starts with #) or empty.
Parameter affectation (name = value).
Section definition ([somedirname]).
Long lines can be broken by ending each incomplete part with
a backslash (\
).
Depending on the type of configuration file, section definitions either separate groups of parameters or allow redefining some parameters for a directory sub-tree. They stay in effect until another section definition, or the end of file, is encountered. Some of the parameters used for indexing are looked up hierarchically from the current directory location upwards. Not all parameters can be meaningfully redefined, this is specified for each in the next section.
Important
Global parameters must not be defined in
a directory subsection, else they will not be found at all by the
Recoll code, which looks for them at the top level
(e.g. skippedPaths
).
When found at the beginning of a file path, the tilde character (~) is expanded to the name of the user's home directory, as a shell would do.
Some parameters are lists of strings. White space is used for separation. List elements with embedded spaces can be quoted using double-quotes. Double quotes inside these elements can be escaped with a backslash.
No value inside a configuration file can contain a newline character. Long lines can be continued by escaping the physical newline with backslash, even inside quoted strings.
astringlist = "some string \ with spaces" thesame = "some string with spaces"
Parameters which are not part of string lists can't be quoted, and leading and trailing space characters are stripped before the value is used.
Encoding issues. Most of the configuration parameters are plain ASCII. Two particular sets of values may cause encoding issues:
File path parameters may contain non-ascii characters and should use the exact same byte values as found in the file system directory. Usually, this means that the configuration file should use the system default locale encoding.
The
unac_except_trans
parameter should be encoded in UTF-8. If your system locale is not UTF-8, and you need to also specify non-ascii file paths, this poses a difficulty because common text editors cannot handle multiple encodings in a single file. In this relatively unlikely case, you can edit the configuration file as two separate text files with appropriate encodings, and concatenate them to create the complete configuration.