tris/recoll
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add notices about quotes processing not being applied to single value parameters

Browse Source
This commit is contained in:
Jean-Francois Dockes 2022-08-26 15:23:18 +02:00
parent 35753d17d0
commit 8deed63be6
3 changed files with 81 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
src/doc/user/usermanual.html
View File

@ -8752,20 +8752,24 @@ hasextract = False
The GUI tool will try to respect your formatting and The GUI tool will try to respect your formatting and
comments as much as possible, so it is quite possible to comments as much as possible, so it is quite possible to
use both approaches on the same configuration.</p> use both approaches on the same configuration.</p>
<p>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.</p>
<p>For each index, there are at least two sets of <p>For each index, there are at least two sets of
configuration files. System-wide configuration files are configuration files. System-wide configuration files are
kept in a directory named like <code class= kept in a directory named like <code class=
"filename">/usr/share/recoll/examples</code>, and define "filename">/usr/share/recoll/examples</code>, 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 parallel set of files defines the customized
parameters.</p> parameters.</p>
<p>The default location of the customized configuration is <p>On <span class="application">Unix</span>-like systems,
the <code class="filename">.recoll</code> directory in your the default location of the customized configuration is the
home. Most people will only use this directory.</p> <code class="filename">.recoll</code> directory in your
<p>This location can be changed, or others can be added home. On <span class="application">Windows</span> it is
<code class=
"filename">C:/Users/[you]/AppData/Local/Recoll</code>. Most
people will only use this directory.</p>
<p>The default location for the configuration directory can
be changed, or others can be added for separate indexes
with the <code class="envar">RECOLL_CONFDIR</code> with the <code class="envar">RECOLL_CONFDIR</code>
environment variable or the <code class="option">-c</code> environment variable or the <code class="option">-c</code>
option parameter to <span class= option parameter to <span class=
@ -8789,9 +8793,9 @@ hasextract = False
probably be interpreted as colon-separated lists in the probably be interpreted as colon-separated lists in the
future: do not use colon characters inside the directory future: do not use colon characters inside the directory
paths.</p> paths.</p>
<p>If the <code class="filename">.recoll</code> directory <p>If the default configuration directory does not exist
does not exist when <span class= when <span class="command"><strong>recoll</strong></span>
"command"><strong>recoll</strong></span> or <span class= or <span class=
"command"><strong>recollindex</strong></span> are started, "command"><strong>recollindex</strong></span> are started,
it will be created with a set of empty configuration files. it will be created with a set of empty configuration files.
<span class="command"><strong>recoll</strong></span> will <span class="command"><strong>recoll</strong></span> will
@ -8870,6 +8874,16 @@ hasextract = False
<p>Parameters which are not part of string lists can't be <p>Parameters which are not part of string lists can't be
quoted, and leading and trailing space characters are quoted, and leading and trailing space characters are
stripped before the value is used.</p> stripped before the value is used.</p>
<div class="important" style=
"margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Important</h3>
<p>Quotes processing is ONLY applied to parameter values
which are lists. Double quoting a single value like, e.g.
<code class="literal">dbdir</code> 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.</p>
</div>
<p><b>Encoding issues.&nbsp;</b>Most of the configuration <p><b>Encoding issues.&nbsp;</b>Most of the configuration
parameters are plain ASCII. Two particular sets of values parameters are plain ASCII. Two particular sets of values
may cause encoding issues:</p> may cause encoding issues:</p>

120
src/doc/user/usermanual.xml
View File

@ -6556,61 +6556,44 @@ hasextract = False
so it is quite possible to use both approaches on the same so it is quite possible to use both approaches on the same
configuration.</para> configuration.</para>
<para>The most accurate documentation for the <para>For each index, there are at least two sets of configuration files. System-wide
configuration parameters is given by comments inside the default configuration files are kept in a directory named
files, and we will just give a general overview here.</para> like <filename>/usr/share/recoll/examples</filename>, and define default values, shared by all
indexes (the values in these files are often commented out, and just present to indicate the
<para>For each index, there are at least two sets of default coded in the program). For each index, a parallel set of files defines the customized
configuration files. System-wide configuration files are kept
in a directory named
like <filename>/usr/share/recoll/examples</filename>,
and define default values, shared by all indexes. For each
index, a parallel set of files defines the customized
parameters.</para> parameters.</para>
<para>The default location of the customized configuration is the <para>On &LIN;, the default location of the customized configuration is
<filename>.recoll</filename> the <filename>.recoll</filename> directory in your home. On &WIN; it
directory in your home. Most people will only use this is <filename>C:/Users/[you]/AppData/Local/Recoll</filename>. Most people will only use this
directory.</para> directory.</para>
<para>This location can be changed, or others can be added with the <para>The default location for the configuration directory can be changed, or others can be
<envar>RECOLL_CONFDIR</envar> environment variable or the added for separate indexes with the <envar>RECOLL_CONFDIR</envar> environment variable or
<option>-c</option> option parameter to <command>recoll</command> and the <option>-c</option> option parameter to <command>recoll</command>
<command>recollindex</command>.</para> and <command>recollindex</command>.</para>
<para>In addition (as of &RCL; version 1.19.7), it is possible <para>In addition (as of &RCL; version 1.19.7), it is possible to specify two additional
to specify two additional configuration directories which will configuration directories which will be stacked before and after the user configuration
be stacked before and after the user configuration directory. These are defined by the <envar>RECOLL_CONFTOP</envar>
directory. These are defined by and <envar>RECOLL_CONFMID</envar> environment variables. Values from configuration files
the <envar>RECOLL_CONFTOP</envar> inside the top directory will override user ones, values from configuration files inside the
and <envar>RECOLL_CONFMID</envar> environment middle directory will override system ones and be overridden by user ones. These two variables
variables. Values from configuration files inside the top may be of use to applications which augment &RCL; functionality, and need to add configuration
directory will override user ones, values from configuration data without disturbing the user's files. Please note that the two, currently single, values
files inside the middle directory will override system ones will probably be interpreted as colon-separated lists in the future: do not use colon
and be overridden by user ones. These two variables may be of characters inside the directory paths.</para>
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.</para>
<para>If the <filename>.recoll</filename> directory does not <para>If the default configuration directory does not exist when <command>recoll</command>
exist when <command>recoll</command> or or <command>recollindex</command> are started, it will be created with a set of empty
<command>recollindex</command> are started, it will be created configuration files. <command>recoll</command> will give you a chance to edit the
with a set of empty configuration files. configuration file before starting indexing. <command>recollindex</command> will proceed
<command>recoll</command> will give you a chance to edit the immediately. To avoid mistakes, the automatic directory creation will only occur for the
configuration file before starting default location, not if <option>-c</option> or <envar>RECOLL_CONFDIR</envar> were used (in
indexing. <command>recollindex</command> will proceed the latter cases, you will have to create the directory).</para>
immediately. To avoid mistakes, the automatic directory
creation will only occur for the
default location, not if <option>-c</option> or
<envar>RECOLL_CONFDIR</envar> were used (in the latter
cases, you will have to create the directory).</para>
<para>All configuration files share the same format. For <para>All configuration files share the same format. For example, a short extract of the main
example, a short extract of the main configuration file might configuration file might look as follows:</para>
look as follows:</para>
<programlisting> <programlisting>
# Space-separated list of files and directories to index. # Space-separated list of files and directories to index.
topdirs = ~/docs /usr/share/doc topdirs = ~/docs /usr/share/doc
@ -6633,17 +6616,14 @@ hasextract = False
</itemizedlist> </itemizedlist>
<para>Long lines can be broken by ending each incomplete part with <para>Long lines can be broken by ending each incomplete part with
a backslash (<literal>\</literal>).</para> a backslash (<literal>\</literal>).</para>
<para>Depending on the type of configuration file, section <para>Depending on the type of configuration file, section definitions either separate groups
definitions either separate groups of parameters or allow of parameters or allow redefining some parameters for a directory sub-tree. They stay in
redefining some parameters for a directory sub-tree. They stay effect until another section definition, or the end of file, is encountered. Some of the
in effect until another section definition, or the end of parameters used for indexing are looked up hierarchically from the current directory location
file, is encountered. Some of the parameters used for indexing upwards. Not all parameters can be meaningfully redefined, this is specified for each in the
are looked up hierarchically from the current directory next section. </para>
location upwards. Not all parameters can be meaningfully
redefined, this is specified for each in the next
section. </para>
<important> <important>
<para>Global parameters <emphasis>must not</emphasis> be defined in <para>Global parameters <emphasis>must not</emphasis> be defined in
@ -6652,14 +6632,12 @@ hasextract = False
(e.g. <literal>skippedPaths</literal>).</para> (e.g. <literal>skippedPaths</literal>).</para>
</important> </important>
<para>When found at the beginning of a file path, the tilde <para>When found at the beginning of a file path, the tilde character (~) is expanded to the
character (~) is expanded to the name of the user's home name of the user's home directory, as a shell would do.</para>
directory, as a shell would do.</para>
<para>Some parameters are lists of strings. White space is used for <para>Some parameters are lists of strings. White space is used for separation. List elements
separation. List elements with embedded spaces can be quoted using with embedded spaces can be quoted using double-quotes. Double quotes inside these elements
double-quotes. Double quotes inside these elements can be escaped can be escaped with a backslash.</para>
with a backslash.</para>
<para>No value inside a configuration file can contain a newline <para>No value inside a configuration file can contain a newline
character. Long lines can be continued by escaping the character. Long lines can be continued by escaping the
@ -6671,8 +6649,14 @@ hasextract = False
</programlisting> </programlisting>
<para>Parameters which are not part of string lists can't be <para>Parameters which are not part of string lists can't be
quoted, and leading and trailing space characters are quoted, and leading and trailing space characters are
stripped before the value is used.</para> stripped before the value is used.</para>
<important>
<para>Quotes processing is ONLY applied to parameter values which are lists. Double quoting
a single value like, e.g. <literal>dbdir</literal> 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.</para></important>
<formalpara> <formalpara>
<title>Encoding issues</title> <title>Encoding issues</title>

4
src/sampleconf/recoll.conf
View File

@ -10,6 +10,10 @@
# #
# Most of the important values in this file can be set from the GUI # 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. # 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.
# <grouptitle id="WHATDOCS">Parameters affecting what documents we # <grouptitle id="WHATDOCS">Parameters affecting what documents we
# index</grouptitle> # index</grouptitle>