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
comments as much as possible, so it is quite possible to
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
configuration files. System-wide configuration files are
kept in a directory named like <code class=
"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
parameters.</p>
<p>The default location of the customized configuration is
the <code class="filename">.recoll</code> directory in your
home. Most people will only use this directory.</p>
<p>This location can be changed, or others can be added
<p>On <span class="application">Unix</span>-like systems,
the default location of the customized configuration is the
<code class="filename">.recoll</code> directory in your
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>
environment variable or the <code class="option">-c</code>
option parameter to <span class=
@ -8789,9 +8793,9 @@ hasextract = False
probably be interpreted as colon-separated lists in the
future: do not use colon characters inside the directory
paths.</p>
<p>If the <code class="filename">.recoll</code> directory
does not exist when <span class=
"command"><strong>recoll</strong></span> or <span class=
<p>If the default configuration directory does not exist
when <span class="command"><strong>recoll</strong></span>
or <span class=
"command"><strong>recollindex</strong></span> are started,
it will be created with a set of empty configuration files.
<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
quoted, and leading and trailing space characters are
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
parameters are plain ASCII. Two particular sets of values
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
configuration.</para>
<para>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.</para>
<para>For each index, there are at least two sets of
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
<para>For each index, there are at least two sets of 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 (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.</para>
<para>The default location of the customized configuration is the
<filename>.recoll</filename>
directory in your home. Most people will only use this
directory.</para>
<para>On &LIN;, the default location of the customized configuration is
the <filename>.recoll</filename> directory in your home. On &WIN; it
is <filename>C:/Users/[you]/AppData/Local/Recoll</filename>. Most people will only use this
directory.</para>
<para>This location can be changed, or others can be added with the
<envar>RECOLL_CONFDIR</envar> environment variable or the
<option>-c</option> option parameter to <command>recoll</command> and
<command>recollindex</command>.</para>
<para>The default location for the configuration directory can be changed, or others can be
added for separate indexes with the <envar>RECOLL_CONFDIR</envar> environment variable or
the <option>-c</option> option parameter to <command>recoll</command>
and <command>recollindex</command>.</para>
<para>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 <envar>RECOLL_CONFTOP</envar>
and <envar>RECOLL_CONFMID</envar> 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.</para>
<para>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 <envar>RECOLL_CONFTOP</envar>
and <envar>RECOLL_CONFMID</envar> 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.</para>
<para>If the <filename>.recoll</filename> directory does not
exist when <command>recoll</command> or
<command>recollindex</command> are started, it will be created
with a set of empty configuration files.
<command>recoll</command> will give you a chance to edit the
configuration file before starting
indexing. <command>recollindex</command> will proceed
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>If the default configuration directory does not exist when <command>recoll</command>
or <command>recollindex</command> are started, it will be created with a set of empty
configuration files. <command>recoll</command> will give you a chance to edit the
configuration file before starting indexing. <command>recollindex</command> will proceed
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
example, a short extract of the main configuration file might
look as follows:</para>
<para>All configuration files share the same format. For example, a short extract of the main
configuration file might look as follows:</para>
<programlisting>
# Space-separated list of files and directories to index.
topdirs = ~/docs /usr/share/doc
@ -6633,17 +6616,14 @@ hasextract = False
</itemizedlist>
<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
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. </para>
<para>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. </para>
<important>
<para>Global parameters <emphasis>must not</emphasis> be defined in
@ -6652,14 +6632,12 @@ hasextract = False
(e.g. <literal>skippedPaths</literal>).</para>
</important>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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
</programlisting>
<para>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.</para>
quoted, and leading and trailing space characters are
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>
<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
# 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
# index</grouptitle>