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.
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 (the values in these files are often commented out, and just present to indicate the
default coded in the program). For each index, a parallel set of files defines the customized
parameters.
On Unix-like systems, the default location of the customized configuration is
the .recoll directory in your home. On Windows it
is C:/Users/[you]/AppData/Local/Recoll. Most people will only use this
directory.
The default location for the configuration directory can be changed, or others can be
added for separate indexes 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 default configuration 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.
Important
Quotes processing is ONLY applied to parameter values which are lists. Double quoting
a single value like, e.g. dbdir will result in an incorrect value, with
quotes included. This is quite confusing, and may have been a design mistake but it is
much too late to fix.
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_transparameter 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.
