small user manual fixes
This commit is contained in:
Jean-Francois Dockes
parent
60517fb838
commit
ffd589e384
@ -31,8 +31,10 @@ src/doc/user/rcl.kicker-applet.html
|
|||||||
src/doc/user/rcl.program.api.html
|
src/doc/user/rcl.program.api.html
|
||||||
src/doc/user/rcl.program.fields.html
|
src/doc/user/rcl.program.fields.html
|
||||||
src/doc/user/rcl.program.html
|
src/doc/user/rcl.program.html
|
||||||
|
src/doc/user/rcl.search.commandline.html
|
||||||
src/doc/user/rcl.search.complex.html
|
src/doc/user/rcl.search.complex.html
|
||||||
src/doc/user/rcl.search.custom.html
|
src/doc/user/rcl.search.custom.html
|
||||||
|
src/doc/user/rcl.search.desktop.html
|
||||||
src/doc/user/rcl.search.history.html
|
src/doc/user/rcl.search.history.html
|
||||||
src/doc/user/rcl.search.html
|
src/doc/user/rcl.search.html
|
||||||
src/doc/user/rcl.search.lang.html
|
src/doc/user/rcl.search.lang.html
|
||||||
|
|||||||
@ -620,6 +620,9 @@ fvwm
|
|||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
<chapter id="rcl.search">
|
<chapter id="rcl.search">
|
||||||
|
<title>Searching</title>
|
||||||
|
|
||||||
|
<sect1 id="rcl.search.gui">
|
||||||
<title>Searching with the Qt graphical user interface</title>
|
<title>Searching with the Qt graphical user interface</title>
|
||||||
|
|
||||||
<para>The <command>recoll</command> program provides the main user
|
<para>The <command>recoll</command> program provides the main user
|
||||||
@ -653,7 +656,7 @@ fvwm
|
|||||||
case (they would typically be printed without white
|
case (they would typically be printed without white
|
||||||
space).</para>
|
space).</para>
|
||||||
|
|
||||||
<sect1 id="rcl.search.simple">
|
<sect2 id="rcl.search.simple">
|
||||||
<title>Simple search</title>
|
<title>Simple search</title>
|
||||||
|
|
||||||
<procedure>
|
<procedure>
|
||||||
@ -733,9 +736,9 @@ fvwm
|
|||||||
<para>You can use the <link linkend="rcl.search.complex">
|
<para>You can use the <link linkend="rcl.search.complex">
|
||||||
<guilabel>Tools</guilabel> / <guilabel>Advanced search</guilabel>
|
<guilabel>Tools</guilabel> / <guilabel>Advanced search</guilabel>
|
||||||
</link> dialog for more complex searches.</para>
|
</link> dialog for more complex searches.</para>
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="rcl.search.reslist">
|
<sect2 id="rcl.search.reslist">
|
||||||
<title>The result list</title>
|
<title>The result list</title>
|
||||||
|
|
||||||
<para>After starting a search, a list of results will instantly
|
<para>After starting a search, a list of results will instantly
|
||||||
@ -797,7 +800,7 @@ fvwm
|
|||||||
results.</para>
|
results.</para>
|
||||||
|
|
||||||
|
|
||||||
<sect2 id="rcl.search.resultlist.menu">
|
<sect3 id="rcl.search.resultlist.menu">
|
||||||
<title>The result list right-click menu</title>
|
<title>The result list right-click menu</title>
|
||||||
|
|
||||||
<para>Apart from the preview and edit links, you can display a
|
<para>Apart from the preview and edit links, you can display a
|
||||||
@ -851,10 +854,10 @@ fvwm
|
|||||||
exemple to start a chm viewer on the parent document for a help
|
exemple to start a chm viewer on the parent document for a help
|
||||||
page.</para>
|
page.</para>
|
||||||
|
|
||||||
</sect2>
|
</sect3>
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="rcl.search.preview">
|
<sect2 id="rcl.search.preview">
|
||||||
<title>The preview window</title>
|
<title>The preview window</title>
|
||||||
|
|
||||||
<para>The preview window opens when you first click a
|
<para>The preview window opens when you first click a
|
||||||
@ -908,203 +911,15 @@ fvwm
|
|||||||
<keycap>^P</keycap> (<keycap>Ctrl</keycap> + <keycap>P</keycap>) in
|
<keycap>^P</keycap> (<keycap>Ctrl</keycap> + <keycap>P</keycap>) in
|
||||||
the window text.</para>
|
the window text.</para>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
|
|
||||||
</sect1>
|
<sect2 id="rcl.search.complex">
|
||||||
|
|
||||||
<sect1 id="rcl.search.lang">
|
|
||||||
<title>The query language</title>
|
|
||||||
|
|
||||||
<para>The query language processor is activated on the
|
|
||||||
simple search entry when the search mode selector is set to
|
|
||||||
<guilabel>Query Language</guilabel>.</para>
|
|
||||||
|
|
||||||
<para>The language is roughly based on the <ulink
|
|
||||||
url="http://www.xesam.org/main/XesamUserSearchLanguage95">
|
|
||||||
Xesam</ulink> user search language specification.</para>
|
|
||||||
|
|
||||||
<para>Here follows a sample request that we are going to
|
|
||||||
explain:</para>
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
<para>This would search for all documents with
|
|
||||||
<replaceable>John Doe</replaceable>
|
|
||||||
appearing as a phrase in the author field (exactly what this is
|
|
||||||
would depend on the document type, ie: the
|
|
||||||
<literal>From:</literal> header, for an email message),
|
|
||||||
and containing either <replaceable>beatles</replaceable> or
|
|
||||||
<replaceable>lennon</replaceable> and either
|
|
||||||
<replaceable>live</replaceable> or
|
|
||||||
<replaceable>unplugged</replaceable> but not
|
|
||||||
<replaceable>potatoes</replaceable> (in any part of the document).</para>
|
|
||||||
|
|
||||||
<para>An element is composed of an optional field specification,
|
|
||||||
and a value, separated by a colon. Exemple:
|
|
||||||
<replaceable>Beatles</replaceable>,
|
|
||||||
<replaceable>author:balzac</replaceable>,
|
|
||||||
<replaceable>dc:title:grandet</replaceable> </para>
|
|
||||||
|
|
||||||
<para>The colon, if present, means "contains". Xesam defines other
|
|
||||||
relations, which are not supported for now.</para>
|
|
||||||
|
|
||||||
<para>All elements in the search entry are normally combined
|
|
||||||
with an implicit AND. It is possible to specify that elements be
|
|
||||||
OR'ed instead, as in <replaceable>Beatles</replaceable>
|
|
||||||
<literal>OR</literal> <replaceable>Lennon</replaceable>. The
|
|
||||||
<literal>OR</literal> must be entered literally (capitals), and
|
|
||||||
it has priority over the AND associations:
|
|
||||||
<replaceable>word1</replaceable>
|
|
||||||
<replaceable>word2</replaceable> <literal>OR</literal>
|
|
||||||
<replaceable>word3</replaceable>
|
|
||||||
means
|
|
||||||
<replaceable>word1</replaceable> AND
|
|
||||||
(<replaceable>word2</replaceable> <literal>OR</literal>
|
|
||||||
<replaceable>word3</replaceable>)
|
|
||||||
not
|
|
||||||
(<replaceable>word1</replaceable> AND
|
|
||||||
<replaceable>word2</replaceable>) <literal>OR</literal>
|
|
||||||
<replaceable>word3</replaceable>. Do not enter explicit
|
|
||||||
parenthesis, they are not supported for now.</para>
|
|
||||||
|
|
||||||
<para>An element preceded by a <literal>-</literal> specifies a
|
|
||||||
term that should <emphasis>not</emphasis> appear. Pure negative
|
|
||||||
queries are forbidden.</para>
|
|
||||||
|
|
||||||
<para>As usual, words inside quotes define a phrase
|
|
||||||
(the order of words is significant), so that
|
|
||||||
<replaceable>title:"prejudice pride"</replaceable> is not the same as
|
|
||||||
<replaceable>title:prejudice title:pride</replaceable>, and is
|
|
||||||
unlikely to find a result.</para>
|
|
||||||
|
|
||||||
<para>&RCL; currently manages the following default fields:</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem><para><literal>title</literal>,
|
|
||||||
<literal>subject</literal> or <literal>caption</literal> are
|
|
||||||
synonyms which specify data to be searched for in the
|
|
||||||
document title or subject.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>author</literal> or
|
|
||||||
<literal>from</literal> for searching the documents originators.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>recipient</literal> or
|
|
||||||
<literal>to</literal> for searching the documents recipients.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>keyword</literal> for searching the
|
|
||||||
document-specified keywords (few documents actually have any).</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>filename</literal> for the document's
|
|
||||||
file name.</listitem>
|
|
||||||
<listitem><para><literal>ext</literal> specifies the file
|
|
||||||
name extension (Ex: <literal>ext:html</literal>)</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<para>The field syntax also supports a few field-like, but
|
|
||||||
special, criteria:</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem><para><literal>dir</literal> for filtering the
|
|
||||||
results on file location (Ex:
|
|
||||||
<literal>dir:/home/me/somedir</literal>). Please note
|
|
||||||
that this is quite inefficient, that it may produce very
|
|
||||||
slow searches, and that it may be worth in some
|
|
||||||
cases to set up separate databases instead.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem><para><literal>date</literal> for searching or filtering
|
|
||||||
on dates. The syntax for the argument is based on the ISO8601
|
|
||||||
standard for dates and time intervals. Only dates are supported, no
|
|
||||||
times. The general syntax is 2 elements separated by a
|
|
||||||
<literal>/</literal> character. Each element can be a date or a
|
|
||||||
period of time. Periods are specified as
|
|
||||||
<literal>P</literal><replaceable>n</replaceable><literal>Y</literal><replaceable>n</replaceable><literal>M</literal><replaceable>n</replaceable><literal>D</literal>.
|
|
||||||
The <replaceable>n</replaceable> numbers are the respective numbers
|
|
||||||
of years, months or days, any of which may be missing. Dates are
|
|
||||||
specified as
|
|
||||||
<replaceable>YYYY</replaceable>-<replaceable>MM</replaceable>-<replaceable>DD</replaceable>.
|
|
||||||
The days and months parts may be missing. If the
|
|
||||||
<literal>/</literal> is present but an element is missing, the
|
|
||||||
missing element is interpreted as the lowest or highest date in the
|
|
||||||
index. Exemples:</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem><para><literal>2001-03-01/2002-05-01</literal> the
|
|
||||||
basic syntax for an interval of dates.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>2001-03-01/P1Y2M</literal> the
|
|
||||||
same specified with a period.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>2001/</literal> from the beginning of
|
|
||||||
2001 to the latest date in the index.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>2001</literal> the whole year of
|
|
||||||
2001</para></listitem>
|
|
||||||
<listitem><para><literal>P2D/</literal> means 2 days ago up to
|
|
||||||
now if there are no documents with dates in the future.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>/2003</literal> all documents from
|
|
||||||
2003 or older.</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
<para>Periods can also be specified with small letters (ie:
|
|
||||||
p2y).</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem><para><literal>mime</literal> or
|
|
||||||
<literal>format</literal> for specifying the
|
|
||||||
mime type. This one is quite special because you can specify
|
|
||||||
several values which will be OR'ed (the normal default for the
|
|
||||||
language is AND). Ex: <literal>mime:text/plain
|
|
||||||
mime:text/html</literal>. Specifying an explicit boolean
|
|
||||||
operator or negation (<literal>-</literal>) before a
|
|
||||||
<literal>mime</literal> specification is not supported and
|
|
||||||
will produce strange results.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem><para><literal>type</literal> or
|
|
||||||
<literal>rclcat</literal> for specifying the category (as in
|
|
||||||
text/media/presentation/etc.). The classification of mime
|
|
||||||
types in categories is defined in the &RCL; configuration
|
|
||||||
(<filename>mimeconf</filename>), and can be modified or
|
|
||||||
extended. The default category names are those which permit
|
|
||||||
filtering results in the main GUI screen. Categories are OR'ed
|
|
||||||
like mime types above.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<para>The document filters used while indexing have the
|
|
||||||
possibility to create other fields with arbitrary names, and
|
|
||||||
aliases may be defined in the configuration, so that the exact
|
|
||||||
field search possibilities may be different for you if someone
|
|
||||||
took care of the customisation.</para>
|
|
||||||
|
|
||||||
<para>The query language is currently the only way to use the
|
|
||||||
&RCL; field search capability.</para>
|
|
||||||
|
|
||||||
<para>Words inside phrases and capitalized words are not
|
|
||||||
stem-expanded. Wildcards may be used anywhere inside a term.
|
|
||||||
Specifying a wild-card on the left of a term can produce a very
|
|
||||||
slow search (or even an incorrect one if the expansion is
|
|
||||||
truncated because of excessive size).</para>
|
|
||||||
|
|
||||||
<para>You can use the <literal>show query</literal> link at the
|
|
||||||
top of the result list to check the exact query which was
|
|
||||||
finally executed by Xapian.</para>
|
|
||||||
|
|
||||||
<para>Most Xesam phrase modifiers are unsupported, except for
|
|
||||||
<literal>l</literal> (small ell) to disable stemming, and
|
|
||||||
<literal>p</literal> to turn a phrase into a NEAR (unordered)
|
|
||||||
search. Exemple: <replaceable>"prejudice pride"p</replaceable></para>
|
|
||||||
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="rcl.search.complex">
|
|
||||||
<title>Complex/advanced search</title>
|
<title>Complex/advanced search</title>
|
||||||
|
|
||||||
<para>The advanced search dialog helps you build more complex
|
<para>The advanced search dialog helps you build more complex queries
|
||||||
queries. It can be opened through the <guilabel>Tools</guilabel>
|
without memorizing the search language constructs. It can be opened
|
||||||
menu or through the main toolbar.</para>
|
through the <guilabel>Tools</guilabel> menu or through the main
|
||||||
|
toolbar.</para>
|
||||||
|
|
||||||
<para>The dialog has three parts:</para>
|
<para>The dialog has three parts:</para>
|
||||||
|
|
||||||
@ -1186,9 +1001,9 @@ fvwm
|
|||||||
<para>Click on the <literal>Show query details</literal> link at
|
<para>Click on the <literal>Show query details</literal> link at
|
||||||
the top of the result page to see the query expansion.</para>
|
the top of the result page to see the query expansion.</para>
|
||||||
|
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="rcl.search.termexplorer">
|
<sect2 id="rcl.search.termexplorer">
|
||||||
<title>The term explorer tool</title>
|
<title>The term explorer tool</title>
|
||||||
|
|
||||||
<para>&RCL; automatically manages the expansion of search terms
|
<para>&RCL; automatically manages the expansion of search terms
|
||||||
@ -1265,57 +1080,9 @@ fvwm
|
|||||||
between the result list and any entry field (the end of lines
|
between the result list and any entry field (the end of lines
|
||||||
will be taken care of).</para>
|
will be taken care of).</para>
|
||||||
|
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="rcl.search.wildcards">
|
<sect2 id="rcl.search.multidb">
|
||||||
<title>More about wildcards</title>
|
|
||||||
|
|
||||||
<para>All words entered in &RCL; search fields will be processed
|
|
||||||
for wildcard expansion before the request is finally
|
|
||||||
executed.</para>
|
|
||||||
|
|
||||||
<para>The wildcard characters are:</para>
|
|
||||||
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem><para><literal>*</literal> which matches 0 or more
|
|
||||||
characters.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>?</literal> which matches
|
|
||||||
a single character.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para><literal>[]</literal> which allow
|
|
||||||
defining sets of characters to be matched (ex:
|
|
||||||
<literal>[</literal><userinput>abc</userinput><literal>]</literal>
|
|
||||||
matches a single character which may be 'a' or 'b' or 'c',
|
|
||||||
<literal>[</literal><userinput>0-9</userinput><literal>]</literal>
|
|
||||||
matches any number.</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<para>You should be aware of a few things before using
|
|
||||||
wildcards.</para>
|
|
||||||
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem><para>Using a wildcard character at the beginning of
|
|
||||||
a word can make for a slow search because &RCL; will have to
|
|
||||||
scan the whole index term list to find the matches.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem><para>Using a <literal>*</literal> at the end of a
|
|
||||||
word can produce more matches than you would think, and
|
|
||||||
strange search results. You can use the <link
|
|
||||||
linkend="rcl.search.termexplorer">term explorer</link> tool to
|
|
||||||
check what completions exist for a given term. You can also
|
|
||||||
see exactly what search was performed by clicking on the link
|
|
||||||
at the top of the result list. In general, for natural
|
|
||||||
language terms, stem expansion will produce better results
|
|
||||||
than an ending <literal>*</literal> (stem expansion is turned
|
|
||||||
off when any wildcard character appears in the term).</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="rcl.search.multidb">
|
|
||||||
<title>Multiple databases</title>
|
<title>Multiple databases</title>
|
||||||
|
|
||||||
<para>Multiple &RCL; databases or indexes can be created by
|
<para>Multiple &RCL; databases or indexes can be created by
|
||||||
@ -1370,9 +1137,9 @@ fvwm
|
|||||||
multiple indexes will have much better performance and may be
|
multiple indexes will have much better performance and may be
|
||||||
worth the trouble.</para>
|
worth the trouble.</para>
|
||||||
|
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="rcl.search.history">
|
<sect2 id="rcl.search.history">
|
||||||
<title>Document history</title>
|
<title>Document history</title>
|
||||||
|
|
||||||
<para>Documents that you actually view (with the internal preview
|
<para>Documents that you actually view (with the internal preview
|
||||||
@ -1385,9 +1152,9 @@ fvwm
|
|||||||
<guilabel>Erase document history</guilabel> entry in the
|
<guilabel>Erase document history</guilabel> entry in the
|
||||||
<guimenu>File</guimenu> menu.
|
<guimenu>File</guimenu> menu.
|
||||||
|
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="rcl.search.sort">
|
<sect2 id="rcl.search.sort">
|
||||||
<title>Sorting search results and collapsing duplicates</title>
|
<title>Sorting search results and collapsing duplicates</title>
|
||||||
|
|
||||||
<para>The documents in a result list are normally sorted in
|
<para>The documents in a result list are normally sorted in
|
||||||
@ -1421,13 +1188,12 @@ fvwm
|
|||||||
by an entry in the <guilabel>Query configuration</guilabel>
|
by an entry in the <guilabel>Query configuration</guilabel>
|
||||||
dialog, and is off by default.</para>
|
dialog, and is off by default.</para>
|
||||||
|
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 id="rcl.search.tips">
|
||||||
<sect1 id="rcl.search.tips">
|
|
||||||
<title>Search tips, shortcuts</title>
|
<title>Search tips, shortcuts</title>
|
||||||
|
|
||||||
<sect2 id="rcl.search.tips.terms">
|
<sect3 id="rcl.search.tips.terms">
|
||||||
<title>Terms and search expansion</title>
|
<title>Terms and search expansion</title>
|
||||||
|
|
||||||
<formalpara><title>Term completion</title>
|
<formalpara><title>Term completion</title>
|
||||||
@ -1489,10 +1255,10 @@ fvwm
|
|||||||
faster than the generic search especially when using wildcards.</para>
|
faster than the generic search especially when using wildcards.</para>
|
||||||
</formalpara>
|
</formalpara>
|
||||||
|
|
||||||
</sect2>
|
</sect3>
|
||||||
|
|
||||||
|
|
||||||
<sect2 id="rcl.search.tips.phrases">
|
<sect3 id="rcl.search.tips.phrases">
|
||||||
<title>Working with phrases and proximity</title>
|
<title>Working with phrases and proximity</title>
|
||||||
|
|
||||||
<formalpara><title>Phrases and Proximity searches</title>
|
<formalpara><title>Phrases and Proximity searches</title>
|
||||||
@ -1518,12 +1284,11 @@ fvwm
|
|||||||
both appear, but those which contain <literal>virtual
|
both appear, but those which contain <literal>virtual
|
||||||
reality</literal> should appear sooner in the list.</para>
|
reality</literal> should appear sooner in the list.</para>
|
||||||
|
|
||||||
</sect2>
|
</sect3>
|
||||||
|
|
||||||
<sect2 id="rcl.search.tips.misc">
|
<sect3 id="rcl.search.tips.misc">
|
||||||
<title>Others</title>
|
<title>Others</title>
|
||||||
|
|
||||||
|
|
||||||
<formalpara><title>Using fields</title>
|
<formalpara><title>Using fields</title>
|
||||||
<para>You can use the <link linkend="rcl.search.lang">query
|
<para>You can use the <link linkend="rcl.search.lang">query
|
||||||
language </link> and field specifications
|
language </link> and field specifications
|
||||||
@ -1578,10 +1343,10 @@ fvwm
|
|||||||
<para>Entering <keycap>^Q</keycap> almost anywhere will
|
<para>Entering <keycap>^Q</keycap> almost anywhere will
|
||||||
close the application.</para>
|
close the application.</para>
|
||||||
</formalpara>
|
</formalpara>
|
||||||
</sect2>
|
</sect3>
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
<sect1 id="rcl.search.custom">
|
<sect2 id="rcl.search.custom">
|
||||||
<title>Customizing the search interface</title>
|
<title>Customizing the search interface</title>
|
||||||
|
|
||||||
<para>You can customize some aspects of the search interface by using
|
<para>You can customize some aspects of the search interface by using
|
||||||
@ -1767,7 +1532,7 @@ fvwm
|
|||||||
need to implement a way of purging the index from stale data,
|
need to implement a way of purging the index from stale data,
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<sect2 id="rcl.search.custom.reslistpara">
|
<sect3 id="rcl.search.custom.reslistpara">
|
||||||
<title>The result list paragraph format</title>
|
<title>The result list paragraph format</title>
|
||||||
|
|
||||||
<para>The presentation of each result inside the result list can be
|
<para>The presentation of each result inside the result list can be
|
||||||
@ -1863,15 +1628,15 @@ fvwm
|
|||||||
one.</para>
|
one.</para>
|
||||||
|
|
||||||
|
|
||||||
</sect2>
|
</sect3>
|
||||||
</sect1>
|
</sect2>
|
||||||
|
|
||||||
</chapter>
|
</sect1> <!-- search GUI -->
|
||||||
|
|
||||||
<chapter id="rcl.searchkio">
|
<sect1 id="rcl.searchkio">
|
||||||
<title>Searching with the KDE KIO slave</title>
|
<title>Searching with the KDE KIO slave</title>
|
||||||
|
|
||||||
<sect1 id="rcl.searchkio.intro">
|
<sect2 id="rcl.searchkio.intro">
|
||||||
<title>What's this</title>
|
<title>What's this</title>
|
||||||
|
|
||||||
<para>The &RCL; KIO slave allows performing a &RCL; search
|
<para>The &RCL; KIO slave allows performing a &RCL; search
|
||||||
@ -1897,14 +1662,16 @@ fvwm
|
|||||||
recoll KIO slave has been previously installed).</para>
|
recoll KIO slave has been previously installed).</para>
|
||||||
|
|
||||||
|
|
||||||
<para>The instructions for building this module are located in
|
<para>The instructions for building this module are located in the
|
||||||
the source tree. See:
|
source tree. See:
|
||||||
<filename>kde/kio/recoll/00README.txt</filename></para>
|
<filename>kde/kio/recoll/00README.txt</filename>. Some Linux
|
||||||
</sect1>
|
distributions do package the kio-recoll module, so check before
|
||||||
|
diving into the build process, maybe it's already out there ready for
|
||||||
|
one-click installation.</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
|
||||||
|
<sect2 id="rcl.searchkio.searchabledocs">
|
||||||
<sect1 id="rcl.searchkio.searchabledocs">
|
|
||||||
<title>Searchable documents</title>
|
<title>Searchable documents</title>
|
||||||
|
|
||||||
<para>As a sample application, the &RCL; KIO slave could allow
|
<para>As a sample application, the &RCL; KIO slave could allow
|
||||||
@ -1930,14 +1697,11 @@ fvwm
|
|||||||
<body ondblclick="recollsearch()">
|
<body ondblclick="recollsearch()">
|
||||||
|
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
|
<sect1 id="rcl.search.commandline">
|
||||||
|
|
||||||
<chapter id="rcl.searchkcl">
|
|
||||||
<title>Searching on the command line</title>
|
<title>Searching on the command line</title>
|
||||||
|
|
||||||
<para>There are several ways to obtain search results as a text
|
<para>There are several ways to obtain search results as a text
|
||||||
@ -1962,8 +1726,8 @@ fvwm
|
|||||||
<para><command>recollq</command> is not built by default. You can
|
<para><command>recollq</command> is not built by default. You can
|
||||||
use the <filename>Makefile</filename> in the
|
use the <filename>Makefile</filename> in the
|
||||||
<filename>query</filename> directory to build it. This is a very
|
<filename>query</filename> directory to build it. This is a very
|
||||||
simple program, and it will often be useful to taylor its output format
|
simple program, and if you can program a little c++, you may find it
|
||||||
to your needs.</para>
|
useful to taylor its output format to your needs.</para>
|
||||||
|
|
||||||
<para><command>recollq</command> has a man page (not installed by
|
<para><command>recollq</command> has a man page (not installed by
|
||||||
default, look in the <filename>doc/man</filename> directory). The
|
default, look in the <filename>doc/man</filename> directory). The
|
||||||
@ -1994,8 +1758,299 @@ text/html [file:///Users/uncrypted-dockes/projets/nautique/webnautique/art
|
|||||||
text/html [file:///Users/uncrypted-dockes/projets/pagepers/index.html] [psxtcl/writemime/recoll]...
|
text/html [file:///Users/uncrypted-dockes/projets/pagepers/index.html] [psxtcl/writemime/recoll]...
|
||||||
text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/recu-chasse-maree....
|
text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/recu-chasse-maree....
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
</chapter>
|
<sect1 id="rcl.search.lang">
|
||||||
|
<title>The query language</title>
|
||||||
|
|
||||||
|
<para>The query language processor is activated in the GUI
|
||||||
|
simple search entry when the search mode selector is set to
|
||||||
|
<guilabel>Query Language</guilabel>. It can also be used with the KIO
|
||||||
|
slave or the command line search. It broadly has the same
|
||||||
|
capabilities as the complex search interface in the
|
||||||
|
GUI. Additionally, the query language is for now the only way to
|
||||||
|
access the important &RCL; field search capabilities.</para>
|
||||||
|
|
||||||
|
<para>The language is roughly based on the <ulink
|
||||||
|
url="http://www.xesam.org/main/XesamUserSearchLanguage95">
|
||||||
|
Xesam</ulink> user search language specification.</para>
|
||||||
|
|
||||||
|
<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
|
||||||
|
<literal>show query</literal> link at the top of the result list to
|
||||||
|
check the exact query which was finally executed by Xapian.</para>
|
||||||
|
|
||||||
|
<para>Here follows a sample request that we are going to
|
||||||
|
explain:</para>
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<para>This would search for all documents with
|
||||||
|
<replaceable>John Doe</replaceable>
|
||||||
|
appearing as a phrase in the author field (exactly what this is
|
||||||
|
would depend on the document type, ie: the
|
||||||
|
<literal>From:</literal> header, for an email message),
|
||||||
|
and containing either <replaceable>beatles</replaceable> or
|
||||||
|
<replaceable>lennon</replaceable> and either
|
||||||
|
<replaceable>live</replaceable> or
|
||||||
|
<replaceable>unplugged</replaceable> but not
|
||||||
|
<replaceable>potatoes</replaceable> (in any part of the document).</para>
|
||||||
|
|
||||||
|
<para>An element is composed of an optional field specification,
|
||||||
|
and a value, separated by a colon. Exemple:
|
||||||
|
<replaceable>Beatles</replaceable>,
|
||||||
|
<replaceable>author:balzac</replaceable>,
|
||||||
|
<replaceable>dc:title:grandet</replaceable> </para>
|
||||||
|
|
||||||
|
<para>The colon, if present, means "contains". Xesam defines other
|
||||||
|
relations, which are not supported for now.</para>
|
||||||
|
|
||||||
|
<para>All elements in the search entry are normally combined
|
||||||
|
with an implicit AND. It is possible to specify that elements be
|
||||||
|
OR'ed instead, as in <replaceable>Beatles</replaceable>
|
||||||
|
<literal>OR</literal> <replaceable>Lennon</replaceable>. The
|
||||||
|
<literal>OR</literal> must be entered literally (capitals), and
|
||||||
|
it has priority over the AND associations:
|
||||||
|
<replaceable>word1</replaceable>
|
||||||
|
<replaceable>word2</replaceable> <literal>OR</literal>
|
||||||
|
<replaceable>word3</replaceable>
|
||||||
|
means
|
||||||
|
<replaceable>word1</replaceable> AND
|
||||||
|
(<replaceable>word2</replaceable> <literal>OR</literal>
|
||||||
|
<replaceable>word3</replaceable>)
|
||||||
|
not
|
||||||
|
(<replaceable>word1</replaceable> AND
|
||||||
|
<replaceable>word2</replaceable>) <literal>OR</literal>
|
||||||
|
<replaceable>word3</replaceable>. Do not enter explicit
|
||||||
|
parenthesis, they are not supported for now.</para>
|
||||||
|
|
||||||
|
<para>An element preceded by a <literal>-</literal> specifies a
|
||||||
|
term that should <emphasis>not</emphasis> appear. Pure negative
|
||||||
|
queries are forbidden.</para>
|
||||||
|
|
||||||
|
<para>As usual, words inside quotes define a phrase
|
||||||
|
(the order of words is significant), so that
|
||||||
|
<replaceable>title:"prejudice pride"</replaceable> is not the same as
|
||||||
|
<replaceable>title:prejudice title:pride</replaceable>, and is
|
||||||
|
unlikely to find a result.</para>
|
||||||
|
<para>Most Xesam phrase modifiers are unsupported, except for
|
||||||
|
<literal>l</literal> (small ell) to disable stemming, and
|
||||||
|
<literal>p</literal> to turn a phrase into a NEAR (unordered proximity)
|
||||||
|
search. Exemple: <replaceable>"prejudice pride"p</replaceable></para>
|
||||||
|
|
||||||
|
<para>&RCL; currently manages the following default fields:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para><literal>title</literal>,
|
||||||
|
<literal>subject</literal> or <literal>caption</literal> are
|
||||||
|
synonyms which specify data to be searched for in the
|
||||||
|
document title or subject.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>author</literal> or
|
||||||
|
<literal>from</literal> for searching the documents originators.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>recipient</literal> or
|
||||||
|
<literal>to</literal> for searching the documents recipients.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>keyword</literal> for searching the
|
||||||
|
document-specified keywords (few documents actually have any).</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>filename</literal> for the document's
|
||||||
|
file name.</listitem>
|
||||||
|
<listitem><para><literal>ext</literal> specifies the file
|
||||||
|
name extension (Ex: <literal>ext:html</literal>)</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>The field syntax also supports a few field-like, but
|
||||||
|
special, criteria:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para><literal>dir</literal> for filtering the
|
||||||
|
results on file location (Ex:
|
||||||
|
<literal>dir:/home/me/somedir</literal>). Please note
|
||||||
|
that this is quite inefficient, that it may produce very
|
||||||
|
slow searches, and that it may be worth in some
|
||||||
|
cases to set up separate databases instead.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem><para><literal>date</literal> for searching or filtering
|
||||||
|
on dates. The syntax for the argument is based on the ISO8601
|
||||||
|
standard for dates and time intervals. Only dates are supported, no
|
||||||
|
times. The general syntax is 2 elements separated by a
|
||||||
|
<literal>/</literal> character. Each element can be a date or a
|
||||||
|
period of time. Periods are specified as
|
||||||
|
<literal>P</literal><replaceable>n</replaceable><literal>Y</literal><replaceable>n</replaceable><literal>M</literal><replaceable>n</replaceable><literal>D</literal>.
|
||||||
|
The <replaceable>n</replaceable> numbers are the respective numbers
|
||||||
|
of years, months or days, any of which may be missing. Dates are
|
||||||
|
specified as
|
||||||
|
<replaceable>YYYY</replaceable>-<replaceable>MM</replaceable>-<replaceable>DD</replaceable>.
|
||||||
|
The days and months parts may be missing. If the
|
||||||
|
<literal>/</literal> is present but an element is missing, the
|
||||||
|
missing element is interpreted as the lowest or highest date in the
|
||||||
|
index. Exemples:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para><literal>2001-03-01/2002-05-01</literal> the
|
||||||
|
basic syntax for an interval of dates.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>2001-03-01/P1Y2M</literal> the
|
||||||
|
same specified with a period.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>2001/</literal> from the beginning of
|
||||||
|
2001 to the latest date in the index.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>2001</literal> the whole year of
|
||||||
|
2001</para></listitem>
|
||||||
|
<listitem><para><literal>P2D/</literal> means 2 days ago up to
|
||||||
|
now if there are no documents with dates in the future.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>/2003</literal> all documents from
|
||||||
|
2003 or older.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
<para>Periods can also be specified with small letters (ie:
|
||||||
|
p2y).</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem><para><literal>mime</literal> or
|
||||||
|
<literal>format</literal> for specifying the
|
||||||
|
mime type. This one is quite special because you can specify
|
||||||
|
several values which will be OR'ed (the normal default for the
|
||||||
|
language is AND). Ex: <literal>mime:text/plain
|
||||||
|
mime:text/html</literal>. Specifying an explicit boolean
|
||||||
|
operator or negation (<literal>-</literal>) before a
|
||||||
|
<literal>mime</literal> specification is not supported and
|
||||||
|
will produce strange results. Note that <literal>mime</literal> is
|
||||||
|
the ONLY field with an OR default. You do need to use
|
||||||
|
<literal>OR</literal> with <literal>ext</literal> terms for
|
||||||
|
example.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem><para><literal>type</literal> or
|
||||||
|
<literal>rclcat</literal> for specifying the category (as in
|
||||||
|
text/media/presentation/etc.). The classification of mime
|
||||||
|
types in categories is defined in the &RCL; configuration
|
||||||
|
(<filename>mimeconf</filename>), and can be modified or
|
||||||
|
extended. The default category names are those which permit
|
||||||
|
filtering results in the main GUI screen. Categories are OR'ed
|
||||||
|
like mime types above.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>Words inside phrases and capitalized words are not
|
||||||
|
stem-expanded. Wildcards may be used anywhere inside a term.
|
||||||
|
Specifying a wild-card on the left of a term can produce a very
|
||||||
|
slow search (or even an incorrect one if the expansion is
|
||||||
|
truncated because of excessive size). Also see <link
|
||||||
|
linkend="rcl.search.wildcards">More about wildcards</link>.</para>
|
||||||
|
|
||||||
|
<para>The document filters used while indexing have the
|
||||||
|
possibility to create other fields with arbitrary names, and
|
||||||
|
aliases may be defined in the configuration, so that the exact
|
||||||
|
field search possibilities may be different for you if someone
|
||||||
|
took care of the customisation.</para>
|
||||||
|
|
||||||
|
<sect2 id="rcl.search.wildcards">
|
||||||
|
<title>More about wildcards</title>
|
||||||
|
|
||||||
|
<para>All words entered in &RCL; search fields will be processed
|
||||||
|
for wildcard expansion before the request is finally
|
||||||
|
executed.</para>
|
||||||
|
|
||||||
|
<para>The wildcard characters are:</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para><literal>*</literal> which matches 0 or more
|
||||||
|
characters.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>?</literal> which matches
|
||||||
|
a single character.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para><literal>[]</literal> which allow
|
||||||
|
defining sets of characters to be matched (ex:
|
||||||
|
<literal>[</literal><userinput>abc</userinput><literal>]</literal>
|
||||||
|
matches a single character which may be 'a' or 'b' or 'c',
|
||||||
|
<literal>[</literal><userinput>0-9</userinput><literal>]</literal>
|
||||||
|
matches any number.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>You should be aware of a few things before using
|
||||||
|
wildcards.</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>Using a wildcard character at the beginning of
|
||||||
|
a word can make for a slow search because &RCL; will have to
|
||||||
|
scan the whole index term list to find the matches.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para>Using a <literal>*</literal> at the end of a
|
||||||
|
word can produce more matches than you would think, and
|
||||||
|
strange search results. You can use the <link
|
||||||
|
linkend="rcl.search.termexplorer">term explorer</link> tool to
|
||||||
|
check what completions exist for a given term. You can also
|
||||||
|
see exactly what search was performed by clicking on the link
|
||||||
|
at the top of the result list. In general, for natural
|
||||||
|
language terms, stem expansion will produce better results
|
||||||
|
than an ending <literal>*</literal> (stem expansion is turned
|
||||||
|
off when any wildcard character appears in the term).</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
</sect1> <!-- rcl.search.lang -->
|
||||||
|
|
||||||
|
<sect1 id="rcl.search.desktop">
|
||||||
|
<title>Desktop integration</title>
|
||||||
|
|
||||||
|
<para>Being independant of the desktop type has its drawbacks: &RCL;
|
||||||
|
desktop integration is minimal. Here follow a few things that may
|
||||||
|
help.</para>
|
||||||
|
|
||||||
|
<sect2 id="rcl.search.shortcut">
|
||||||
|
<title>Hotkeying recoll</title>
|
||||||
|
|
||||||
|
<para>It is surprisingly convenient to be able to show or hide the
|
||||||
|
&RCL; GUI with a single keystroke. Recoll comes with a small
|
||||||
|
python script, based on the <literal>libwnck</literal> window manager
|
||||||
|
interface library, which will allow you to do just this. The detailed
|
||||||
|
instructions are on
|
||||||
|
<ulink url="http://bitbucket.org/medoc/recoll/wiki/HotRecoll">
|
||||||
|
this wiki page</ulink>.</para>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 id="rcl.kicker-applet">
|
||||||
|
<title>The KDE Kicker Recoll applet</title>
|
||||||
|
|
||||||
|
<para>The &RCL; source tree contains the source code to the
|
||||||
|
<literal>recoll_applet</literal>, a small application derived
|
||||||
|
from the <literal>find_applet</literal>. This can be used to
|
||||||
|
add a small &RCL; launcher to the KDE panel.</para>
|
||||||
|
|
||||||
|
<para>The applet is not automatically built with the main &RCL;
|
||||||
|
programs, nor is it included with the main source distribution
|
||||||
|
(because the KDE build boilerplate makes it relatively big). You can
|
||||||
|
download its source from the recoll.org download page. Use the
|
||||||
|
omnipotent <userinput>configure;make;make install</userinput>
|
||||||
|
incantation to build and install.</para>
|
||||||
|
|
||||||
|
<para>You can then add the applet to the panel by right-clicking the
|
||||||
|
panel and choosing the <guilabel>Add applet</guilabel> entry.</para>
|
||||||
|
|
||||||
|
<para>The <literal>recoll_applet</literal> has a small text window
|
||||||
|
where you can type a &RCL; query (in query language form), and an
|
||||||
|
icon which can be used to restrict the search to certain types of
|
||||||
|
files. It is quite primitive, and launches a new recoll GUI instance
|
||||||
|
every time (even if it is already running). You may find it useful
|
||||||
|
anyway.</para>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
</sect1> <!-- rcl.search.desktop -->
|
||||||
|
|
||||||
|
</chapter> <!-- Search -->
|
||||||
|
|
||||||
<chapter id="rcl.program">
|
<chapter id="rcl.program">
|
||||||
<title>Programming interface</title>
|
<title>Programming interface</title>
|
||||||
@ -2544,7 +2599,7 @@ while query.next >= 0 and query.next < nres:
|
|||||||
|
|
||||||
|
|
||||||
<chapter id="rcl.install">
|
<chapter id="rcl.install">
|
||||||
<title>Installation</title>
|
<title>Installation and configuration</title>
|
||||||
|
|
||||||
<sect1 id="rcl.install.binary">
|
<sect1 id="rcl.install.binary">
|
||||||
<title>Installing a binary copy</title>
|
<title>Installing a binary copy</title>
|
||||||
@ -3751,33 +3806,6 @@ application/x-blobapp = exec rclblob
|
|||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="rcl.kicker-applet">
|
|
||||||
<title>The KDE Kicker Recoll applet</title>
|
|
||||||
|
|
||||||
<para>The &RCL; source tree contains the source code to the
|
|
||||||
<literal>recoll_applet</literal>, a small application derived
|
|
||||||
from the <literal>find_applet</literal>. This can be used to
|
|
||||||
add a small &RCL; launcher to the KDE panel.</para>
|
|
||||||
|
|
||||||
<para>The applet is not automatically built with the main &RCL;
|
|
||||||
programs, nor is it included with the main source distribution
|
|
||||||
(because the KDE build boilerplate makes it relatively big). You
|
|
||||||
can download its source from the recoll.org download page. Use
|
|
||||||
the omnipotent <userinput>configure;make;make
|
|
||||||
install</userinput> incantation to build and install.</para>
|
|
||||||
|
|
||||||
<para>You can then add the applet to the panel by right-clicking
|
|
||||||
the panel and choosing the <guilabel>Add applet</guilabel>
|
|
||||||
entry.</para>
|
|
||||||
|
|
||||||
<para>The <literal>recoll_applet</literal> has a small text
|
|
||||||
window where you can type a &RCL; query (in query language
|
|
||||||
form), and an icon which can be used to restrict the search to
|
|
||||||
certain types of files. It is quite primitive, and launches a
|
|
||||||
new recoll GUI instance every time (even if it is already
|
|
||||||
running). You may find it useful anyway.</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
</book>
|
</book>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user