From 2a48efc22b00125ef985e32cca9c528891fceeec Mon Sep 17 00:00:00 2001 From: Jean-Francois Dockes Date: Tue, 1 Dec 2015 14:30:17 +0100 Subject: [PATCH] doc --- src/doc/user/usermanual.xml | 75 ++++++++++++++++++++++++++----------- 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/src/doc/user/usermanual.xml b/src/doc/user/usermanual.xml index c5675a49..af6c920d 100644 --- a/src/doc/user/usermanual.xml +++ b/src/doc/user/usermanual.xml @@ -661,6 +661,18 @@ indexedmimetypes = application/pdf option to recoll and recollindex. + When working with the recoll index + configuration GUI, the configuration directory for which parameters + are modified is the one which was selected by + RECOLL_CONFDIR or the parameter, + and there is no way to switch configurations within the GUI. + + Additional configuration directory (beyond + ~/.recoll) must be created by hand + (mkdir or such), the GUI will not do it. This is + to avoid mistakenly creating additional directories when an + argument is mistyped. + A typical usage scenario for the multiple index feature would be for a system administrator to set up a central index for shared data, that you choose to search or not in addition to @@ -5190,13 +5202,14 @@ except: 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 ways. + 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. - By default, for each index, there are two sets of + For each index, there are at least two sets of configuration files. System-wide configuration files are kept in a directory named like /usr/[local/]share/recoll/examples, @@ -5204,6 +5217,16 @@ except: 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 + 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 @@ -5221,17 +5244,7 @@ except: future: do not use colon characters inside the directory paths. - The default location of the 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 - option parameter to recoll and - recollindex. - - If the .recoll directory does not + If the .recoll directory does not exist when recoll or recollindex are started, it will be created with a set of empty configuration files. @@ -5243,7 +5256,6 @@ except: 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 @@ -5269,6 +5281,9 @@ except: + 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 @@ -5283,15 +5298,31 @@ except: character (~) is expanded to the name of the user's home directory, as a shell would do. - White space is used for separation inside lists. - List elements with embedded spaces can be quoted using - double-quotes. + 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: + + - - 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