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

doc

Browse Source
This commit is contained in:
Jean-Francois Dockes 2019-03-31 16:48:53 +02:00
parent 6b6a3dfa23
commit 7e3acf2d0a
2 changed files with 244 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -92,11 +92,11 @@ alink="#0000FF">
"#RCL.INDEXING.INTRODUCTION.CONFIG">Configurations, "#RCL.INDEXING.INTRODUCTION.CONFIG">Configurations,
multiple indexes</a></span></dt> multiple indexes</a></span></dt>
<dt><span class="sect2">2.1.3. <a href= <dt><span class="sect2">2.1.3. <a href=
"#idm227">Document types</a></span></dt> "#idm229">Document types</a></span></dt>
<dt><span class="sect2">2.1.4. <a href= <dt><span class="sect2">2.1.4. <a href=
"#idm268">Indexing failures</a></span></dt> "#idm270">Indexing failures</a></span></dt>
<dt><span class="sect2">2.1.5. <a href= <dt><span class="sect2">2.1.5. <a href=
"#idm280">Recovery</a></span></dt> "#idm282">Recovery</a></span></dt>
</dl> </dl>
</dd> </dd>
<dt><span class="sect1">2.2. <a href= <dt><span class="sect1">2.2. <a href=
@ -885,9 +885,8 @@ alink="#0000FF">
</div> </div>
</div> </div>
<p><span class="application">Recoll</span> supports <p><span class="application">Recoll</span> supports
defining multiple indexes.</p> defining multiple indexes, each defined by its own
<p>Each index is defined by its own <a class="link" href= <a class="link" href="#RCL.INDEXING.CONFIG" title=
"#RCL.INDEXING.CONFIG" title=
"2.3.&nbsp;Index configuration">configuration "2.3.&nbsp;Index configuration">configuration
directory</a>, in which several configuration files directory</a>, in which several configuration files
describe what should be indexed and how.</p> describe what should be indexed and how.</p>
@ -904,46 +903,66 @@ alink="#0000FF">
changed to process a different area of the file system, changed to process a different area of the file system,
select files in different ways, and many other select files in different ways, and many other
things.</p> things.</p>
<p>In some cases, it may be interesting, for example, to <p>In some cases, it may be useful to create additional
index different areas of the file system into separate configuration directories, for example, to separate
indexes, or use different options. You can do this by personal and shared indexes, or to take advantage of the
creating additional configuration directories.</p> organization of your data to improve search
<p>Examples of usage would be to separate personal and precision.</p>
shared indexes, or to take advantage of the organization <p>A plausible usage scenario for the multiple index
of your data to improve search precision.</p> 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 your personal data. Of course,
there are other possibilities. for example, there are
many cases where you know the subset of files that should
be searched, and where narrowing the search can improve
the results. You can achieve approximately the same
effect with the directory filter in advanced search, but
multiple indexes may have better performance and may be
worth the trouble in some cases.</p>
<p>A more advanced use case would be to use multiple
index to improve indexing performance, by updating
several indexes in parallel (using multiple CPU cores and
disks, or possibly several machines), and then merging
them, or querying them in parallel.</p>
<p>A specific configuration can be selected by setting <p>A specific configuration can be selected by setting
the <code class="envar">RECOLL_CONFDIR</code> environment the <code class="envar">RECOLL_CONFDIR</code> environment
variable, or giving the <code class="option">-c</code> variable, or giving the <code class="option">-c</code>
option to any of the <span class= option to any of the <span class=
"application">Recoll</span> commands.</p> "application">Recoll</span> commands.</p>
<p>When generating indexes, the different configurations <p>When creating or updating indexes, the different
are entirely independant (no parameters are ever shared configurations are entirely independant (no parameters
between configurations when indexing).</p> are ever shared between configurations when indexing).
<p>Multiple indexes can be queryied concurrently, either The <span class=
from the GUI or the command line. When doing this, there "command"><strong>recollindex</strong></span> program
is always a main configuration, from which both always works on a single index.</p>
configuration and index data are used. Only the index <p>When querying, multiple indexes can be accessed
data from the additional indexes is used (their concurrently, either from the GUI or the command line.
configuration parameters are ignored).</p> When doing this, there is always one main configuration,
<p>This is important and sometimes confusing, so it will from which both configuration and index data are used.
be rephrased here: for index generation, multiple Only the index data from the additional indexes is used
configurations are totally independant from each other. (their configuration parameters are ignored).</p>
When querying, configuration and data are used from the <p>The behaviour of index update and query regarding
main index (the one designated by <code class= multiple configurations is important and sometimes
"literal">-c</code> or <code class= confusing, so it will be rephrased here: for index
generation, multiple configurations are totally
independant from each other. When querying, configuration
and data are used from the main index (the one designated
by <code class="literal">-c</code> or <code class=
"envar">RECOLL_CONFDIR</code>), and only the data from "envar">RECOLL_CONFDIR</code>), and only the data from
the additional indexes is used. This also implies that the additional indexes is used. This implies that some
<a class="link" href="#RCL.INDEXING.CONFIG.MULTIPLE" parameters should be consistent among the configurations
title="2.3.1.&nbsp;Multiple indexes">some parameters for indexes which are to be used together.</p>
should be consistent among the configurations</a> for <p>See the section about <a class="link" href=
indexes which are to be used together.</p> "#RCL.INDEXING.CONFIG.MULTIPLE" title=
"2.3.1.&nbsp;Multiple indexes">configuring multiple
indexes</a> for more detail</p>
</div> </div>
<div class="sect2"> <div class="sect2">
<div class="titlepage"> <div class="titlepage">
<div> <div>
<div> <div>
<h3 class="title"><a name="idm227" id= <h3 class="title"><a name="idm229" id=
"idm227"></a>2.1.3.&nbsp;Document types</h3> "idm229"></a>2.1.3.&nbsp;Document types</h3>
</div> </div>
</div> </div>
</div> </div>
@ -1040,8 +1059,8 @@ alink="#0000FF">
<div class="titlepage"> <div class="titlepage">
<div> <div>
<div> <div>
<h3 class="title"><a name="idm268" id= <h3 class="title"><a name="idm270" id=
"idm268"></a>2.1.4.&nbsp;Indexing failures</h3> "idm270"></a>2.1.4.&nbsp;Indexing failures</h3>
</div> </div>
</div> </div>
</div> </div>
@ -1076,8 +1095,8 @@ alink="#0000FF">
<div class="titlepage"> <div class="titlepage">
<div> <div>
<div> <div>
<h3 class="title"><a name="idm280" id= <h3 class="title"><a name="idm282" id=
"idm280"></a>2.1.5.&nbsp;Recovery</h3> "idm282"></a>2.1.5.&nbsp;Recovery</h3>
</div> </div>
</div> </div>
</div> </div>
@ -1368,42 +1387,29 @@ alink="#0000FF">
<span class="command"><strong>recoll</strong></span> and <span class="command"><strong>recoll</strong></span> and
<span class= <span class=
"command"><strong>recollindex</strong></span>.</p> "command"><strong>recollindex</strong></span>.</p>
<p>When working with the <span class= <p>Index configuration parameters can be set either by
using a text editor on the files, or, for most
parameters, by using the <span class=
"command"><strong>recoll</strong></span> index "command"><strong>recoll</strong></span> index
configuration GUI, the configuration directory for which configuration GUI. In the latter case, the configuration
parameters are modified is the one which was selected by directory for which parameters are modified is the one
<code class="envar">RECOLL_CONFDIR</code> or the which was selected by <code class=
<code class="option">-c</code> parameter, and there is no "envar">RECOLL_CONFDIR</code> or the <code class=
way to switch configurations within the GUI.</p> "option">-c</code> parameter, and there is no way to
<p>Additional configuration directories (beyond switch configurations within the GUI.</p>
<code class="filename">~/.recoll</code>) must be created <p>As a remainder from a previous section, a <span class=
by hand (<span class=
"command"><strong>mkdir</strong></span> or such), the GUI
will not do it. This is to avoid mistakenly creating
additional directories when an argument is mistyped.</p>
<p>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 your personal data. Of course,
there are other possibilities. There are many cases where
you know the subset of files that should be searched, and
where narrowing the search can improve the results. You
can achieve approximately the same effect with the
directory filter in advanced search, but multiple indexes
will have better performance and may be worth the
trouble.</p>
<p>A <span class=
"command"><strong>recollindex</strong></span> program "command"><strong>recollindex</strong></span> program
instance can only update one specific index, and it will instance can only update one specific index, and it will
only use parameters from a single configuration (no only use parameters from a single configuration (no
parameters are ever shared between configurations when parameters are ever shared between configurations when
indexing).</p> indexing). All the query methods (<span class=
<p>Multiple indexes can be queryied concurrently, either "command"><strong>recoll</strong></span>, <span class=
from the GUI or the command line. When doing this, there "command"><strong>recollq</strong></span>, the Python
is always a main configuration, from which both API, etc.) operate with a main configuration, from which
configuration and index data are used. Only the index both configuration and index data are used, but can also
data from the additional indexes is used (their query data from multiple additional indexes. Only the
configuration parameters are ignored).</p> index data from the latter is used, their configuration
parameters are ignored.</p>
<p>When searching, the current main index (defined by <p>When searching, the current main index (defined by
<code class="envar">RECOLL_CONFDIR</code> or <code class= <code class="envar">RECOLL_CONFDIR</code> or <code class=
"option">-c</code>) is always active. If this is "option">-c</code>) is always active. If this is
@ -1428,6 +1434,60 @@ alink="#0000FF">
<p>The different search interfaces (GUI, command line, <p>The different search interfaces (GUI, command line,
...) have different methods to define the set of indexes ...) have different methods to define the set of indexes
to be used, see the appropriate section.</p> to be used, see the appropriate section.</p>
<p>At the moment, using multiple configurations implies a
small level of command line usage. Additional
configuration directories (beyond <code class=
"filename">~/.recoll</code>) must be created by hand
(<span class="command"><strong>mkdir</strong></span> or
such), the GUI will not do it. This is to avoid
mistakenly creating additional directories when an
argument is mistyped. Also, the GUI or the indexer must
be launched with a specific option or environment to work
on the right configuration.</p>
<p>To be more practical, here follows a few examples of
the commands need to create, configure, update, and query
an additional index.</p>
<p>Initially creating the configuration and index:</p>
<pre class="programlisting">
mkdir <em class=
"replaceable"><code>/path/to/my/new/config</code></em></pre>
<p>Configuring the new index can be done from the
<span class="command"><strong>recoll</strong></span> GUI,
launched from the command line to pass the <code class=
"literal">-c</code> option (you could create a desktop
file to do it for you), and then using the GUI index
configuration tool to set up the index.</p>
<pre class="programlisting">
recoll -c <em class=
"replaceable"><code>/path/to/my/new/config</code></em></pre>
<p>Alternatively, you can just start a text editor on the
main configuration file <a class="link" href=
"#RCL.INSTALL.CONFIG.RECOLLCONF" title=
"6.4.2.&nbsp;Recoll main configuration file, recoll.conf">
<code class="filename">recoll.conf</code></a> .</p>
<p>Creating and updating the index can be done from the
command line:</p>
<pre class="programlisting">recollindex -c <em class=
"replaceable"><code>/path/to/my/new/config</code></em>
</pre>
<p>or from the File menu of a GUI launched with the same
option (<span class=
"command"><strong>recoll</strong></span>, see above).</p>
<p>The same GUI would also let you set up batch indexing
for the new index. Real time indexing can only be set up
from the GUI for the default index (the menu entry will
be inactive if the GUI was started with a non-default
<code class="literal">-c</code> option).</p>
<p>The new index can be queried alone with</p>
<pre class="programlisting">
recoll -c <em class=
"replaceable"><code>/path/to/my/new/config</code></em></pre>
<p>Or, in parallel with the default index, by starting
<span class="command"><strong>recoll</strong></span>
without a <code class="literal">-c</code> option, and
using the <span class="guimenu">Preferences</span> →
<span class="guimenuitem">External Index Dialog</span>
menu.</p>
</div> </div>
<div class="sect2"> <div class="sect2">
<div class="titlepage"> <div class="titlepage">

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

@ -395,12 +395,10 @@
<sect2 id="RCL.INDEXING.INTRODUCTION.CONFIG"> <sect2 id="RCL.INDEXING.INTRODUCTION.CONFIG">
<title>Configurations, multiple indexes</title> <title>Configurations, multiple indexes</title>
<para>&RCL; supports defining multiple indexes.</para> <para>&RCL; supports defining multiple indexes, each defined by its
own <link linkend="RCL.INDEXING.CONFIG">configuration
<para>Each index is defined by its own <link directory</link>, in which several configuration files describe
linkend="RCL.INDEXING.CONFIG">configuration directory</link>, in what should be indexed and how.</para>
which several configuration files describe what should be indexed
and how.</para>
<para>A default personal configuration directory <para>A default personal configuration directory
(<filename>$HOME/.recoll/</filename>) is created (<filename>$HOME/.recoll/</filename>) is created
@ -415,38 +413,58 @@
different area of the file system, select files in different ways, different area of the file system, select files in different ways,
and many other things.</para> and many other things.</para>
<para>In some cases, it may be interesting, for example, to index <para>In some cases, it may be useful to create additional
different areas of the file system into separate indexes, or use configuration directories, for example, to separate personal and
different options. You can do this by creating additional shared indexes, or to take advantage of the organization of your
configuration directories.</para> data to improve search precision.</para>
<para>Examples of usage would be to separate personal and shared <para>A plausible usage scenario for the multiple index feature
indexes, or to take advantage of the organization of your data would be for a system administrator to set up a central index for
to improve search precision.</para> shared data, that you choose to search or not in addition to your
personal data. Of course, there are other possibilities. for
example, there are many cases where you know the subset of files
that should be searched, and where narrowing the search can improve
the results. You can achieve approximately the same effect with the
directory filter in advanced search, but multiple indexes may have
better performance and may be worth the trouble in some
cases.</para>
<para>A more advanced use case would be to use multiple index to
improve indexing performance, by updating several indexes in
parallel (using multiple CPU cores and disks, or possibly several
machines), and then merging them, or querying them in
parallel.</para>
<para>A specific configuration can be selected by setting the <para>A specific configuration can be selected by setting the
<envar>RECOLL_CONFDIR</envar> environment variable, or giving the <envar>RECOLL_CONFDIR</envar> environment variable, or giving the
<option>-c</option> option to any of the &RCL; commands.</para> <option>-c</option> option to any of the &RCL; commands.</para>
<para>When generating indexes, the different configurations are <para>When creating or updating indexes, the different
entirely independant (no parameters are ever shared between configurations are entirely independant (no parameters are ever
configurations when indexing).</para> shared between configurations when indexing). The
<command>recollindex</command> program always works on a single
index.</para>
<para>Multiple indexes can be queryied concurrently, either from <para>When querying, multiple indexes can be accessed concurrently,
the GUI or the command line. When doing this, there is always a either from the GUI or the command line. When doing this, there is
main configuration, from which both configuration and index data always one main configuration, from which both configuration and
are used. Only the index data from the additional indexes is used index data are used. Only the index data from the additional
(their configuration parameters are ignored).</para> indexes is used (their configuration parameters are
ignored).</para>
<para>This is important and sometimes confusing, so it will be <para>The behaviour of index update and query regarding multiple
configurations is important and sometimes confusing, so it will be
rephrased here: for index generation, multiple configurations are rephrased here: for index generation, multiple configurations are
totally independant from each other. When querying, configuration totally independant from each other. When querying, configuration
and data are used from the main index (the one designated by and data are used from the main index (the one designated by
<literal>-c</literal> or <envar>RECOLL_CONFDIR</envar>), and only <literal>-c</literal> or <envar>RECOLL_CONFDIR</envar>), and only
the data from the additional indexes is used. This also implies the data from the additional indexes is used. This implies
that <link linkend="RCL.INDEXING.CONFIG.MULTIPLE">some parameters that some parameters should be consistent among the configurations
should be consistent among the configurations</link> for indexes for indexes which are to be used together.</para>
which are to be used together.</para>
<para>See the section about <link
linkend="RCL.INDEXING.CONFIG.MULTIPLE">configuring multiple
indexes</link> for more detail</para>
</sect2> </sect2>
@ -784,38 +802,24 @@
<option>-c</option> option to <command>recoll</command> and <option>-c</option> option to <command>recoll</command> and
<command>recollindex</command>.</para> <command>recollindex</command>.</para>
<para>When working with the <command>recoll</command> index <para>Index configuration parameters can be set either by using a
configuration GUI, the configuration directory for which parameters text editor on the files, or, for most parameters, by using the
are modified is the one which was selected by <command>recoll</command> index configuration GUI. In the latter
<envar>RECOLL_CONFDIR</envar> or the <option>-c</option> parameter, case, the configuration directory for which parameters are modified
and there is no way to switch configurations within the GUI.</para> is the one which was selected by <envar>RECOLL_CONFDIR</envar> or
the <option>-c</option> parameter, and there is no way to switch
configurations within the GUI.</para>
<para>Additional configuration directories (beyond <para>As a remainder from a previous section, a
<filename>~/.recoll</filename>) must be created by hand <command>recollindex</command> program instance can only update one
(<command>mkdir</command> or such), the GUI will not do it. This is specific index, and it will only use parameters from a single
to avoid mistakenly creating additional directories when an configuration (no parameters are ever shared between configurations
argument is mistyped.</para> when indexing). All the query methods (<command>recoll</command>,
<command>recollq</command>, the Python API, etc.) operate with a
<para>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 your personal
data. Of course, there are other possibilities. There are many
cases where you know the subset of files that should be searched,
and where narrowing the search can improve the results. You can
achieve approximately the same effect with the directory filter in
advanced search, but multiple indexes will have better performance
and may be worth the trouble.</para>
<para>A <command>recollindex</command> program instance can only
update one specific index, and it will only use parameters from a
single configuration (no parameters are ever shared between
configurations when indexing).</para>
<para>Multiple indexes can be queryied concurrently, either from
the GUI or the command line. When doing this, there is always a
main configuration, from which both configuration and index data main configuration, from which both configuration and index data
are used. Only the index data from the additional indexes is used are used, but can also query data from multiple additional
(their configuration parameters are ignored).</para> indexes. Only the index data from the latter is used, their
configuration parameters are ignored.</para>
<para>When searching, the current main index (defined by <para>When searching, the current main index (defined by
<envar>RECOLL_CONFDIR</envar> or <option>-c</option>) is always <envar>RECOLL_CONFDIR</envar> or <option>-c</option>) is always
@ -841,6 +845,60 @@
have different methods to define the set of indexes to be have different methods to define the set of indexes to be
used, see the appropriate section.</para> used, see the appropriate section.</para>
<para>At the moment, using multiple configurations implies a small
level of command line usage. Additional configuration directories
(beyond <filename>~/.recoll</filename>) must be created by hand
(<command>mkdir</command> or such), the GUI will not do it. This is
to avoid mistakenly creating additional directories when an
argument is mistyped. Also, the GUI or the indexer must be launched
with a specific option or environment to work on the right
configuration.</para>
<para>To be more practical, here follows a few examples of the
commands need to create, configure, update, and query an additional
index.</para>
<para>Initially creating the configuration and index:<programlisting>
mkdir <replaceable>/path/to/my/new/config</replaceable></programlisting></para>
<para>Configuring the new index can be done from the
<command>recoll</command> GUI, launched from the
command line to pass the <literal>-c</literal> option
(you could create a desktop file to do it for you), and then using the
GUI index configuration tool to set up the index.
<programlisting>
recoll -c <replaceable>/path/to/my/new/config</replaceable></programlisting>
</para>
<para>Alternatively, you can just start a text editor on the main
configuration file <link
linkend="RCL.INSTALL.CONFIG.RECOLLCONF"><filename>recoll.conf
</filename></link>.</para>
<para>Creating and updating the index can be done from the command line:
<programlisting>recollindex -c <replaceable>/path/to/my/new/config</replaceable>
</programlisting>
or from the File menu of a GUI launched with the same option
(<command>recoll</command>, see above).</para>
<para>The same GUI would also let you set up batch indexing for
the new index. Real time indexing can only be set up from the GUI
for the default index (the menu entry will be inactive if the GUI
was started with a non-default <literal>-c</literal>
option).</para>
<para>The new index can be queried alone with<programlisting>
recoll -c <replaceable>/path/to/my/new/config</replaceable></programlisting>
Or, in parallel with the default index, by starting
<command>recoll</command> without a <literal>-c</literal> option,
and using the
<menuchoice>
<guimenu>Preferences</guimenu>
<guimenuitem>External Index Dialog</guimenuitem>
</menuchoice> menu.</para>
</sect2> </sect2>