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 2021-07-09 09:25:24 +02:00
parent e6055681d4
commit 03c1e4ce8a
2 changed files with 615 additions and 556 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -257,20 +257,25 @@ alink="#0000FF">
<dd> <dd>
<dl> <dl>
<dt><span class="sect2">3.5.1. <a href= <dt><span class="sect2">3.5.1. <a href=
"#RCL.SEARCH.LANG.SYNTAX">General
syntax</a></span></dt>
<dt><span class="sect2">3.5.2. <a href=
"#RCL.SEARCH.LANG.SPECIALFIELDS">Special field-like
specifiers</a></span></dt>
<dt><span class="sect2">3.5.3. <a href=
"#RCL.SEARCH.LANG.RANGES">Range "#RCL.SEARCH.LANG.RANGES">Range
clauses</a></span></dt> clauses</a></span></dt>
<dt><span class="sect2">3.5.2. <a href= <dt><span class="sect2">3.5.4. <a href=
"#RCL.SEARCH.LANG.MODIFIERS">Modifiers</a></span></dt> "#RCL.SEARCH.LANG.MODIFIERS">Modifiers</a></span></dt>
</dl> </dl>
</dd> </dd>
<dt><span class="sect1">3.6. <a href= <dt><span class="sect1">3.6. <a href=
"#RCL.SEARCH.ANCHORWILD">Anchored searches and "#RCL.SEARCH.ANCHORWILD">Wildcards and anchored
wildcards</a></span></dt> searches</a></span></dt>
<dd> <dd>
<dl> <dl>
<dt><span class="sect2">3.6.1. <a href= <dt><span class="sect2">3.6.1. <a href=
"#RCL.SEARCH.WILDCARDS">More about "#RCL.SEARCH.WILDCARDS">Wildcards</a></span></dt>
wildcards</a></span></dt>
<dt><span class="sect2">3.6.2. <a href= <dt><span class="sect2">3.6.2. <a href=
"#RCL.SEARCH.ANCHOR">Anchored "#RCL.SEARCH.ANCHOR">Anchored
searches</a></span></dt> searches</a></span></dt>
@ -423,7 +428,7 @@ alink="#0000FF">
<div class="list-of-tables"> <div class="list-of-tables">
<p><b>List of Tables</b></p> <p><b>List of Tables</b></p>
<dl> <dl>
<dt>3.1. <a href="#idm1471">Keyboard shortcuts</a></dt> <dt>3.1. <a href="#idm1472">Keyboard shortcuts</a></dt>
</dl> </dl>
</div> </div>
<div class="chapter"> <div class="chapter">
@ -2133,22 +2138,23 @@ metadatacmds = ; <em class=
language, through any of its aliases: <em class= language, through any of its aliases: <em class=
"replaceable"><code>tags:some/alternate/values</code></em> "replaceable"><code>tags:some/alternate/values</code></em>
or <em class= or <em class=
"replaceable"><code>tags:all,these,values</code></em> (the "replaceable"><code>tags:all,these,values</code></em>. The
compact field search syntax is supported for recoll 1.20 compact comma- or slash-based field search syntax is
and later. For older versions, you would need to repeat the supported for recoll 1.20 and later. For older versions,
<em class="replaceable"><code>tags:</code></em> specifier you would need to repeat the <em class=
for each term, e.g. <em class= "replaceable"><code>tags:</code></em> specifier for each
term, e.g. <em class=
"replaceable"><code>tags:some</code></em> <code class= "replaceable"><code>tags:some</code></em> <code class=
"literal">OR</code> <em class= "literal">OR</code> <em class=
"replaceable"><code>tags:alternate</code></em>).</p> "replaceable"><code>tags:alternate</code></em>.</p>
<p>Tags changes will not be detected by the indexer if the <p>Tags changes will not be detected by the indexer if the
file itself did not change. One possible workaround would file itself did not change. One possible workaround would
be to update the file <code class="literal">ctime</code> be to update the file <code class="literal">ctime</code>
when you modify the tags, which would be consistent with when you modify the tags, which would be consistent with
how extended attributes function. A pair of <span class= how extended attributes function. A pair of <span class=
"command"><strong>chmod</strong></span> commands could "command"><strong>chmod</strong></span> commands could
accomplish this, or a <code class="literal">touch -a</code> accomplish this, or a <code class="literal">touch
. Alternatively, just couple the tag update with a -a</code>. Alternatively, just couple the tag update with a
<code class="literal">recollindex -e -i</code> <em class= <code class="literal">recollindex -e -i</code> <em class=
"replaceable"><code>/path/to/the/file</code></em>.</p> "replaceable"><code>/path/to/the/file</code></em>.</p>
</div> </div>
@ -2771,11 +2777,16 @@ fs.inotify.max_user_watches=32768
documents containing all your input terms.</p> documents containing all your input terms.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">Query Language</code> mode <p>The <code class="literal">Query Language</code>
behaves like <code class="literal">All Terms</code> mode behaves like <code class="literal">All
in the absence of special input, but it can also do Terms</code> in the absence of special input, but it
much more. This is the best mode for getting the most can also do much more. This is the best mode for
of <span class="application">Recoll</span>.</p> getting the most of <span class=
"application">Recoll</span>. It is usable from all
possible interfaces (GUI, command line, WEB UI, ...),
and is <a class="link" href="#RCL.SEARCH.LANG" title=
"3.5.&nbsp;The query language">described
here</a>.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p>In <code class="literal">Any Term</code> mode, <p>In <code class="literal">Any Term</code> mode,
@ -2906,8 +2917,8 @@ fs.inotify.max_user_watches=32768
<code class="literal">?</code>, <code class= <code class="literal">?</code>, <code class=
"literal">[]</code>). See the <a class="link" href= "literal">[]</code>). See the <a class="link" href=
"#RCL.SEARCH.WILDCARDS" title= "#RCL.SEARCH.WILDCARDS" title=
"3.6.1.&nbsp;More about wildcards">section about "3.6.1.&nbsp;Wildcards">section about wildcards</a> for
wildcards</a> for more details.</p> more details.</p>
<p>In all modes except <span class="guilabel">File <p>In all modes except <span class="guilabel">File
name</span>, you can search for exact phrases (adjacent name</span>, you can search for exact phrases (adjacent
words in a given order) by enclosing the input inside words in a given order) by enclosing the input inside
@ -2964,9 +2975,9 @@ fs.inotify.max_user_watches=32768
complex searches.</p> complex searches.</p>
<p>The <span class="guilabel">File name</span> search <p>The <span class="guilabel">File name</span> search
mode will specifically look for file names. The point of mode will specifically look for file names. The point of
having a separate file name search is that wild card having a separate file name search is that wildcard
expansion can be performed more efficiently on a small expansion can be performed more efficiently on a small
subset of the index (allowing wild cards on the left of subset of the index (allowing wildcards on the left of
terms without excessive cost). Things to know:</p> terms without excessive cost). Things to know:</p>
<div class="itemizedlist"> <div class="itemizedlist">
<ul class="itemizedlist" style= <ul class="itemizedlist" style=
@ -2981,7 +2992,7 @@ fs.inotify.max_user_watches=32768
accents, independently of the type of index.</p> accents, independently of the type of index.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p>An entry without any wild card character and not <p>An entry without any wildcard character and not
capitalized will be prepended and appended with '*' capitalized will be prepended and appended with '*'
(ie: <em class="replaceable"><code>etc</code></em> (ie: <em class="replaceable"><code>etc</code></em>
-&gt; <em class= -&gt; <em class=
@ -3841,7 +3852,7 @@ fs.inotify.max_user_watches=32768
<em class="replaceable"><code>xapi</code></em>. <em class="replaceable"><code>xapi</code></em>.
(More about wildcards <a class="link" href= (More about wildcards <a class="link" href=
"#RCL.SEARCH.WILDCARDS" title= "#RCL.SEARCH.WILDCARDS" title=
"3.6.1.&nbsp;More about wildcards">here</a> ).</p> "3.6.1.&nbsp;Wildcards">here</a> ).</p>
</dd> </dd>
<dt><span class="term">Regular expression</span></dt> <dt><span class="term">Regular expression</span></dt>
<dd> <dd>
@ -4064,7 +4075,7 @@ fs.inotify.max_user_watches=32768
given context (e.g. within a preview window, within the given context (e.g. within a preview window, within the
result table).</p> result table).</p>
<div class="table"> <div class="table">
<a name="idm1471" id="idm1471"></a> <a name="idm1472" id="idm1472"></a>
<p class="title"><b>Table&nbsp;3.1.&nbsp;Keyboard <p class="title"><b>Table&nbsp;3.1.&nbsp;Keyboard
shortcuts</b></p> shortcuts</b></p>
<div class="table-contents"> <div class="table-contents">
@ -4291,8 +4302,7 @@ fs.inotify.max_user_watches=32768
<p><b>Wildcards.&nbsp;</b>Wildcards can be used inside <p><b>Wildcards.&nbsp;</b>Wildcards can be used inside
search terms in all forms of searches. <a class="link" search terms in all forms of searches. <a class="link"
href="#RCL.SEARCH.WILDCARDS" title= href="#RCL.SEARCH.WILDCARDS" title=
"3.6.1.&nbsp;More about wildcards">More about "3.6.1.&nbsp;Wildcards">More about wildcards</a>.</p>
wildcards</a>.</p>
<p><b>Automatic suffixes.&nbsp;</b>Words like <p><b>Automatic suffixes.&nbsp;</b>Words like
<code class="literal">odt</code> or <code class= <code class="literal">odt</code> or <code class=
"literal">ods</code> can be automatically turned into "literal">ods</code> can be automatically turned into
@ -4361,7 +4371,7 @@ fs.inotify.max_user_watches=32768
Example: "user manual"p would also match "manual user". Example: "user manual"p would also match "manual user".
Also see <a class="link" href= Also see <a class="link" href=
"#RCL.SEARCH.LANG.MODIFIERS" title= "#RCL.SEARCH.LANG.MODIFIERS" title=
"3.5.2.&nbsp;Modifiers">the modifier section</a> from "3.5.4.&nbsp;Modifiers">the modifier section</a> from
the query language documentation.</p> the query language documentation.</p>
<p><b>AutoPhrases.&nbsp;</b>This option can be set in <p><b>AutoPhrases.&nbsp;</b>This option can be set in
the preferences dialog. If it is set, a phrase will be the preferences dialog. If it is set, a phrase will be
@ -5213,22 +5223,35 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
</div> </div>
</div> </div>
</div> </div>
<p>The <span class="application">Recoll</span> query
language was based on the now defunct <a class="ulink"
href="http://www.xesam.org/main/XesamUserSearchLanguage95"
target="_top">Xesam</a> user search language specification.
It allows defining general boolean searches within the main
body text or specific fields, and has many additional
features, broadly equivalent to those provided by
<span class="emphasis"><em>complex search</em></span>
interface in the GUI.</p>
<p>The query language processor is activated in the GUI <p>The query language processor is activated in the GUI
simple search entry when the search mode selector is set to simple search entry when the search mode selector is set to
<span class="guilabel">Query Language</span>. It can also <code class="literal">Query Language</code>. It can also be
be used with the KIO slave or the command line search. It used from the command line search, the KIO slave, or the
broadly has the same capabilities as the complex search WEB UI.</p>
interface in the GUI.</p>
<p>The language was based on the now defunct <a class=
"ulink" href=
"http://www.xesam.org/main/XesamUserSearchLanguage95"
target="_top">Xesam</a> user search language
specification.</p>
<p>If the results of a query language search puzzle you and <p>If the results of a query language search puzzle you and
you doubt what has been actually searched for, you can use you doubt what has been actually searched for, you can use
the GUI <code class="literal">Show Query</code> link at the the GUI <code class="literal">Show Query</code> link at the
top of the result list to check the exact query which was top of the result list to check the exact query which was
finally executed by Xapian.</p> finally executed by Xapian.</p>
<div class="sect2">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="RCL.SEARCH.LANG.SYNTAX"
id="RCL.SEARCH.LANG.SYNTAX"></a>3.5.1.&nbsp;General
syntax</h3>
</div>
</div>
</div>
<p>Here follows a sample request that we are going to <p>Here follows a sample request that we are going to
explain:</p> explain:</p>
<pre class="programlisting"> <pre class="programlisting">
@ -5243,17 +5266,27 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
"replaceable"><code>beatles</code></em> or <em class= "replaceable"><code>beatles</code></em> or <em class=
"replaceable"><code>lennon</code></em> and either "replaceable"><code>lennon</code></em> and either
<em class="replaceable"><code>live</code></em> or <em class="replaceable"><code>live</code></em> or
<em class="replaceable"><code>unplugged</code></em> but not <em class="replaceable"><code>unplugged</code></em> but
<em class="replaceable"><code>potatoes</code></em> (in any not <em class="replaceable"><code>potatoes</code></em>
part of the document).</p> (in any part of the document).</p>
<p>An element is composed of an optional field <p>An element is composed of an optional field
specification, and a value, separated by a colon (the field specification, and a value, separated by a colon (the
separator is the last colon in the element). Examples: field separator is the last colon in the element).
<em class="replaceable"><code>Eugenie</code></em>, Examples:</p>
<em class="replaceable"><code>author:balzac</code></em>, <div class="itemizedlist">
<em class="replaceable"><code>dc:title:grandet</code></em> <ul class="itemizedlist" style=
<em class="replaceable"><code>dc:title:"eugenie "list-style-type: disc;">
grandet"</code></em></p> <li class="listitem"><em class=
"replaceable"><code>Eugenie</code></em></li>
<li class="listitem"><em class=
"replaceable"><code>author:balzac</code></em></li>
<li class="listitem"><em class=
"replaceable"><code>dc:title:grandet</code></em></li>
<li class="listitem"><em class=
"replaceable"><code>dc:title:"eugenie
grandet"</code></em></li>
</ul>
</div>
<p>The colon, if present, means "contains". Xesam defines <p>The colon, if present, means "contains". Xesam defines
other relations, which are mostly unsupported for now other relations, which are mostly unsupported for now
(except in special cases, described further down).</p> (except in special cases, described further down).</p>
@ -5277,34 +5310,33 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
"replaceable"><code>word2</code></em>) <code class= "replaceable"><code>word2</code></em>) <code class=
"literal">OR</code> <em class= "literal">OR</code> <em class=
"replaceable"><code>word3</code></em>.</p> "replaceable"><code>word3</code></em>.</p>
<p><span class="application">Recoll</span> versions 1.21 <p>You can use parentheses to group elements (from
and later, allow using parentheses to group elements, which version 1.21), which will sometimes make things clearer,
will sometimes make things clearer, and may allow and may allow expressing combinations which would have
expressing combinations which would have been difficult been difficult otherwise.</p>
otherwise.</p> <p>An element preceded by a <code class=
<p>An element preceded by a <code class="literal">-</code> "literal">-</code> specifies a term that should
specifies a term that should <span class= <span class="emphasis"><em>not</em></span> appear.</p>
"emphasis"><em>not</em></span> appear.</p> <p>As usual, words inside quotes define a phrase (the
<p>As usual, words inside quotes define a phrase (the order order of words is significant), so that <em class=
of words is significant), so that <em class= "replaceable"><code>title:"prejudice pride"</code></em>
"replaceable"><code>title:"prejudice pride"</code></em> is is not the same as <em class=
not the same as <em class=
"replaceable"><code>title:prejudice "replaceable"><code>title:prejudice
title:pride</code></em>, and is unlikely to find a title:pride</code></em>, and is unlikely to find a
result.</p> result.</p>
<p>Words inside phrases and capitalized words are not <p>Words inside phrases and capitalized words are not
stem-expanded. Wildcards may be used anywhere inside a stem-expanded. Wildcards may be used anywhere inside a
term. Specifying a wild-card on the left of a term can term. Specifying a wildcard on the left of a term can
produce a very slow search (or even an incorrect one if the produce a very slow search (or even an incorrect one if
expansion is truncated because of excessive size). Also see the expansion is truncated because of excessive size).
<a class="link" href="#RCL.SEARCH.WILDCARDS" title= Also see <a class="link" href="#RCL.SEARCH.WILDCARDS"
"3.6.1.&nbsp;More about wildcards">More about title="3.6.1.&nbsp;Wildcards">More about
wildcards</a>.</p> wildcards</a>.</p>
<p>To save you some typing, recent <span class= <p>To save you some typing, <span class=
"application">Recoll</span> versions (1.20 and later) "application">Recoll</span> versions 1.20 and later
interpret a comma-separated list of terms for a field as an interpret a field value given as a comma-separated list
AND list inside the field. Use slash characters ('/') for of terms as an AND list and a slash-separated list as an
an OR list. No white space is allowed. So</p> OR list. No white space is allowed. So</p>
<pre class="programlisting">author:john,lennon</pre> <pre class="programlisting">author:john,lennon</pre>
<p>will search for documents with <code class= <p>will search for documents with <code class=
"literal">john</code> and <code class= "literal">john</code> and <code class=
@ -5312,22 +5344,30 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
"literal">author</code> field (in any order), and</p> "literal">author</code> field (in any order), and</p>
<pre class="programlisting">author:john/ringo</pre> <pre class="programlisting">author:john/ringo</pre>
<p>would search for <code class="literal">john</code> or <p>would search for <code class="literal">john</code> or
<code class="literal">ringo</code>. This behaviour only <code class="literal">ringo</code>. This behaviour is
happens for field queries (input without a field, comma- or only triggered by a field prefix: without it, comma- or
slash- separated input will produce a phrase search). You slash- separated input will produce a phrase search.
can use a <code class="literal">text</code> field name to However, you can use a <code class="literal">text</code>
search the main text this way.</p> field name to search the main text this way, as an
alternate to using an explicit <code class=
"literal">OR</code>, e.g. <code class=
"literal">text:napoleon/bonaparte</code> would generate a
search for <em class=
"replaceable"><code>napoleon</code></em> or <em class=
"replaceable"><code>bonaparte</code></em> in the main
text body.</p>
<p>Modifiers can be set on a double-quote value, for <p>Modifiers can be set on a double-quote value, for
example to specify a proximity search (unordered). See example to specify a proximity search (unordered). See
<a class="link" href="#RCL.SEARCH.LANG.MODIFIERS" title= <a class="link" href="#RCL.SEARCH.LANG.MODIFIERS" title=
"3.5.2.&nbsp;Modifiers">the modifier section</a>. No space "3.5.4.&nbsp;Modifiers">the modifier section</a>. No
must separate the final double-quote and the modifiers space must separate the final double-quote and the
value, e.g. <em class="replaceable"><code>"two modifiers value, e.g. <em class="replaceable"><code>"two
one"po10</code></em></p> one"po10</code></em></p>
<p><span class="application">Recoll</span> currently <p><span class="application">Recoll</span> currently
manages the following default fields:</p> manages the following default fields:</p>
<div class="itemizedlist"> <div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc;"> <ul class="itemizedlist" style=
"list-style-type: disc;">
<li class="listitem"> <li class="listitem">
<p><code class="literal">title</code>, <code class= <p><code class="literal">title</code>, <code class=
"literal">subject</code> or <code class= "literal">subject</code> or <code class=
@ -5346,32 +5386,34 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
documents recipients.</p> documents recipients.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">keyword</code> for searching <p><code class="literal">keyword</code> for
the document-specified keywords (few documents searching the document-specified keywords (few
actually have any).</p> documents actually have any).</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">filename</code> for the <p><code class="literal">filename</code> for the
document's file name. This is not necessarily set for document's file name. You can use the shorter
all documents: internal documents contained inside a <code class="literal">fn</code> alias. This value
compound one (for example an EPUB section) do not is not set for all documents: internal documents
inherit the container file name any more, this was contained inside a compound one (for example an
replaced by an explicit field (see next). EPUB section) do not inherit the container file
Sub-documents can still have a specific <code class= name any more, this was replaced by an explicit
"literal">filename</code>, if it is implied by the field (see next). Sub-documents can still have a
document format, for example the attachment file name <code class="literal">filename</code>, if it is
for an email attachment.</p> implied by the document format, for example the
attachment file name for an email attachment.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">containerfilename</code>. <p><code class="literal">containerfilename</code>,
This is set for all documents, both top-level and aliased as <code class="literal">cfn</code>. This
is set for all documents, both top-level and
contained sub-documents, and is always the name of contained sub-documents, and is always the name of
the filesystem directory entry which contains the the filesystem file which contains the data. The
data. The terms from this field can only be matched terms from this field can only be matched by an
by an explicit field specification (as opposed to explicit field specification (as opposed to terms
terms from <code class="literal">filename</code> from <code class="literal">filename</code> which
which are also indexed as general document content). are also indexed as general document content). This
This avoids getting matches for all the sub-documents avoids getting matches for all the sub-documents
when searching for the container file name.</p> when searching for the container file name.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
@ -5385,59 +5427,79 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
displaying the duplicates of a search result (when displaying the duplicates of a search result (when
querying with the option to collapse duplicate querying with the option to collapse duplicate
results). Incidentally, this could be used to find results). Incidentally, this could be used to find
the duplicates of any given file by computing its MD5 the duplicates of any given file by computing its
checksum and executing a query with just the MD5 checksum and executing a query with just the
<code class="literal">rclmd5</code> value.</p> <code class="literal">rclmd5</code> value.</p>
</li> </li>
</ul> </ul>
</div> </div>
<p><span class="application">Recoll</span> 1.20 and later <p>You can define aliases for field names, in order to
have a way to specify aliases for the field names, which use your preferred denomination or to save typing (e.g.
will save typing, for example by aliasing <code class= the predefined <code class="literal">fn</code> and
"literal">filename</code> to <em class= <code class="literal">cfn</code> aliases defined for
"replaceable"><code>fn</code></em> or <code class= <code class="literal">filename</code> and <code class=
"literal">containerfilename</code> to <em class= "literal">containerfilename</code>). See the <a class=
"replaceable"><code>cfn</code></em>. See the <a class=
"link" href="#RCL.INSTALL.CONFIG.FIELDS" title= "link" href="#RCL.INSTALL.CONFIG.FIELDS" title=
"5.4.3.&nbsp;The fields file">section about the "5.4.3.&nbsp;The fields file">section about the
<code class="filename">fields</code> file</a>.</p> <code class="filename">fields</code> file</a>.</p>
<p>The document input handlers used while indexing have the <p>The document input handlers have the possibility to
possibility to create other fields with arbitrary names, create other fields with arbitrary names, and aliases may
and aliases may be defined in the configuration, so that be defined in the configuration, so that the exact field
the exact field search possibilities may be different for search possibilities may be different for you if someone
you if someone took care of the customisation.</p> took care of the customisation.</p>
</div>
<div class="sect2">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name=
"RCL.SEARCH.LANG.SPECIALFIELDS" id=
"RCL.SEARCH.LANG.SPECIALFIELDS"></a>3.5.2.&nbsp;Special
field-like specifiers</h3>
</div>
</div>
</div>
<p>The field syntax also supports a few field-like, but <p>The field syntax also supports a few field-like, but
special, criteria:</p> special, criteria, for which the values are interpreted
differently. Regular processing does not apply (for
example the slash- or comma- separated lists don't work).
A list follows.</p>
<div class="itemizedlist"> <div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc;"> <ul class="itemizedlist" style=
"list-style-type: disc;">
<li class="listitem"> <li class="listitem">
<p><code class="literal">dir</code> for filtering the <p><a name="RCL.SEARCH.LANG.SPECIALFIELDS.DIR" id=
results on file location (Ex: <code class= "RCL.SEARCH.LANG.SPECIALFIELDS.DIR"></a><code class="literal">dir</code>
"literal">dir:/home/me/somedir</code>). <code class= for filtering the results on file location. For
"literal">-dir</code> also works to find results not example, <code class=
in the specified directory (release &gt;= 1.15.8). "literal">dir:/home/me/somedir</code> will restrict
Tilde expansion will be performed as usual (except the search to results found anywhere under the
for a bug in versions 1.19 to 1.19.11p1). Wildcards <em class=
will be expanded, but please <a class="link" href= "replaceable"><code>/home/me/somedir</code></em>
"#RCL.SEARCH.WILDCARDS.PATH" title= directory (including subdirectories).</p>
"Wildcards and path filtering">have a look</a> at an <p>Tilde expansion will be performed as usual.
important limitation of wildcards in path Wildcards will be expanded, but please <a class=
"link" href="#RCL.SEARCH.WILDCARDS.PATH" title=
"Wildcards and path filtering">have a look</a> at
an important limitation of wildcards in path
filters.</p> filters.</p>
<p>Relative paths also make sense, for example, <p>You can also use relative paths. For example,
<code class="literal">dir:share/doc</code> would <code class="literal">dir:share/doc</code> would
match either <code class= match either <code class=
"filename">/usr/share/doc</code> or <code class= "filename">/usr/share/doc</code> or <code class=
"filename">/usr/local/share/doc</code></p> "filename">/usr/local/share/doc</code>.</p>
<p><code class="literal">-dir</code> will find
results <span class="emphasis"><em>not</em></span>
in the specified location.</p>
<p>Several <code class="literal">dir</code> clauses <p>Several <code class="literal">dir</code> clauses
can be specified, both positive and negative. For can be specified, both positive and negative. For
example the following makes sense:</p> example the following makes sense:</p>
<pre class="programlisting"> <pre class=
dir:recoll dir:src -dir:utils -dir:common "programlisting">dir:recoll dir:src -dir:utils -dir:common</pre>
</pre>
<p>This would select results which have both <p>This would select results which have both
<code class="filename">recoll</code> and <code class= <code class="filename">recoll</code> and
"filename">src</code> in the path (in any order), and <code class="filename">src</code> in the path (in
which have not either <code class= any order), and which have not either <code class=
"filename">utils</code> or <code class= "filename">utils</code> or <code class=
"filename">common</code>.</p> "filename">common</code>.</p>
<p>You can also use <code class="literal">OR</code> <p>You can also use <code class="literal">OR</code>
@ -5446,15 +5508,18 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<p>A special aspect of <code class= <p>A special aspect of <code class=
"literal">dir</code> clauses is that the values in "literal">dir</code> clauses is that the values in
the index are not transcoded to UTF-8, and never the index are not transcoded to UTF-8, and never
lower-cased or unaccented, but stored as binary. This lower-cased or unaccented, but stored as binary.
means that you need to enter the values in the exact This means that you need to enter the values in the
lower or upper case, and that searches for names with exact lower or upper case, and that searches for
diacritics may sometimes be impossible because of names with diacritics may sometimes be impossible
character set conversion issues. Non-ASCII UNIX file because of character set conversion issues.
paths are an unending source of trouble and are best Non-ASCII UNIX file paths are an unending source of
avoided.</p> trouble and are best avoided.</p>
<p>You need to use double-quotes around the path <p>You need to use double-quotes around the path
value if it contains space characters.</p> value if it contains space characters.</p>
<p>The shortcut syntax to define OR or AND lists
within fields with commas or slash characters is
not available.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">size</code> for filtering <p><code class="literal">size</code> for filtering
@ -5464,16 +5529,16 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
"literal">&gt;</code> or <code class= "literal">&gt;</code> or <code class=
"literal">=</code> as operators. You can specify a "literal">=</code> as operators. You can specify a
range like the following: <code class= range like the following: <code class=
"literal">size&gt;100 size&lt;1000</code>. The usual "literal">size&gt;100 size&lt;1000</code>. The
<code class="literal">k/K, m/M, g/G, t/T</code> can usual <code class="literal">k/K, m/M, g/G,
be used as (decimal) multipliers. Ex: <code class= t/T</code> can be used as (decimal) multipliers.
"literal">size&gt;1k</code> to search for files Ex: <code class="literal">size&gt;1k</code> to
bigger than 1000 bytes.</p> search for files bigger than 1000 bytes.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">date</code> for searching or <p><code class="literal">date</code> for searching
filtering on dates. The syntax for the argument is or filtering on dates. The syntax for the argument
based on the ISO8601 standard for dates and time is based on the ISO8601 standard for dates and time
intervals. Only dates are supported, no times. The intervals. Only dates are supported, no times. The
general syntax is 2 elements separated by a general syntax is 2 elements separated by a
<code class="literal">/</code> character. Each <code class="literal">/</code> character. Each
@ -5511,13 +5576,13 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
specified with a period.</p> specified with a period.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">2001/</code> from the <p><code class="literal">2001/</code> from
beginning of 2001 to the latest date in the the beginning of 2001 to the latest date in
index.</p> the index.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">2001</code> the whole <p><code class="literal">2001</code> the
year of 2001</p> whole year of 2001</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">P2D/</code> means 2 <p><code class="literal">P2D/</code> means 2
@ -5534,35 +5599,37 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
(ie: p2y).</p> (ie: p2y).</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">mime</code> or <code class= <p><code class="literal">mime</code> or
"literal">format</code> for specifying the MIME type. <code class="literal">format</code> for specifying
These clauses are processed besides the normal the MIME type. These clauses are processed apart
Boolean logic of the search. Multiple values will be from the normal Boolean logic of the search:
OR'ed (instead of the normal AND). You can specify multiple values will be OR'ed (instead of the
types to be excluded, with the usual <code class= normal AND). You can specify types to be excluded,
"literal">-</code>, and use wildcards. Example: with the usual <code class="literal">-</code>, and
<em class="replaceable"><code>mime:text/* use wildcards. Example: <em class=
-mime:text/plain</code></em> Specifying an explicit "replaceable"><code>mime:text/*
boolean operator before a <code class= -mime:text/plain</code></em>. Specifying an
"literal">mime</code> specification is not supported explicit boolean operator before a <code class=
and will produce strange results.</p> "literal">mime</code> specification is not
supported and will produce strange results.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">type</code> or <code class= <p><code class="literal">type</code> or
"literal">rclcat</code> for specifying the category <code class="literal">rclcat</code> for specifying
(as in text/media/presentation/etc.). The the category (as in text/media/presentation/etc.).
classification of MIME types in categories is defined The classification of MIME types in categories is
in the <span class="application">Recoll</span> defined in the <span class=
configuration (<code class= "application">Recoll</span> configuration
"filename">mimeconf</code>), and can be modified or (<code class="filename">mimeconf</code>), and can
extended. The default category names are those which be modified or extended. The default category names
permit filtering results in the main GUI screen. are those which permit filtering results in the
Categories are OR'ed like MIME types above, and can main GUI screen. Categories are OR'ed like MIME
be negated with <code class="literal">-</code>.</p> types above, and can be negated with <code class=
"literal">-</code>.</p>
</li> </li>
<li class="listitem"> <li class="listitem">
<p><code class="literal">issub</code> for specifying <p><code class="literal">issub</code> for
that only standalone (<code class= specifying that only standalone (<code class=
"literal">issub:0</code>) or only embedded "literal">issub:0</code>) or only embedded
(<code class="literal">issub:1</code>) documents (<code class="literal">issub:1</code>) documents
should be returned as results.</p> should be returned as results.</p>
@ -5574,28 +5641,29 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<h3 class="title">Note</h3> <h3 class="title">Note</h3>
<p><code class="literal">mime</code>, <code class= <p><code class="literal">mime</code>, <code class=
"literal">rclcat</code>, <code class= "literal">rclcat</code>, <code class=
"literal">size</code>, <code class="literal">issub</code> "literal">size</code>, <code class=
and <code class="literal">date</code> criteria always "literal">issub</code> and <code class=
affect the whole query (they are applied as a final "literal">date</code> criteria always affect the whole
filter), even if set with other terms inside a query (they are applied as a final filter), even if set
parenthese.</p> with other terms inside a parenthese.</p>
</div> </div>
<div class="note" style= <div class="note" style=
"margin-left: 0.5in; margin-right: 0.5in;"> "margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3> <h3 class="title">Note</h3>
<p><code class="literal">mime</code> (or the equivalent <p><code class="literal">mime</code> (or the equivalent
<code class="literal">rclcat</code>) is the <span class= <code class="literal">rclcat</code>) is the
"emphasis"><em>only</em></span> field with an <span class="emphasis"><em>only</em></span> field with
<code class="literal">OR</code> default. You do need to an <code class="literal">OR</code> default. You do need
use <code class="literal">OR</code> with <code class= to use <code class="literal">OR</code> with
"literal">ext</code> terms for example.</p> <code class="literal">ext</code> terms for example.</p>
</div>
</div> </div>
<div class="sect2"> <div class="sect2">
<div class="titlepage"> <div class="titlepage">
<div> <div>
<div> <div>
<h3 class="title"><a name="RCL.SEARCH.LANG.RANGES" <h3 class="title"><a name="RCL.SEARCH.LANG.RANGES"
id="RCL.SEARCH.LANG.RANGES"></a>3.5.1.&nbsp;Range id="RCL.SEARCH.LANG.RANGES"></a>3.5.3.&nbsp;Range
clauses</h3> clauses</h3>
</div> </div>
</div> </div>
@ -5634,7 +5702,7 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<div> <div>
<h3 class="title"><a name= <h3 class="title"><a name=
"RCL.SEARCH.LANG.MODIFIERS" id= "RCL.SEARCH.LANG.MODIFIERS" id=
"RCL.SEARCH.LANG.MODIFIERS"></a>3.5.2.&nbsp;Modifiers</h3> "RCL.SEARCH.LANG.MODIFIERS"></a>3.5.4.&nbsp;Modifiers</h3>
</div> </div>
</div> </div>
</div> </div>
@ -5698,8 +5766,8 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<div> <div>
<h2 class="title" style="clear: both"><a name= <h2 class="title" style="clear: both"><a name=
"RCL.SEARCH.ANCHORWILD" id= "RCL.SEARCH.ANCHORWILD" id=
"RCL.SEARCH.ANCHORWILD"></a>3.6.&nbsp;Anchored "RCL.SEARCH.ANCHORWILD"></a>3.6.&nbsp;Wildcards and
searches and wildcards</h2> anchored searches</h2>
</div> </div>
</div> </div>
</div> </div>
@ -5714,8 +5782,7 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<div> <div>
<div> <div>
<h3 class="title"><a name="RCL.SEARCH.WILDCARDS" <h3 class="title"><a name="RCL.SEARCH.WILDCARDS"
id="RCL.SEARCH.WILDCARDS"></a>3.6.1.&nbsp;More id="RCL.SEARCH.WILDCARDS"></a>3.6.1.&nbsp;Wildcards</h3>
about wildcards</h3>
</div> </div>
</div> </div>
</div> </div>

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

@ -1399,25 +1399,21 @@ metadatacmds = ; <replaceable>tags</replaceable> = tmsu tags %f
extend the <link linkend="RCL.PROGRAM.FIELDS">field extend the <link linkend="RCL.PROGRAM.FIELDS">field
configuration</link>.</para> configuration</link>.</para>
<para>Once re-indexing is performed (you will need to force the file <para>Once re-indexing is performed (you will need to force the file reindexing, &RCL; will
reindexing, &RCL; will not detect the need by itself), you will be not detect the need by itself), you will be able to search from the query language, through
able to search from the query language, through any of its aliases: any of its aliases: <replaceable>tags:some/alternate/values</replaceable>
<replaceable>tags:some/alternate/values</replaceable> or or <replaceable>tags:all,these,values</replaceable>. The compact comma- or slash-based field
<replaceable>tags:all,these,values</replaceable> (the compact field search search syntax is supported for recoll 1.20 and later. For older versions, you would need to
syntax is supported for recoll 1.20 and later. For older versions, repeat the <replaceable>tags:</replaceable> specifier for each term,
you would need to repeat the <replaceable>tags:</replaceable> e.g. <replaceable>tags:some</replaceable> <literal>OR</literal>
specifier for each term, e.g. <replaceable>tags:some</replaceable> <replaceable>tags:alternate</replaceable>.</para>
<literal>OR</literal>
<replaceable>tags:alternate</replaceable>).</para>
<para>Tags changes will not be detected by <para>Tags changes will not be detected by the indexer if the file itself did not change. One
the indexer if the file itself did not change. One possible possible workaround would be to update the file <literal>ctime</literal> when you modify the
workaround would be to update the file <literal>ctime</literal> when tags, which would be consistent with how extended attributes function. A pair
you modify the tags, which of <command>chmod</command> commands could accomplish this, or a
would be consistent with how extended attributes function. A pair of <literal>touch -a</literal>.
<command>chmod</command> commands could accomplish this, or a Alternatively, just couple the tag update with a
<literal>touch -a</literal> . Alternatively, just
couple the tag update with a
<literal>recollindex -e -i</literal> <replaceable>/path/to/the/file</replaceable>.</para> <literal>recollindex -e -i</literal> <replaceable>/path/to/the/file</replaceable>.</para>
</sect1> </sect1>
@ -1918,11 +1914,12 @@ fs.inotify.max_user_watches=32768
<itemizedlist> <itemizedlist>
<listitem><para>In <literal>All Terms</literal> mode, &RCL; looks <listitem><para>In <literal>All Terms</literal> mode, &RCL; looks
for documents containing all your input terms.</para></listitem> for documents containing all your input terms.</para></listitem>
<listitem><para><literal>Query Language</literal> mode behaves like
<literal>All Terms</literal> in the absence of special input, but <listitem><para>The <literal>Query Language</literal> mode behaves like <literal>All
it can also do much more. This is the best mode for getting the Terms</literal> in the absence of special input, but it can also do much more. This is the
most of &RCL;.</para></listitem> best mode for getting the most of &RCL;. It is usable from all possible interfaces (GUI,
command line, WEB UI, ...), and is <link linkend="RCL.SEARCH.LANG">described
here</link>.</para></listitem>
<listitem><para>In <literal>Any Term</literal> mode, &RCL; looks <listitem><para>In <literal>Any Term</literal> mode, &RCL; looks
for documents containing any your input terms, preferring those for documents containing any your input terms, preferring those
@ -2067,8 +2064,8 @@ fs.inotify.max_user_watches=32768
<para>The <guilabel>File name</guilabel> search mode will <para>The <guilabel>File name</guilabel> search mode will
specifically look for file names. The point of having a separate specifically look for file names. The point of having a separate
file name search is that wild card expansion can be performed more file name search is that wildcard expansion can be performed more
efficiently on a small subset of the index (allowing wild cards on efficiently on a small subset of the index (allowing wildcards on
the left of terms without excessive cost). Things to know: the left of terms without excessive cost). Things to know:
<itemizedlist> <itemizedlist>
<listitem><para>White space in the entry should match white <listitem><para>White space in the entry should match white
@ -2077,7 +2074,7 @@ fs.inotify.max_user_watches=32768
<listitem><para>The search is insensitive to character case and <listitem><para>The search is insensitive to character case and
accents, independently of the type of index.</para> accents, independently of the type of index.</para>
</listitem> </listitem>
<listitem><para>An entry without any wild card <listitem><para>An entry without any wildcard
character and not capitalized will be prepended and appended character and not capitalized will be prepended and appended
with '*' (ie: <replaceable>etc</replaceable> -> with '*' (ie: <replaceable>etc</replaceable> ->
<replaceable>*etc*</replaceable>, but <replaceable>*etc*</replaceable>, but
@ -3940,24 +3937,26 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<sect1 id="RCL.SEARCH.LANG"> <sect1 id="RCL.SEARCH.LANG">
<title>The query language</title> <title>The query language</title>
<para>The query language processor is activated in the GUI <para>The &RCL; query language was based on the now defunct
simple search entry when the search mode selector is set to <ulink url="http://www.xesam.org/main/XesamUserSearchLanguage95">
<guilabel>Query Language</guilabel>. It can also be used with the KIO Xesam</ulink> user search language specification. It allows defining general boolean
slave or the command line search. It broadly has the same searches within the main body text or specific fields, and has many additional features,
capabilities as the complex search interface in the broadly equivalent to those provided by <emphasis>complex search</emphasis> interface in the
GUI.</para> GUI.</para>
<para>The language was based on the now defunct <para>The query language processor is activated in the GUI simple search entry when the search
<ulink url="http://www.xesam.org/main/XesamUserSearchLanguage95"> mode selector is set to <literal>Query Language</literal>. It can also be used from the
Xesam</ulink> user search language specification.</para> command line search, the KIO slave, or the WEB UI.</para>
<para>If the results of a query language search puzzle you and you <para>If the results of a query language search puzzle you and you
doubt what has been actually searched for, you can use the GUI doubt what has been actually searched for, you can use the GUI <literal>Show Query</literal>
<literal>Show Query</literal> link at the top of the result list to link at the top of the result list to check the exact query which was finally executed by
check the exact query which was finally executed by Xapian.</para> Xapian.</para>
<para>Here follows a sample request that we are going to <sect2 id="RCL.SEARCH.LANG.SYNTAX">
explain:</para> <title>General syntax</title>
<para>Here follows a sample request that we are going to explain:</para>
<programlisting> <programlisting>
author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes
@ -3977,10 +3976,12 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<para>An element is composed of an optional field specification, <para>An element is composed of an optional field specification,
and a value, separated by a colon (the field separator is the last and a value, separated by a colon (the field separator is the last
colon in the element). Examples: colon in the element). Examples:
<replaceable>Eugenie</replaceable>, <itemizedlist>
<replaceable>author:balzac</replaceable>, <listitem><replaceable>Eugenie</replaceable></listitem>
<replaceable>dc:title:grandet</replaceable> <listitem><replaceable>author:balzac</replaceable></listitem>
<replaceable>dc:title:"eugenie grandet"</replaceable> <listitem><replaceable>dc:title:grandet</replaceable></listitem>
<listitem><replaceable>dc:title:"eugenie grandet"</replaceable></listitem>
</itemizedlist>
</para> </para>
<para>The colon, if present, means "contains". Xesam defines other <para>The colon, if present, means "contains". Xesam defines other
@ -4005,41 +4006,38 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
<replaceable>word2</replaceable>) <literal>OR</literal> <replaceable>word2</replaceable>) <literal>OR</literal>
<replaceable>word3</replaceable>. </para> <replaceable>word3</replaceable>. </para>
<para>&RCL; versions 1.21 and later, allow using parentheses to <para>You can use parentheses to group elements (from version 1.21), which will sometimes make
group elements, which will sometimes make things clearer, and may things clearer, and may allow expressing combinations which would have been difficult
allow expressing combinations which would have been difficult
otherwise.</para> otherwise.</para>
<para>An element preceded by a <literal>-</literal> specifies a <para>An element preceded by a <literal>-</literal> specifies a
term that should <emphasis>not</emphasis> appear.</para> term that should <emphasis>not</emphasis> appear.</para>
<para>As usual, words inside quotes define a phrase <para>As usual, words inside quotes define a phrase (the order of words is significant), so
(the order of words is significant), so that that <replaceable>title:"prejudice pride"</replaceable> is not the same
<replaceable>title:"prejudice pride"</replaceable> is not the same as as <replaceable>title:prejudice title:pride</replaceable>, and is unlikely to find a
<replaceable>title:prejudice title:pride</replaceable>, and is result.</para>
unlikely to find a result.</para>
<para>Words inside phrases and capitalized words are not <para>Words inside phrases and capitalized words are not stem-expanded. Wildcards may be used
stem-expanded. Wildcards may be used anywhere inside a term. anywhere inside a term. Specifying a wildcard on the left of a term can produce a very slow
Specifying a wild-card on the left of a term can produce a very search (or even an incorrect one if the expansion is truncated because of excessive
slow search (or even an incorrect one if the expansion is size). Also see <link linkend="RCL.SEARCH.WILDCARDS">More about wildcards</link>.
truncated because of excessive size). Also see
<link linkend="RCL.SEARCH.WILDCARDS">More about wildcards</link>.
</para> </para>
<para>To save you some typing, recent &RCL; versions (1.20 and later) <para>To save you some typing, &RCL; versions 1.20 and later
interpret a comma-separated list of terms for a field as an AND list interpret a field value given as a comma-separated list of terms as an AND list and a
inside the field. Use slash characters ('/') for an OR list. No white slash-separated list as an OR list. No white space is
space is allowed. So allowed. So <programlisting>author:john,lennon</programlisting> will search for documents
<programlisting>author:john,lennon</programlisting> will search for with <literal>john</literal> and <literal>lennon</literal> inside
documents with <literal>john</literal> and <literal>lennon</literal> the <literal>author</literal> field (in any order),
inside the <literal>author</literal> field (in any order), and and <programlisting>author:john/ringo</programlisting> would search
<programlisting>author:john/ringo</programlisting> would search for for <literal>john</literal> or <literal>ringo</literal>. This behaviour is only triggered by
<literal>john</literal> or <literal>ringo</literal>. This behaviour a field prefix: without it, comma- or slash- separated input will produce a phrase
only happens for field queries (input without a field, comma- or search. However, you can use a <literal>text</literal> field name to search the main text
slash- separated input will produce a phrase search). You can use a this way, as an alternate to using an explicit <literal>OR</literal>,
<literal>text</literal> field name to search the main text this e.g. <literal>text:napoleon/bonaparte</literal> would generate a search
way.</para> for <replaceable>napoleon</replaceable> or <replaceable>bonaparte</replaceable> in the main
text body.</para>
<para>Modifiers can be set on a double-quote value, for example to specify <para>Modifiers can be set on a double-quote value, for example to specify
a proximity search (unordered). See a proximity search (unordered). See
@ -4073,23 +4071,20 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
</listitem> </listitem>
<listitem><para><literal>filename</literal> for the document's <listitem><para><literal>filename</literal> for the document's
file name. This is not necessarily set for all documents: file name. You can use the shorter <literal>fn</literal> alias. This value is not set
internal documents contained inside a compound one (for example for all documents: internal documents contained inside a compound one (for example an
an EPUB section) do not inherit the container file name any more, EPUB section) do not inherit the container file name any more, this was replaced by an
this was replaced by an explicit field (see next). Sub-documents explicit field (see next). Sub-documents can still have a <literal>filename</literal>,
can still have a specific <literal>filename</literal>, if it is if it is implied by the document format, for example the attachment file name for an
implied by the document format, for example the attachment file email attachment.</para></listitem>
name for an email attachment.</para></listitem>
<listitem><para><literal>containerfilename</literal>. This is <listitem><para><literal>containerfilename</literal>, aliased
set for all documents, both top-level and contained as <literal>cfn</literal>. This is set for all documents, both top-level and contained
sub-documents, and is always the name of the filesystem directory sub-documents, and is always the name of the filesystem file which contains the
entry which contains the data. The terms from this field can data. The terms from this field can only be matched by an explicit field specification
only be matched by an explicit field specification (as opposed (as opposed to terms from <literal>filename</literal> which are also indexed as general
to terms from <literal>filename</literal> which are also indexed document content). This avoids getting matches for all the sub-documents when searching
as general document content). This avoids getting matches for for the container file name.</para></listitem>
all the sub-documents when searching for the container file
name.</para></listitem>
<listitem><para><literal>ext</literal> specifies the file <listitem><para><literal>ext</literal> specifies the file
name extension name extension
@ -4106,47 +4101,49 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
</itemizedlist> </itemizedlist>
<para>&RCL; 1.20 and later have a way to specify aliases for the <para>You can define aliases for field names, in order to use your preferred denomination or
field names, which will save typing, for example by aliasing to save typing (e.g. the predefined <literal>fn</literal> and <literal>cfn</literal> aliases
<literal>filename</literal> to <replaceable>fn</replaceable> or defined for <literal>filename</literal> and <literal>containerfilename</literal>). See
<literal>containerfilename</literal> to the <link linkend="RCL.INSTALL.CONFIG.FIELDS">section about the <filename>fields</filename>
<replaceable>cfn</replaceable>. See the file</link>.
<link linkend="RCL.INSTALL.CONFIG.FIELDS">section about the <filename>fields</filename> file</link>.
</para> </para>
<para>The document input handlers used while indexing have the <para>The document input handlers have the possibility to create other fields with arbitrary
possibility to create other fields with arbitrary names, and names, and aliases may be defined in the configuration, so that the exact field search
aliases may be defined in the configuration, so that the exact possibilities may be different for you if someone took care of the customisation.</para>
field search possibilities may be different for you if someone </sect2>
took care of the customisation.</para>
<para>The field syntax also supports a few field-like, but <sect2 id="RCL.SEARCH.LANG.SPECIALFIELDS">
special, criteria:</para> <title>Special field-like specifiers</title>
<para>The field syntax also supports a few field-like, but special, criteria, for which the
values are interpreted differently. Regular processing does not apply (for example the
slash- or comma- separated lists don't work). A list follows.</para>
<itemizedlist> <itemizedlist>
<listitem><para><literal>dir</literal> for filtering the <listitem>
results on file location <para id="RCL.SEARCH.LANG.SPECIALFIELDS.DIR"><literal>dir</literal> for filtering the
(Ex: <literal>dir:/home/me/somedir</literal>). results on file location. For example, <literal>dir:/home/me/somedir</literal> will
<literal>-dir</literal> restrict the search to results found anywhere under
also works to find results not in the specified directory the <replaceable>/home/me/somedir</replaceable> directory (including
(release >= 1.15.8). Tilde expansion will be performed as subdirectories).</para>
usual (except for a bug in versions 1.19 to
1.19.11p1). Wildcards will be expanded, but
please
<link linkend="RCL.SEARCH.WILDCARDS.PATH"> have a look</link>
at an important limitation of wildcards in path filters.</para>
<para>Relative paths also make sense, for example, <para>Tilde expansion will be performed as usual. Wildcards will be expanded, but
<literal>dir:share/doc</literal> would match either please <link linkend="RCL.SEARCH.WILDCARDS.PATH"> have a look</link> at an important
<filename>/usr/share/doc</filename> or limitation of wildcards in path filters.</para>
<filename>/usr/local/share/doc</filename> </para>
<para>You can also use relative paths. For example, <literal>dir:share/doc</literal> would
match either <filename>/usr/share/doc</filename>
or <filename>/usr/local/share/doc</filename>.</para>
<para><literal>-dir</literal> will find
results <emphasis>not</emphasis> in the specified location.</para>
<para>Several <literal>dir</literal> clauses can be specified, <para>Several <literal>dir</literal> clauses can be specified,
both positive and negative. For example the following makes sense: both positive and negative. For example the following makes sense:
<programlisting> <programlisting>dir:recoll dir:src -dir:utils -dir:common</programlisting>
dir:recoll dir:src -dir:utils -dir:common This would select results which have both
</programlisting> This would select results which have both
<filename>recoll</filename> and <filename>src</filename> in the <filename>recoll</filename> and <filename>src</filename> in the
path (in any order), and which have not either path (in any order), and which have not either
<filename>utils</filename> or <filename>utils</filename> or
@ -4156,16 +4153,17 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
with <literal>dir:</literal> clauses.</para> with <literal>dir:</literal> clauses.</para>
<para>A special aspect of <literal>dir</literal> clauses is <para>A special aspect of <literal>dir</literal> clauses is
that the values in the index are not transcoded to UTF-8, and that the values in the index are not transcoded to UTF-8, and never lower-cased or
never lower-cased or unaccented, but stored as binary. This means unaccented, but stored as binary. This means that you need to enter the values in the
that you need to enter the values in the exact lower or upper exact lower or upper case, and that searches for names with diacritics may sometimes be
case, and that searches for names with diacritics may sometimes impossible because of character set conversion issues. Non-ASCII UNIX file paths are an
be impossible because of character set conversion unending source of trouble and are best avoided.</para>
issues. Non-ASCII UNIX file paths are an unending source of
trouble and are best avoided.</para>
<para>You need to use double-quotes around the path value if it <para>You need to use double-quotes around the path value if it contains space
contains space characters.</para> characters.</para>
<para>The shortcut syntax to define OR or AND lists within fields with commas or slash
characters is not available.</para>
</listitem> </listitem>
@ -4219,17 +4217,13 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
p2y).</para> p2y).</para>
</listitem> </listitem>
<listitem><para><literal>mime</literal> or <listitem><para><literal>mime</literal> or <literal>format</literal> for specifying the MIME
<literal>format</literal> for specifying the type. These clauses are processed apart from the normal Boolean logic of the search:
MIME type. These clauses are processed besides the normal multiple values will be OR'ed (instead of the normal AND). You can specify types to be
Boolean logic of the search. Multiple values will be OR'ed
(instead of the normal AND). You can specify types to be
excluded, with the usual <literal>-</literal>, and use excluded, with the usual <literal>-</literal>, and use
wildcards. Example: <replaceable>mime:text/* wildcards. Example: <replaceable>mime:text/* -mime:text/plain</replaceable>. Specifying an
-mime:text/plain</replaceable> explicit boolean operator before a <literal>mime</literal> specification is not supported
Specifying an explicit boolean and will produce strange results. </para>
operator before a <literal>mime</literal> specification is not
supported and will produce strange results. </para>
</listitem> </listitem>
<listitem><para><literal>type</literal> or <listitem><para><literal>type</literal> or
@ -4264,6 +4258,7 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
field with an <literal>OR</literal> default. You do need to use field with an <literal>OR</literal> default. You do need to use
<literal>OR</literal> with <literal>ext</literal> terms for <literal>OR</literal> with <literal>ext</literal> terms for
example.</para> </note> example.</para> </note>
</sect2>
<sect2 id="RCL.SEARCH.LANG.RANGES"> <sect2 id="RCL.SEARCH.LANG.RANGES">
<title>Range clauses</title> <title>Range clauses</title>
@ -4343,20 +4338,18 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
</sect1> <!-- rcl.search.lang --> </sect1> <!-- rcl.search.lang -->
<sect1 id="RCL.SEARCH.ANCHORWILD"> <sect1 id="RCL.SEARCH.ANCHORWILD">
<title>Anchored searches and wildcards</title> <title>Wildcards and anchored searches</title>
<para>Some special characters are interpreted by &RCL; in search <para>Some special characters are interpreted by &RCL; in search
strings to expand or specialize the search. Wildcards expand a root strings to expand or specialize the search. Wildcards expand a root term in controlled
term in controlled ways. Anchor characters can restrict a search to ways. Anchor characters can restrict a search to succeed only if the match is found at or
succeed only if the match is found at or near the beginning of the near the beginning of the document or one of its fields.</para>
document or one of its fields.</para>
<sect2 id="RCL.SEARCH.WILDCARDS"> <sect2 id="RCL.SEARCH.WILDCARDS">
<title>More about wildcards</title> <title>Wildcards</title>
<para>All words entered in &RCL; search fields will be processed <para>All words entered in &RCL; search fields will be processed
for wildcard expansion before the request is finally for wildcard expansion before the request is finally executed.</para>
executed.</para>
<para>The wildcard characters are:</para> <para>The wildcard characters are:</para>
@ -4376,8 +4369,7 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>You should be aware of a few things when using <para>You should be aware of a few things when using wildcards.</para>
wildcards.</para>
<itemizedlist> <itemizedlist>
<listitem><para>Using a wildcard character at the beginning of <listitem><para>Using a wildcard character at the beginning of