From 8deed63be6f707c7447af780366e7613b0a80d3d Mon Sep 17 00:00:00 2001 From: Jean-Francois Dockes Date: Fri, 26 Aug 2022 15:23:18 +0200 Subject: [PATCH] Add notices about quotes processing not being applied to single value parameters --- src/doc/user/usermanual.html | 36 +++++++---- src/doc/user/usermanual.xml | 120 +++++++++++++++-------------------- src/sampleconf/recoll.conf | 4 ++ 3 files changed, 81 insertions(+), 79 deletions(-) diff --git a/src/doc/user/usermanual.html b/src/doc/user/usermanual.html index c1923479..3a54fe3b 100644 --- a/src/doc/user/usermanual.html +++ b/src/doc/user/usermanual.html @@ -8752,20 +8752,24 @@ hasextract = False 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 + 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.

-

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 +

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 -

If the .recoll directory - does not exist when recoll or 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 @@ -8870,6 +8874,16 @@ hasextract = False

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:

diff --git a/src/doc/user/usermanual.xml b/src/doc/user/usermanual.xml index 27b0fe4c..2c5561b6 100644 --- a/src/doc/user/usermanual.xml +++ b/src/doc/user/usermanual.xml @@ -6556,61 +6556,44 @@ hasextract = False 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 + 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. - The default location of the customized configuration is the - .recoll - directory in your home. Most people will only use this - directory. + On &LIN;, the default location of the customized configuration is + the .recoll directory in your home. On &WIN; it + is C:/Users/[you]/AppData/Local/Recoll. 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 - option parameter to recoll and - recollindex. + 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 option parameter to recoll + and recollindex. - In addition (as of &RCL; 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 &RCL; 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. + In addition (as of &RCL; 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 &RCL; 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 or - RECOLL_CONFDIR were used (in the latter - cases, you will have to create the directory). + 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 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: + 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 @@ -6633,17 +6616,14 @@ hasextract = False Long lines can be broken by ending each incomplete part with - a backslash (\). + 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. + 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. Global parameters must not be defined in @@ -6652,14 +6632,12 @@ hasextract = False (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. + 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. + 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 @@ -6671,8 +6649,14 @@ hasextract = False 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. + quoted, and leading and trailing space characters are + stripped before the value is used. + + + 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 diff --git a/src/sampleconf/recoll.conf b/src/sampleconf/recoll.conf index c094ce31..b921b5c5 100644 --- a/src/sampleconf/recoll.conf +++ b/src/sampleconf/recoll.conf @@ -10,6 +10,10 @@ # # Most of the important values in this file can be set from the GUI # configuration menus, which may be an easier approach than direct editing. +# +# Note about quoting: values which are parts of list parameters and contain white space can be +# quoted with "double quotes". Double quotes processing is NOT applied to single value parameter, +# and using quotes there will result in bad values. # Parameters affecting what documents we # index