--- a/src/doc/user/usermanual.sgml
+++ b/src/doc/user/usermanual.sgml
@@ -620,6 +620,9 @@
</chapter>
<chapter id="rcl.search">
+ <title>Searching</title>
+
+ <sect1 id="rcl.search.gui">
<title>Searching with the Qt graphical user interface</title>
<para>The <command>recoll</command> program provides the main user
@@ -653,7 +656,7 @@
case (they would typically be printed without white
space).</para>
- <sect1 id="rcl.search.simple">
+ <sect2 id="rcl.search.simple">
<title>Simple search</title>
<procedure>
@@ -733,9 +736,9 @@
<para>You can use the <link linkend="rcl.search.complex">
<guilabel>Tools</guilabel> / <guilabel>Advanced search</guilabel>
</link> dialog for more complex searches.</para>
- </sect1>
-
- <sect1 id="rcl.search.reslist">
+ </sect2>
+
+ <sect2 id="rcl.search.reslist">
<title>The result list</title>
<para>After starting a search, a list of results will instantly
@@ -797,7 +800,7 @@
results.</para>
- <sect2 id="rcl.search.resultlist.menu">
+ <sect3 id="rcl.search.resultlist.menu">
<title>The result list right-click menu</title>
<para>Apart from the preview and edit links, you can display a
@@ -851,10 +854,10 @@
exemple to start a chm viewer on the parent document for a help
page.</para>
- </sect2>
- </sect1>
-
- <sect1 id="rcl.search.preview">
+ </sect3>
+ </sect2>
+
+ <sect2 id="rcl.search.preview">
<title>The preview window</title>
<para>The preview window opens when you first click a
@@ -908,19 +911,874 @@
<keycap>^P</keycap> (<keycap>Ctrl</keycap> + <keycap>P</keycap>) in
the window text.</para>
-
+ </sect2>
+
+ <sect2 id="rcl.search.complex">
+ <title>Complex/advanced search</title>
+
+ <para>The advanced search dialog helps you build more complex queries
+ without memorizing the search language constructs. It can be opened
+ through the <guilabel>Tools</guilabel> menu or through the main
+ toolbar.</para>
+
+ <para>The dialog has three parts:</para>
+
+ <itemizedlist>
+ <listitem><para>The top part allows constructing a query by
+ combining multiple clauses of different types.
+ Each entry field is configurable for the following modes:</para>
+
+ <itemizedlist>
+ <listitem><para>All terms.</para>
+ </listitem>
+ <listitem><para>Any term.</para>
+ </listitem>
+ <listitem><para>None of the terms.</para>
+ </listitem>
+ <listitem><para>Phrase (exact terms in order within an
+ adjustable window).</para>
+ </listitem>
+ <listitem><para>Proximity (terms in any order within an
+ adjustable window).</para>
+ </listitem>
+ <listitem><para>Filename search.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Additional entry fields can be created by clicking the
+ <guilabel>Add clause</guilabel> button.</para>
+
+ <para>When searching, the non-empty clauses will be
+ combined either with an AND or an OR conjunction, depending on
+ the choice made on the left (<guilabel>All clauses</guilabel> or
+ <guilabel>Any clause</guilabel>).</para>
+
+ <para>Entries of all types except "Phrase" and "Near" accept
+ a mix of single words and phrases enclosed in double quotes.
+ Stemming and wildcard expansion will be performed as for simple
+ search. </para>
+ </listitem>
+
+ <listitem><para>The next part allows filtering the
+ results by their mime types.</para>
+ <para>The state of the file type selection can be saved as
+ the default (the file type filter will not be activated at
+ program start-up, but the lists will be in the restored
+ state).</para>
+ </listitem>
+
+ <listitem>
+ <para>The bottom part allows restricting the search results to a
+ sub-tree of the indexed area. If you need to do this often,
+ you may think of setting up multiple indexes instead, as the
+ performance will be much better.</para>
+ </listitem>
+
+ </itemizedlist>
+
+
+ <formalpara><title>Phrases and Proximity searches</title>
+ <para>These two clauses work in similar ways, with the
+ difference that proximity searches do not impose an order on the
+ words. In both cases, an adjustable number (slack) of non-matched words
+ may be accepted between the searched ones (use the counter on
+ the left to adjust this count). For phrases, the default count
+ is zero (exact match). For proximity it is ten (meaning that two search
+ terms, would be matched if found within a window of twelve
+ words). Examples: a phrase search for <literal>quick
+ fox</literal> with a slack of 0 will match <literal>quick
+ fox</literal> but not <literal>quick brown fox</literal>. With
+ a slack of 1 it will match the latter, but not <literal>fox
+ quick</literal>. A proximity search for <literal>quick
+ fox</literal> with the default slack will match the
+ latter, and also <literal>a fox is a cunning and quick animal</literal>.
+ </formalpara>
+
+ <para>Click on the <guilabel>Start Search</guilabel> button in
+ the advanced search dialog, or type <keycap>Enter</keycap> in
+ any text field to start the search. The button in
+ the main window always performs a simple search.</para>
+ <para>Click on the <literal>Show query details</literal> link at
+ the top of the result page to see the query expansion.</para>
+
+ </sect2>
+
+ <sect2 id="rcl.search.termexplorer">
+ <title>The term explorer tool</title>
+
+ <para>&RCL; automatically manages the expansion of search terms
+ to their derivatives (ie: plural/singular, verb
+ inflections). But there are other cases where the exact search
+ term is not known. For example, you may not remember the exact
+ spelling, or only know the beginning of the name.</para>
+
+ <para>The term explorer tool (started from the toolbar icon or
+ from the <guilabel>Term explorer</guilabel> entry of the
+ <guilabel>Tools</guilabel> menu) can be used to search the full index
+ terms list. It has three modes of operations:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term>Wildcard</term>
+ <listitem><para>In this mode of operation, you can enter a
+ search string with shell-like wildcards (*, ?, []). ie:
+ <replaceable>xapi*</replaceable> would display all index terms
+ beginning with <replaceable>xapi</replaceable>. (More
+ about wildcards <link
+ linkend="rcl.search.wildcards">here</link>).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Regular expression</term>
+ <listitem><para>This mode will accept a regular expression
+ as input. Example:
+ <replaceable>word[0-9]+</replaceable>. The expression is
+ implicitely anchored at the beginning. Ie:
+ <replaceable>press</replaceable> will match
+ <replaceable>pression</replaceable> but not
+ <replaceable>expression</replaceable>. You can use
+ <replaceable>.*press</replaceable> to match the latter,
+ but be aware that this will cause a full index term list
+ scan, which can be quite long.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+
+ <term>Stem expansion</term>
+ <listitem><para>This mode will perform the usual stem expansion
+ normally done as part user input processing. As such it is
+ probably mostly useful to demonstrate the process.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Spelling/Phonetic</term> <listitem><para>In this
+ mode, you enter the term as you think it is spelled, and
+ &RCL; will do its best to find index terms that sound like
+ your entry. This mode uses the
+ <application>Aspell</application> spelling application,
+ which must be installed on your system for things to work
+ (if your documents contain non-ascii characters, &RCL;
+ needs an aspell version newer than 0.60 for UTF-8
+ support). The language which is used to build the
+ dictionary out of the index terms (which is done at the
+ end of an indexing pass) is the one defined by your NLS
+ environment. Weird things will probably happen if
+ languages are mixed up.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Note that in cases where &RCL; does not know the beginning
+ of the string to search for (ie a wildcard expression like
+ <replaceable>*coll</replaceable>), the expansion can take quite
+ a long time because the full index term list will have to be
+ processed. The expansion is currently limited at 200 results for
+ wildcards and regular expressions.</para>
+
+ <para>Double-clicking on a term in the result list will insert
+ it into the simple search entry field. You can also cut/paste
+ between the result list and any entry field (the end of lines
+ will be taken care of).</para>
+
+ </sect2>
+
+ <sect2 id="rcl.search.multidb">
+ <title>Multiple databases</title>
+
+ <para>Multiple &RCL; databases or indexes can be created by
+ using several configuration directories which are usually set to
+ index different areas of the file system. A specific index can
+ be selected for updating or searching, using the
+ <literal>RECOLL_CONFDIR</literal> environment variable or the
+ <literal>-c</literal> option to <command>recoll</command> and
+ <command>recollindex</command>.</para>
+
+ <para>A <command>recollindex</command> program instance can only
+ update one specific index.</para>
+
+ <para>A <command>recoll</command> program instance is also
+ associated with a specific index, which is the one to be
+ updated by its indexing thread, but it can use any
+ number of &RCL; indexes for searching. The external indexes
+ can be selected through the <guilabel>external
+ indexes</guilabel> tab in the preferences dialog.</para>
+
+ <para>Index selection is performed in two phases. A set of all
+ usable indexes must first be defined, and then the subset of
+ indexes to be used for searching. Of course, these parameters
+ are retained across program executions (there are kept
+ separately for each &RCL; configuration). The set of all indexes
+ is usually quite stable, while the active ones might typically
+ be adjusted quite frequently.</para>
+
+ <para>The main index (defined by
+ <literal>RECOLL_CONFDIR</literal>) is always active. If this is
+ undesirable, you can set up your base configuration to index
+ an empty directory.</para>
+
+ <para>As building the set of all indexes can be a little tedious
+ when done through the user interface, you can use the
+ <literal>RECOLL_EXTRA_DBS</literal> environment
+ variable to provide an initial set. This might typically be
+ set up by a system administrator so that every user does not
+ have to do it. The variable should define a colon-separated list
+ of index directories, ie:
+ </para>
+ <screen>export RECOLL_EXTRA_DBS=/some/place/xapiandb:/some/other/db</screen>
+
+ <para>A typical usage scenario for the multiple index feature
+ would be for a system administrator to set up a central index
+ for shared data, that you choose to search or not in addition to
+ your personal data. Of course, there are other
+ possibilities. There are many cases where you know the subset of
+ files that should be searched, and where narrowing the search
+ can improve the results. You can achieve approximately the same
+ effect with the directory filter in advanced search, but
+ multiple indexes will have much better performance and may be
+ worth the trouble.</para>
+
+ </sect2>
+
+ <sect2 id="rcl.search.history">
+ <title>Document history</title>
+
+ <para>Documents that you actually view (with the internal preview
+ or an external tool) are entered into the document history,
+ which is remembered.</para>
+ <para>You can display the history list by using
+ the <guilabel>Tools/</guilabel><guilabel>Doc History</guilabel> menu
+ entry.</para>
+ <para>You can erase the document history by using the
+ <guilabel>Erase document history</guilabel> entry in the
+ <guimenu>File</guimenu> menu.
+
+ </sect2>
+
+ <sect2 id="rcl.search.sort">
+ <title>Sorting search results and collapsing duplicates</title>
+
+ <para>The documents in a result list are normally sorted in
+ order of relevance. It is possible to specify different sort
+ parameters by using the <guimenu>Sort parameters</guimenu>
+ dialog (located in the <guimenu>Tools</guimenu> menu).</para>
+
+ <para>The tool sorts a specified number of the most
+ relevant documents in the result list, according to specified
+ criteria. The currently available criteria are
+ <emphasis>date</emphasis> and <emphasis>mime
+ type</emphasis>.</para>
+
+ <para>The sort parameters stay in effect until they are
+ explicitly reset, or the program exits. An activated sort is
+ indicated in the result list header.</para>
+
+ <para>Sort parameters are remembered between program
+ invocations, but result sorting is normally always inactive
+ when the program starts. It is possible to keep the sorting
+ activation state between program invocations by checking the
+ <guilabel>Remember sort activation state</guilabel> option in
+ the preferences.</para>
+
+ <para>It is also possible to hide duplicate entries inside
+ the result list (documents with the exact same contents as the
+ displayed one). The test of identity is based on an MD5 hash
+ of the document container, not only of the text contents (so
+ that ie, a text document with an image added will not be a
+ duplicate of the text only). Duplicates hiding is controlled
+ by an entry in the <guilabel>Query configuration</guilabel>
+ dialog, and is off by default.</para>
+
+ </sect2>
+
+ <sect2 id="rcl.search.tips">
+ <title>Search tips, shortcuts</title>
+
+ <sect3 id="rcl.search.tips.terms">
+ <title>Terms and search expansion</title>
+
+ <formalpara><title>Term completion</title>
+ <para>Typing <keycap>Esc</keycap> <keycap>Space</keycap> in
+ the simple search entry field while entering a word will
+ either complete the current word if its beginning matches a
+ unique term in the index, or open a window to propose a list
+ of completions.</para>
+ </formalpara>
+
+ <formalpara><title>Picking up new terms from result or preview
+ text</title>
+ <para>Double-clicking on a word in the result list or in a
+ preview window will copy it to the simple search entry field.</para>
+ </formalpara>
+
+ <formalpara><title>Wildcards</title>
+ <para>Wildcards can be used inside search terms in all forms
+ of searches. <link linkend="rcl.search.wildcards">
+ More about wildcards</link>.
+ </para>
+ </formalpara>
+
+ <formalpara><title>Automatic suffixes</title>
+ <para>Words like <literal>odt</literal> or <literal>ods</literal>
+ can be automatically turned into query language
+ <literal>ext:xxx</literal> clauses. This can be enabled in the
+ <guilabel>Search preferences</guilabel> panel in the GUI.
+ </para>
+ </formalpara>
+
+ <formalpara><title>Disabling stem expansion</title>
+ <para>Entering a capitalized word in any search field will prevent
+ stem expansion (no search for
+ <literal>gardening</literal> if you enter
+ <literal>Garden</literal> instead of
+ <literal>garden</literal>). This is the only case where
+ character case should make a difference for a &RCL;
+ search. You can also disable stem expansion or change the
+ stemming language in the preferences.</para>
+ </formalpara>
+
+ <formalpara><title>Finding related documents</title>
+ <para>Selecting the <guilabel>Find similar documents</guilabel> entry
+ in the result list paragraph right-click menu will select a
+ set of "interesting" terms from the current result, and insert
+ them into the simple search entry field. You can then possibly
+ edit the list and start a search to find documents which may
+ be apparented to the current result.</para>
+ </formalpara>
+
+ <formalpara><title>File names</title>
+ <para>File names are added as terms during indexing, and you can
+ specify them as ordinary terms in normal search fields (&RCL; used
+ to index all directories in the file path as terms. This has been
+ abandoned as it did not seem really useful). Alternatively, you
+ can use the specific file name search which will
+ <emphasis>only</emphasis> look for file names, and may be
+ faster than the generic search especially when using wildcards.</para>
+ </formalpara>
+
+ </sect3>
+
+
+ <sect3 id="rcl.search.tips.phrases">
+ <title>Working with phrases and proximity</title>
+
+ <formalpara><title>Phrases and Proximity searches</title>
+ <para>A phrase can be looked for by enclosing it in double
+ quotes. Example: <literal>"user manual"</literal> will look
+ only for occurrences of <literal>user</literal> immediately
+ followed by <literal>manual</literal>. You can use the
+ <guilabel>This phrase</guilabel> field of the advanced
+ search dialog to the same effect. Phrases can be entered along
+ simple terms in all simple or advanced search entry fields
+ (except <guilabel>This exact phrase</guilabel>).</para>
+ </formalpara>
+
+ <formalpara><title>AutoPhrases</title>
+ <para>This option can be set in the preferences dialog. If it is
+ set, a phrase will be automatically built and added to simple
+ searches when looking for <literal>Any terms</literal>. This
+ will not change radically the results, but will give a relevance
+ boost to the results where the search terms appear as a
+ phrase. Ie: searching for <literal>virtual reality</literal>
+ will still find all documents where either
+ <literal>virtual</literal> or <literal>reality</literal> or
+ both appear, but those which contain <literal>virtual
+ reality</literal> should appear sooner in the list.</para>
+
+ </sect3>
+
+ <sect3 id="rcl.search.tips.misc">
+ <title>Others</title>
+
+ <formalpara><title>Using fields</title>
+ <para>You can use the <link linkend="rcl.search.lang">query
+ language </link> and field specifications
+ to only search certain parts of documents. This can be
+ especially helpful with email, for example only searching
+ emails from a specific originator:
+ <literal>search tips from:helpfulgui</literal>
+ </para>
+ </formalpara>
+
+ <formalpara><title>Query explanation</title>
+ <para>You can get an exact description of what the query
+ looked for, including stem expansion, and Boolean operators
+ used, by clicking on the result list header.</para>
+ </formalpara>
+
+ <formalpara><title>Browsing the result list inside a preview
+ window</title>
+ <para>Entering <keycap>Shift-Down</keycap> or <keycap>Shift-Up</keycap>
+ (<keycap>Shift</keycap> + an arrow key) in a preview window will
+ display the next or the previous document from the result
+ list. Any secondary search currently active will be executed on
+ the new document.</para>
+ </formalpara>
+
+ <formalpara><title>Scrolling the result list from the keyboard</title>
+ <para>You can use <keycap>PageUp</keycap> and <keycap>PageDown</keycap>
+ to scroll the result list, <keycap>Shift+Home</keycap> to go back
+ to the first page. These work even while the focus is in the
+ search entry.</para>
+ </formalpara>
+
+ <formalpara><title>Forced opening of a preview window</title>
+ <para>You can use <keycap>Shift</keycap>+Click on a result list
+ <literal>Preview</literal> link to force the creation of a
+ preview window instead of a new tab in the existing one.</para>
+ </formalpara>
+
+ <formalpara><title>Closing previews</title>
+ <para>Entering <keycap>^W</keycap> in a tab will
+ close it (and, for the last tab, close the preview
+ window). Entering <keycap>Esc</keycap> will close the preview
+ window and all its tabs.</para>
+ </formalpara>
+
+ <formalpara><title>Printing previews</title>
+ <para>Entering <keycap>^P</keycap> in a preview window will print
+ the currently displayed text.</para>
+ </formalpara>
+
+ <formalpara><title>Quitting</title>
+ <para>Entering <keycap>^Q</keycap> almost anywhere will
+ close the application.</para>
+ </formalpara>
+ </sect3>
+ </sect2>
+
+ <sect2 id="rcl.search.custom">
+ <title>Customizing the search interface</title>
+
+ <para>You can customize some aspects of the search interface by using
+ the <guimenu>Query configuration</guimenu> entry in the
+ <guimenu>Preferences</guimenu> menu.</para>
+
+ <para>There are several tabs in the dialog, dealing with the
+ interface itself, the parameters used for searching and
+ returning results, and what indexes are searched.</para>
+
+ <formalpara id="rcl.search.custom.ui">
+ <title>User interface parameters:</title>
+ <para>
+ <itemizedlist>
+
+ <listitem><para><guilabel>Number of results in a result
+ page</guilabel>: </para>
+ </listitem>
+
+ <listitem><para><guilabel>Hide duplicate results</guilabel>:
+ decides if result list entries are shown for identical
+ documents found in different places.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Highlight color for query
+ terms</guilabel>: Terms from the user query are highlighted in
+ the result list samples and the preview window. The color can
+ be chosen here. Any Qt color string should work (ie
+ <literal>red</literal>, <literal>#ff0000</literal>). The
+ default is <literal>blue</literal>.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Result list font</guilabel>: There is
+ quite a lot of information shown in the result list, and you
+ may want to customize the font and/or font size. The rest of
+ the fonts used by &RCL; are determined by your generic Qt
+ config (try the <command>qtconfig</command> command).</para>
+ </listitem>
+
+ <listitem><anchor id="rcl.search.custom.resultpara">
+ <para><guilabel>Result paragraph format string</guilabel>:
+ allows you to change the presentation of each result list
+ entry. This is <link linkend="rcl.search.custom.reslistpara">
+ described in its own section.</link></para>
+ </listitem>
+
+ <listitem><para><guilabel>Maximum text size highlighted for
+ preview</guilabel> Inserting highlights on search term inside
+ the text before inserting it in the preview window involves
+ quite a lot of processing, and can be disabled over the given
+ text size to speed up loading.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Use desktop preferences to choose
+ document editor</guilabel>: if this is checked, the
+ <command>xdg-open</command> utility will be used to open files
+ when you click the <guilabel>Open</guilabel> link in the result
+ list, instead of the application defined in
+ <filename>mimeview</filename>. <command>xdg-open</command> will
+ in term use your desktop preferences to choose an appropriate
+ application.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Choose editor applications</guilabel>
+ this will let you choose the command started by the
+ <guilabel>Open</guilabel> links inside the result list, for
+ specific document types.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Display category filter as
+ toolbar...</guilabel> this will let you choose if the document
+ categories are displayed as a list or a set of buttons.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Auto-start simple search on white
+ space entry</guilabel>: if this is checked, a search will be
+ executed each time you enter a space in the simple search input
+ field. This lets you look at the result list as you enter new
+ terms. This is off by default, you may like it or not...</para>
+ </listitem>
+
+ <listitem><para><guilabel>Start with advanced search dialog open
+ </guilabel> and <guilabel>Start with sort dialog
+ open</guilabel>: If you use these dialogs all the time, checking
+ these entries will get them to open when recoll starts.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Remember sort activation
+ state</guilabel> if set, Recoll will remember the sort tool
+ stat between invocations. It normally starts with sorting
+ disabled.</para>
+ </listitem>
+ <listitem><para><guilabel>Prefer HTML to plain text for preview
+
+ </guilabel> if set, Recoll will display HTML as such inside the
+ preview window. If this causes problems with the Qt HTML
+ display, you can uncheck it to display the plain text version
+ instead. </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+
+ <formalpara id="rcl.search.custom.search">
+ <title>Search parameters:</title>
+ <para>
+ <itemizedlist>
+
+ <listitem><para><guilabel>Stemming language</guilabel>:
+ stemming obviously depends on the document's language. This
+ listbox will let you chose among the stemming databases which
+ were built during indexing (this is set in the <link
+ linkend="rcl.install.config.recollconf">main configuration
+ file</link>), or later added with <command>recollindex
+ -s</command> (See the recollindex manual). Stemming languages
+ which are dynamically added will be deleted at the next
+ indexing pass unless they are also added in the configuration
+ file.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Dynamically add phrase to simple
+ searches</guilabel>: a phrase will be automatically built and
+ added to simple searches when looking for <literal>Any
+ terms</literal>. This will give a relevance boost to the
+ results where the search terms appear as a phrase (consecutive
+ and in order).</para>
+ </listitem>
+
+ <listitem><para><guilabel>Replace abstracts from
+ documents</guilabel>: this decides if we should synthesize and
+ display an abstract in place of an explicit abstract found
+ within the document itself.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Dynamically build
+ abstracts</guilabel>: this decides if &RCL; tries to build
+ document abstracts when displaying the result list. Abstracts
+ are constructed by taking context from the document
+ information, around the search terms. This can slow down
+ result list display significantly for big documents, and you
+ may want to turn it off.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Synthetic abstract size</guilabel>:
+ adjust to taste...</para>
+ </listitem>
+
+ <listitem><para><guilabel>Synthetic abstract context
+ words</guilabel>: how many words should be displayed around
+ each term occurrence.</para>
+ </listitem>
+
+ <listitem><para><guilabel>Query language magic file name
+ suffixes</guilabel>: a list of words which automatically get
+ turned into <literal>ext:xxx</literal> file name suffix clauses
+ when starting a query language query (ie: <literal>doc xls
+ xlsx...</literal>). This will save some typing for people who
+ use file types a lot when querying.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+
+ <formalpara id="rcl.search.custom.extradb">
+ <title>External indexes:</title>
+ <para>This panel will let you browse for additional indexes
+ that you may want to search. External indexes are designated by
+ their database directory (ie:
+ <filename>/home/someothergui/.recoll/xapiandb</filename>,
+ <filename>/usr/local/recollglobal/xapiandb</filename>).</para>
+
+ <para>Once entered, the indexes will appear in the
+ <guilabel>External indexes</guilabel> list, and you can
+ chose which ones you want to use at any moment by checking or
+ unchecking their entries.</para>
+
+ <para>Your main database (the one the current configuration
+ indexes to), is always implicitly active. If this is not
+ desirable, you can set up your configuration so that it indexes,
+ for example, an empty directory. An alternative indexer may also
+ need to implement a way of purging the index from stale data,
+ </para>
+
+ <sect3 id="rcl.search.custom.reslistpara">
+ <title>The result list paragraph format</title>
+
+ <para>The presentation of each result inside the result list can be
+ customized by setting the result list paragraph format inside the
+ <guilabel>User Interface</guilabel> tab of the <guilabel>Query
+ configuration</guilabel>.</para>
+
+ <para>This is a Qt HTML string where the following printf-like
+ <literal>%</literal> substitutions will be performed:
+
+ <itemizedlist>
+ <listitem>
+ <formalpara><title>%A</title><para>Abstract</para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%D</title><para>Date</para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%I</title><para>Icon image name
+ </para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%K</title><para>Keywords (if
+ any)</para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%L</title><para>Preview and
+ Edit links</para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%M</title><para>Mime
+ type</para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%N</title><para>result Number
+ </para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%R</title><para>Relevance
+ percentage</para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%S</title><para>Size
+ information</para></formalpara>
+ </listitem>
+ <listitem><formalpara><title>%T</title><para>Title</para>
+ </formalpara>
+ </listitem>
+ <listitem><formalpara><title>%U</title><para>Url</para></formalpara>
+ </listitem>
+ </itemizedlist>
+
+ The format of the Preview and Edit links is
+ <literal><a href="P%N"></literal>
+ and
+ <literal><a href="E%N"></literal>
+ where <replaceable>docnum</replaceable> (%N expands to the document
+ number inside the result list).</para>
+
+ <para>In addition to the predefined values above, all strings like
+ <literal>%(fieldname)</literal> will be replaced by the value of
+ the field named <literal>fieldname</literal> for this
+ document. Only stored fields can be accessed in this way, the value
+ of indexed but not stored fields is not known at this point in the
+ search process (see <link linkend="rcl.program.fields">field
+ configuration</link>). There are currently very few fields stored
+ by default, apart from the values above (only
+ <literal>author</literal>), so this feature will need some custom
+ local configuration to be useful. For example, you could look at
+ the fields for the document types of interest (use the right-click
+ menu inside the preview window), and add what you want to the list
+ of stored fields. A candidate example would be the
+ <literal>recipient</literal> field which is generated by the
+ message filters.</para>
+
+ <para>The default value for the paragraph format string is:
+ <programlisting><img src="%I" align="left">%R %S %L &nbsp;&nbsp;<b>%T</b><br>
+%M&nbsp;%D&nbsp;&nbsp;&nbsp;<i>%U</i>&nbsp;%i<br>
+%A %K
+ </programlisting>
+ You may, for example, try the following for a more web-like
+ experience:
+ <programlisting><u><b><a href="P%N">%T</a></b></u><br>
+%A<font color=#008000>%U - %S</font> - %L
+ </programlisting>
+ Or the clean looking:
+ <programlisting><img src="%I" align="left">%L <font color="#900000">%R</font>
+ <b>%T</b><br>%S
+<font color="#808080"><i>%U</i></font>
+<table bgcolor="#e0e0e0">
+<tr><td><div>%A</div></td></tr>
+</table>%K
+ </programlisting>
+ Note that the P%N link in the above paragraph makes the title a
+ preview link.
+ </para>
+
+ <para>Due to the way the program handles right mouse clicks in the
+ result list, if the custom formatting results in multiple
+ paragraphs per result, right clicks will only work inside the first
+ one.</para>
+
+
+ </sect3>
+ </sect2>
+
+ </sect1> <!-- search GUI -->
+
+ <sect1 id="rcl.searchkio">
+ <title>Searching with the KDE KIO slave</title>
+
+ <sect2 id="rcl.searchkio.intro">
+ <title>What's this</title>
+
+ <para>The &RCL; KIO slave allows performing a &RCL; search
+ by entering an appropriate URL in a KDE open dialog, or with an
+ HTML-based interface displayed in
+ <command>Konqueror</command>.</para>
+
+ <para>The HTML-based interface is similar to the Qt-based
+ interface, but slightly less powerful for now. Its advantage is
+ that you can perform your search while staying fully within the
+ KDE framework: drag and drop from the result list works normally
+ and you have your normal choice of applications for opening
+ files.</para>
+
+ <para>The alternative interface uses a directory view of search
+ results. Due to limitations in the current KIO slave interface,
+ it is currently not obviously useful (to me).</para>
+
+ <para>The interface is described in more detail inside a help
+ file which you can access by entering
+ <filename>recoll:/</filename> inside the
+ <command>konqueror</command> URL line (this works only if the
+ recoll KIO slave has been previously installed).</para>
+
+
+ <para>The instructions for building this module are located in the
+ source tree. See:
+ <filename>kde/kio/recoll/00README.txt</filename>. Some Linux
+ 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">
+ <title>Searchable documents</title>
+
+ <para>As a sample application, the &RCL; KIO slave could allow
+ preparing a set of HTML documents (for example a manual) so that
+ they become their own search interface inside
+ <command>konqueror</command>.</para>
+
+ <para>This can be done by either explicitly inserting
+ <literal><a href="recoll:/..."></literal> links
+ around some document areas, or automatically by adding a
+ very small <application>javascript</application> program to the
+ documents, like the following example, which would initiate a search by
+ double-clicking any term:</para>
+
+ <programlisting><script language="JavaScript">
+ function recollsearch() {
+ var t = document.getSelection();
+ window.location.href = 'recoll://search/query?qtp=a&p=0&q=' +
+ encodeURIComponent(t);
+ }
+</script>
+ ....
+<body ondblclick="recollsearch()">
+
+</programlisting>
+ </sect2>
</sect1>
+
+
+ <sect1 id="rcl.search.commandline">
+ <title>Searching on the command line</title>
+
+ <para>There are several ways to obtain search results as a text
+ stream, without a graphical interface:</para>
+ <itemizedlist>
+ <listitem><para>By passing option <literal>-t</literal> to the
+ <command>recoll</command> program.</para>
+ </listitem>
+ <listitem><para>By using the <command>recollq</command> program.</para>
+ </listitem>
+ <listitem><para>By writing a custom
+ <application>Python</application> program, using the
+ <link linkend="rcl.program.api.python">Recoll Python API</link>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The first two methods work in the same way and accept/need the same
+ arguments (except for the additional <literal>-t</literal> to
+ <command>recoll</command>). The query to be executed is specified
+ as command line arguments.</para>
+
+ <para><command>recollq</command> is not built by default. You can
+ use the <filename>Makefile</filename> in the
+ <filename>query</filename> directory to build it. This is a very
+ simple program, and if you can program a little c++, you may find it
+ useful to taylor its output format to your needs.</para>
+
+ <para><command>recollq</command> has a man page (not installed by
+ default, look in the <filename>doc/man</filename> directory). The
+ Usage string is as follows:</para>
+<programlisting>recollq [-o|-a|-f] <query string>
+ Runs a recoll query and displays result lines.
+ Default: will interpret the argument(s) as a query language string
+ -o Emulate the gui simple search in ANY TERM mode
+ -a Emulate the gui simple search in ALL TERMS mode
+ -f Emulate the gui simple search in filename mode
+Common options:
+ -c <configdir> : specify config directory, overriding $RECOLL_CONFDIR
+ -d also dump file contents
+ -n <cnt> limit the maximum number of results (0->no limit, default 2000)
+ -b : basic. Just output urls, no mime types or titles
+ -m : dump the whole document meta[] array
+ -S fld : sort by field name
+ -D : sort descending
+</programlisting>
+
+ <para>Sample execution:</para>
+<programlisting>recollq 'ilur -nautique mime:text/html'
+Recoll query: ((((ilur:(wqf=11) OR ilurs) AND_NOT (nautique:(wqf=11)
+ OR nautiques OR nautiqu OR nautiquement)) FILTER Ttext/html))
+4 results
+text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/comptes.html] [comptes.html] 18593 bytes
+text/html [file:///Users/uncrypted-dockes/projets/nautique/webnautique/articles/ilur1/index.html] [Constructio...
+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....
+</programlisting>
+ </sect1>
<sect1 id="rcl.search.lang">
<title>The query language</title>
- <para>The query language processor is activated on the
+ <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>.</para>
+ <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>
@@ -977,6 +1835,10 @@
<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>
@@ -1058,7 +1920,10 @@
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>
+ 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
@@ -1073,201 +1938,20 @@
</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>
- <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>
-
- <para>The advanced search dialog helps you build more complex
- queries. It can be opened through the <guilabel>Tools</guilabel>
- menu or through the main toolbar.</para>
-
- <para>The dialog has three parts:</para>
-
- <itemizedlist>
- <listitem><para>The top part allows constructing a query by
- combining multiple clauses of different types.
- Each entry field is configurable for the following modes:</para>
-
- <itemizedlist>
- <listitem><para>All terms.</para>
- </listitem>
- <listitem><para>Any term.</para>
- </listitem>
- <listitem><para>None of the terms.</para>
- </listitem>
- <listitem><para>Phrase (exact terms in order within an
- adjustable window).</para>
- </listitem>
- <listitem><para>Proximity (terms in any order within an
- adjustable window).</para>
- </listitem>
- <listitem><para>Filename search.</para>
- </listitem>
- </itemizedlist>
-
- <para>Additional entry fields can be created by clicking the
- <guilabel>Add clause</guilabel> button.</para>
-
- <para>When searching, the non-empty clauses will be
- combined either with an AND or an OR conjunction, depending on
- the choice made on the left (<guilabel>All clauses</guilabel> or
- <guilabel>Any clause</guilabel>).</para>
-
- <para>Entries of all types except "Phrase" and "Near" accept
- a mix of single words and phrases enclosed in double quotes.
- Stemming and wildcard expansion will be performed as for simple
- search. </para>
- </listitem>
-
- <listitem><para>The next part allows filtering the
- results by their mime types.</para>
- <para>The state of the file type selection can be saved as
- the default (the file type filter will not be activated at
- program start-up, but the lists will be in the restored
- state).</para>
- </listitem>
-
- <listitem>
- <para>The bottom part allows restricting the search results to a
- sub-tree of the indexed area. If you need to do this often,
- you may think of setting up multiple indexes instead, as the
- performance will be much better.</para>
- </listitem>
-
- </itemizedlist>
-
-
- <formalpara><title>Phrases and Proximity searches</title>
- <para>These two clauses work in similar ways, with the
- difference that proximity searches do not impose an order on the
- words. In both cases, an adjustable number (slack) of non-matched words
- may be accepted between the searched ones (use the counter on
- the left to adjust this count). For phrases, the default count
- is zero (exact match). For proximity it is ten (meaning that two search
- terms, would be matched if found within a window of twelve
- words). Examples: a phrase search for <literal>quick
- fox</literal> with a slack of 0 will match <literal>quick
- fox</literal> but not <literal>quick brown fox</literal>. With
- a slack of 1 it will match the latter, but not <literal>fox
- quick</literal>. A proximity search for <literal>quick
- fox</literal> with the default slack will match the
- latter, and also <literal>a fox is a cunning and quick animal</literal>.
- </formalpara>
-
- <para>Click on the <guilabel>Start Search</guilabel> button in
- the advanced search dialog, or type <keycap>Enter</keycap> in
- any text field to start the search. The button in
- the main window always performs a simple search.</para>
- <para>Click on the <literal>Show query details</literal> link at
- the top of the result page to see the query expansion.</para>
-
- </sect1>
-
- <sect1 id="rcl.search.termexplorer">
- <title>The term explorer tool</title>
-
- <para>&RCL; automatically manages the expansion of search terms
- to their derivatives (ie: plural/singular, verb
- inflections). But there are other cases where the exact search
- term is not known. For example, you may not remember the exact
- spelling, or only know the beginning of the name.</para>
-
- <para>The term explorer tool (started from the toolbar icon or
- from the <guilabel>Term explorer</guilabel> entry of the
- <guilabel>Tools</guilabel> menu) can be used to search the full index
- terms list. It has three modes of operations:</para>
- <variablelist>
-
- <varlistentry>
- <term>Wildcard</term>
- <listitem><para>In this mode of operation, you can enter a
- search string with shell-like wildcards (*, ?, []). ie:
- <replaceable>xapi*</replaceable> would display all index terms
- beginning with <replaceable>xapi</replaceable>. (More
- about wildcards <link
- linkend="rcl.search.wildcards">here</link>).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Regular expression</term>
- <listitem><para>This mode will accept a regular expression
- as input. Example:
- <replaceable>word[0-9]+</replaceable>. The expression is
- implicitely anchored at the beginning. Ie:
- <replaceable>press</replaceable> will match
- <replaceable>pression</replaceable> but not
- <replaceable>expression</replaceable>. You can use
- <replaceable>.*press</replaceable> to match the latter,
- but be aware that this will cause a full index term list
- scan, which can be quite long.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
-
- <term>Stem expansion</term>
- <listitem><para>This mode will perform the usual stem expansion
- normally done as part user input processing. As such it is
- probably mostly useful to demonstrate the process.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Spelling/Phonetic</term> <listitem><para>In this
- mode, you enter the term as you think it is spelled, and
- &RCL; will do its best to find index terms that sound like
- your entry. This mode uses the
- <application>Aspell</application> spelling application,
- which must be installed on your system for things to work
- (if your documents contain non-ascii characters, &RCL;
- needs an aspell version newer than 0.60 for UTF-8
- support). The language which is used to build the
- dictionary out of the index terms (which is done at the
- end of an indexing pass) is the one defined by your NLS
- environment. Weird things will probably happen if
- languages are mixed up.</para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>Note that in cases where &RCL; does not know the beginning
- of the string to search for (ie a wildcard expression like
- <replaceable>*coll</replaceable>), the expansion can take quite
- a long time because the full index term list will have to be
- processed. The expansion is currently limited at 200 results for
- wildcards and regular expressions.</para>
-
- <para>Double-clicking on a term in the result list will insert
- it into the simple search entry field. You can also cut/paste
- between the result list and any entry field (the end of lines
- will be taken care of).</para>
-
- </sect1>
-
- <sect1 id="rcl.search.wildcards">
+ <sect2 id="rcl.search.wildcards">
<title>More about wildcards</title>
<para>All words entered in &RCL; search fields will be processed
@@ -1313,689 +1997,60 @@
</listitem>
</itemizedlist>
- </sect1>
-
- <sect1 id="rcl.search.multidb">
- <title>Multiple databases</title>
-
- <para>Multiple &RCL; databases or indexes can be created by
- using several configuration directories which are usually set to
- index different areas of the file system. A specific index can
- be selected for updating or searching, using the
- <literal>RECOLL_CONFDIR</literal> environment variable or the
- <literal>-c</literal> option to <command>recoll</command> and
- <command>recollindex</command>.</para>
-
- <para>A <command>recollindex</command> program instance can only
- update one specific index.</para>
-
- <para>A <command>recoll</command> program instance is also
- associated with a specific index, which is the one to be
- updated by its indexing thread, but it can use any
- number of &RCL; indexes for searching. The external indexes
- can be selected through the <guilabel>external
- indexes</guilabel> tab in the preferences dialog.</para>
-
- <para>Index selection is performed in two phases. A set of all
- usable indexes must first be defined, and then the subset of
- indexes to be used for searching. Of course, these parameters
- are retained across program executions (there are kept
- separately for each &RCL; configuration). The set of all indexes
- is usually quite stable, while the active ones might typically
- be adjusted quite frequently.</para>
-
- <para>The main index (defined by
- <literal>RECOLL_CONFDIR</literal>) is always active. If this is
- undesirable, you can set up your base configuration to index
- an empty directory.</para>
-
- <para>As building the set of all indexes can be a little tedious
- when done through the user interface, you can use the
- <literal>RECOLL_EXTRA_DBS</literal> environment
- variable to provide an initial set. This might typically be
- set up by a system administrator so that every user does not
- have to do it. The variable should define a colon-separated list
- of index directories, ie:
- </para>
- <screen>export RECOLL_EXTRA_DBS=/some/place/xapiandb:/some/other/db</screen>
-
- <para>A typical usage scenario for the multiple index feature
- would be for a system administrator to set up a central index
- for shared data, that you choose to search or not in addition to
- your personal data. Of course, there are other
- possibilities. There are many cases where you know the subset of
- files that should be searched, and where narrowing the search
- can improve the results. You can achieve approximately the same
- effect with the directory filter in advanced search, but
- multiple indexes will have much better performance and may be
- worth the trouble.</para>
-
- </sect1>
-
- <sect1 id="rcl.search.history">
- <title>Document history</title>
-
- <para>Documents that you actually view (with the internal preview
- or an external tool) are entered into the document history,
- which is remembered.</para>
- <para>You can display the history list by using
- the <guilabel>Tools/</guilabel><guilabel>Doc History</guilabel> menu
- entry.</para>
- <para>You can erase the document history by using the
- <guilabel>Erase document history</guilabel> entry in the
- <guimenu>File</guimenu> menu.
-
- </sect1>
-
- <sect1 id="rcl.search.sort">
- <title>Sorting search results and collapsing duplicates</title>
-
- <para>The documents in a result list are normally sorted in
- order of relevance. It is possible to specify different sort
- parameters by using the <guimenu>Sort parameters</guimenu>
- dialog (located in the <guimenu>Tools</guimenu> menu).</para>
-
- <para>The tool sorts a specified number of the most
- relevant documents in the result list, according to specified
- criteria. The currently available criteria are
- <emphasis>date</emphasis> and <emphasis>mime
- type</emphasis>.</para>
-
- <para>The sort parameters stay in effect until they are
- explicitly reset, or the program exits. An activated sort is
- indicated in the result list header.</para>
-
- <para>Sort parameters are remembered between program
- invocations, but result sorting is normally always inactive
- when the program starts. It is possible to keep the sorting
- activation state between program invocations by checking the
- <guilabel>Remember sort activation state</guilabel> option in
- the preferences.</para>
-
- <para>It is also possible to hide duplicate entries inside
- the result list (documents with the exact same contents as the
- displayed one). The test of identity is based on an MD5 hash
- of the document container, not only of the text contents (so
- that ie, a text document with an image added will not be a
- duplicate of the text only). Duplicates hiding is controlled
- by an entry in the <guilabel>Query configuration</guilabel>
- dialog, and is off by default.</para>
-
- </sect1>
-
-
- <sect1 id="rcl.search.tips">
- <title>Search tips, shortcuts</title>
-
- <sect2 id="rcl.search.tips.terms">
- <title>Terms and search expansion</title>
-
- <formalpara><title>Term completion</title>
- <para>Typing <keycap>Esc</keycap> <keycap>Space</keycap> in
- the simple search entry field while entering a word will
- either complete the current word if its beginning matches a
- unique term in the index, or open a window to propose a list
- of completions.</para>
- </formalpara>
-
- <formalpara><title>Picking up new terms from result or preview
- text</title>
- <para>Double-clicking on a word in the result list or in a
- preview window will copy it to the simple search entry field.</para>
- </formalpara>
-
- <formalpara><title>Wildcards</title>
- <para>Wildcards can be used inside search terms in all forms
- of searches. <link linkend="rcl.search.wildcards">
- More about wildcards</link>.
- </para>
- </formalpara>
-
- <formalpara><title>Automatic suffixes</title>
- <para>Words like <literal>odt</literal> or <literal>ods</literal>
- can be automatically turned into query language
- <literal>ext:xxx</literal> clauses. This can be enabled in the
- <guilabel>Search preferences</guilabel> panel in the GUI.
- </para>
- </formalpara>
-
- <formalpara><title>Disabling stem expansion</title>
- <para>Entering a capitalized word in any search field will prevent
- stem expansion (no search for
- <literal>gardening</literal> if you enter
- <literal>Garden</literal> instead of
- <literal>garden</literal>). This is the only case where
- character case should make a difference for a &RCL;
- search. You can also disable stem expansion or change the
- stemming language in the preferences.</para>
- </formalpara>
-
- <formalpara><title>Finding related documents</title>
- <para>Selecting the <guilabel>Find similar documents</guilabel> entry
- in the result list paragraph right-click menu will select a
- set of "interesting" terms from the current result, and insert
- them into the simple search entry field. You can then possibly
- edit the list and start a search to find documents which may
- be apparented to the current result.</para>
- </formalpara>
-
- <formalpara><title>File names</title>
- <para>File names are added as terms during indexing, and you can
- specify them as ordinary terms in normal search fields (&RCL; used
- to index all directories in the file path as terms. This has been
- abandoned as it did not seem really useful). Alternatively, you
- can use the specific file name search which will
- <emphasis>only</emphasis> look for file names, and may be
- faster than the generic search especially when using wildcards.</para>
- </formalpara>
+ </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.search.tips.phrases">
- <title>Working with phrases and proximity</title>
-
- <formalpara><title>Phrases and Proximity searches</title>
- <para>A phrase can be looked for by enclosing it in double
- quotes. Example: <literal>"user manual"</literal> will look
- only for occurrences of <literal>user</literal> immediately
- followed by <literal>manual</literal>. You can use the
- <guilabel>This phrase</guilabel> field of the advanced
- search dialog to the same effect. Phrases can be entered along
- simple terms in all simple or advanced search entry fields
- (except <guilabel>This exact phrase</guilabel>).</para>
- </formalpara>
-
- <formalpara><title>AutoPhrases</title>
- <para>This option can be set in the preferences dialog. If it is
- set, a phrase will be automatically built and added to simple
- searches when looking for <literal>Any terms</literal>. This
- will not change radically the results, but will give a relevance
- boost to the results where the search terms appear as a
- phrase. Ie: searching for <literal>virtual reality</literal>
- will still find all documents where either
- <literal>virtual</literal> or <literal>reality</literal> or
- both appear, but those which contain <literal>virtual
- reality</literal> should appear sooner in the list.</para>
+ <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>
- <sect2 id="rcl.search.tips.misc">
- <title>Others</title>
-
-
- <formalpara><title>Using fields</title>
- <para>You can use the <link linkend="rcl.search.lang">query
- language </link> and field specifications
- to only search certain parts of documents. This can be
- especially helpful with email, for example only searching
- emails from a specific originator:
- <literal>search tips from:helpfulgui</literal>
- </para>
- </formalpara>
-
- <formalpara><title>Query explanation</title>
- <para>You can get an exact description of what the query
- looked for, including stem expansion, and Boolean operators
- used, by clicking on the result list header.</para>
- </formalpara>
-
- <formalpara><title>Browsing the result list inside a preview
- window</title>
- <para>Entering <keycap>Shift-Down</keycap> or <keycap>Shift-Up</keycap>
- (<keycap>Shift</keycap> + an arrow key) in a preview window will
- display the next or the previous document from the result
- list. Any secondary search currently active will be executed on
- the new document.</para>
- </formalpara>
-
- <formalpara><title>Scrolling the result list from the keyboard</title>
- <para>You can use <keycap>PageUp</keycap> and <keycap>PageDown</keycap>
- to scroll the result list, <keycap>Shift+Home</keycap> to go back
- to the first page. These work even while the focus is in the
- search entry.</para>
- </formalpara>
-
- <formalpara><title>Forced opening of a preview window</title>
- <para>You can use <keycap>Shift</keycap>+Click on a result list
- <literal>Preview</literal> link to force the creation of a
- preview window instead of a new tab in the existing one.</para>
- </formalpara>
-
- <formalpara><title>Closing previews</title>
- <para>Entering <keycap>^W</keycap> in a tab will
- close it (and, for the last tab, close the preview
- window). Entering <keycap>Esc</keycap> will close the preview
- window and all its tabs.</para>
- </formalpara>
-
- <formalpara><title>Printing previews</title>
- <para>Entering <keycap>^P</keycap> in a preview window will print
- the currently displayed text.</para>
- </formalpara>
-
- <formalpara><title>Quitting</title>
- <para>Entering <keycap>^Q</keycap> almost anywhere will
- close the application.</para>
- </formalpara>
- </sect2>
- </sect1>
-
- <sect1 id="rcl.search.custom">
- <title>Customizing the search interface</title>
-
- <para>You can customize some aspects of the search interface by using
- the <guimenu>Query configuration</guimenu> entry in the
- <guimenu>Preferences</guimenu> menu.</para>
-
- <para>There are several tabs in the dialog, dealing with the
- interface itself, the parameters used for searching and
- returning results, and what indexes are searched.</para>
-
- <formalpara id="rcl.search.custom.ui">
- <title>User interface parameters:</title>
- <para>
- <itemizedlist>
-
- <listitem><para><guilabel>Number of results in a result
- page</guilabel>: </para>
- </listitem>
-
- <listitem><para><guilabel>Hide duplicate results</guilabel>:
- decides if result list entries are shown for identical
- documents found in different places.</para>
- </listitem>
-
- <listitem><para><guilabel>Highlight color for query
- terms</guilabel>: Terms from the user query are highlighted in
- the result list samples and the preview window. The color can
- be chosen here. Any Qt color string should work (ie
- <literal>red</literal>, <literal>#ff0000</literal>). The
- default is <literal>blue</literal>.</para>
- </listitem>
-
- <listitem><para><guilabel>Result list font</guilabel>: There is
- quite a lot of information shown in the result list, and you
- may want to customize the font and/or font size. The rest of
- the fonts used by &RCL; are determined by your generic Qt
- config (try the <command>qtconfig</command> command).</para>
- </listitem>
-
- <listitem><anchor id="rcl.search.custom.resultpara">
- <para><guilabel>Result paragraph format string</guilabel>:
- allows you to change the presentation of each result list
- entry. This is <link linkend="rcl.search.custom.reslistpara">
- described in its own section.</link></para>
- </listitem>
-
- <listitem><para><guilabel>Maximum text size highlighted for
- preview</guilabel> Inserting highlights on search term inside
- the text before inserting it in the preview window involves
- quite a lot of processing, and can be disabled over the given
- text size to speed up loading.</para>
- </listitem>
-
- <listitem><para><guilabel>Use desktop preferences to choose
- document editor</guilabel>: if this is checked, the
- <command>xdg-open</command> utility will be used to open files
- when you click the <guilabel>Open</guilabel> link in the result
- list, instead of the application defined in
- <filename>mimeview</filename>. <command>xdg-open</command> will
- in term use your desktop preferences to choose an appropriate
- application.</para>
- </listitem>
-
- <listitem><para><guilabel>Choose editor applications</guilabel>
- this will let you choose the command started by the
- <guilabel>Open</guilabel> links inside the result list, for
- specific document types.</para>
- </listitem>
-
- <listitem><para><guilabel>Display category filter as
- toolbar...</guilabel> this will let you choose if the document
- categories are displayed as a list or a set of buttons.</para>
- </listitem>
-
- <listitem><para><guilabel>Auto-start simple search on white
- space entry</guilabel>: if this is checked, a search will be
- executed each time you enter a space in the simple search input
- field. This lets you look at the result list as you enter new
- terms. This is off by default, you may like it or not...</para>
- </listitem>
-
- <listitem><para><guilabel>Start with advanced search dialog open
- </guilabel> and <guilabel>Start with sort dialog
- open</guilabel>: If you use these dialogs all the time, checking
- these entries will get them to open when recoll starts.</para>
- </listitem>
-
- <listitem><para><guilabel>Remember sort activation
- state</guilabel> if set, Recoll will remember the sort tool
- stat between invocations. It normally starts with sorting
- disabled.</para>
- </listitem>
- <listitem><para><guilabel>Prefer HTML to plain text for preview
-
- </guilabel> if set, Recoll will display HTML as such inside the
- preview window. If this causes problems with the Qt HTML
- display, you can uncheck it to display the plain text version
- instead. </para>
- </listitem>
-
- </itemizedlist>
- </para>
- </formalpara>
-
-
- <formalpara id="rcl.search.custom.search">
- <title>Search parameters:</title>
- <para>
- <itemizedlist>
-
- <listitem><para><guilabel>Stemming language</guilabel>:
- stemming obviously depends on the document's language. This
- listbox will let you chose among the stemming databases which
- were built during indexing (this is set in the <link
- linkend="rcl.install.config.recollconf">main configuration
- file</link>), or later added with <command>recollindex
- -s</command> (See the recollindex manual). Stemming languages
- which are dynamically added will be deleted at the next
- indexing pass unless they are also added in the configuration
- file.</para>
- </listitem>
-
- <listitem><para><guilabel>Dynamically add phrase to simple
- searches</guilabel>: a phrase will be automatically built and
- added to simple searches when looking for <literal>Any
- terms</literal>. This will give a relevance boost to the
- results where the search terms appear as a phrase (consecutive
- and in order).</para>
- </listitem>
-
- <listitem><para><guilabel>Replace abstracts from
- documents</guilabel>: this decides if we should synthesize and
- display an abstract in place of an explicit abstract found
- within the document itself.</para>
- </listitem>
-
- <listitem><para><guilabel>Dynamically build
- abstracts</guilabel>: this decides if &RCL; tries to build
- document abstracts when displaying the result list. Abstracts
- are constructed by taking context from the document
- information, around the search terms. This can slow down
- result list display significantly for big documents, and you
- may want to turn it off.</para>
- </listitem>
-
- <listitem><para><guilabel>Synthetic abstract size</guilabel>:
- adjust to taste...</para>
- </listitem>
-
- <listitem><para><guilabel>Synthetic abstract context
- words</guilabel>: how many words should be displayed around
- each term occurrence.</para>
- </listitem>
-
- <listitem><para><guilabel>Query language magic file name
- suffixes</guilabel>: a list of words which automatically get
- turned into <literal>ext:xxx</literal> file name suffix clauses
- when starting a query language query (ie: <literal>doc xls
- xlsx...</literal>). This will save some typing for people who
- use file types a lot when querying.</para>
- </listitem>
- </itemizedlist>
- </para>
- </formalpara>
-
- <formalpara id="rcl.search.custom.extradb">
- <title>External indexes:</title>
- <para>This panel will let you browse for additional indexes
- that you may want to search. External indexes are designated by
- their database directory (ie:
- <filename>/home/someothergui/.recoll/xapiandb</filename>,
- <filename>/usr/local/recollglobal/xapiandb</filename>).</para>
-
- <para>Once entered, the indexes will appear in the
- <guilabel>External indexes</guilabel> list, and you can
- chose which ones you want to use at any moment by checking or
- unchecking their entries.</para>
-
- <para>Your main database (the one the current configuration
- indexes to), is always implicitly active. If this is not
- desirable, you can set up your configuration so that it indexes,
- for example, an empty directory. An alternative indexer may also
- need to implement a way of purging the index from stale data,
- </para>
-
- <sect2 id="rcl.search.custom.reslistpara">
- <title>The result list paragraph format</title>
-
- <para>The presentation of each result inside the result list can be
- customized by setting the result list paragraph format inside the
- <guilabel>User Interface</guilabel> tab of the <guilabel>Query
- configuration</guilabel>.</para>
-
- <para>This is a Qt HTML string where the following printf-like
- <literal>%</literal> substitutions will be performed:
-
- <itemizedlist>
- <listitem>
- <formalpara><title>%A</title><para>Abstract</para></formalpara>
- </listitem>
- <listitem><formalpara><title>%D</title><para>Date</para></formalpara>
- </listitem>
- <listitem><formalpara><title>%I</title><para>Icon image name
- </para></formalpara>
- </listitem>
- <listitem><formalpara><title>%K</title><para>Keywords (if
- any)</para></formalpara>
- </listitem>
- <listitem><formalpara><title>%L</title><para>Preview and
- Edit links</para></formalpara>
- </listitem>
- <listitem><formalpara><title>%M</title><para>Mime
- type</para></formalpara>
- </listitem>
- <listitem><formalpara><title>%N</title><para>result Number
- </para></formalpara>
- </listitem>
- <listitem><formalpara><title>%R</title><para>Relevance
- percentage</para></formalpara>
- </listitem>
- <listitem><formalpara><title>%S</title><para>Size
- information</para></formalpara>
- </listitem>
- <listitem><formalpara><title>%T</title><para>Title</para>
- </formalpara>
- </listitem>
- <listitem><formalpara><title>%U</title><para>Url</para></formalpara>
- </listitem>
- </itemizedlist>
-
- The format of the Preview and Edit links is
- <literal><a href="P%N"></literal>
- and
- <literal><a href="E%N"></literal>
- where <replaceable>docnum</replaceable> (%N expands to the document
- number inside the result list).</para>
-
- <para>In addition to the predefined values above, all strings like
- <literal>%(fieldname)</literal> will be replaced by the value of
- the field named <literal>fieldname</literal> for this
- document. Only stored fields can be accessed in this way, the value
- of indexed but not stored fields is not known at this point in the
- search process (see <link linkend="rcl.program.fields">field
- configuration</link>). There are currently very few fields stored
- by default, apart from the values above (only
- <literal>author</literal>), so this feature will need some custom
- local configuration to be useful. For example, you could look at
- the fields for the document types of interest (use the right-click
- menu inside the preview window), and add what you want to the list
- of stored fields. A candidate example would be the
- <literal>recipient</literal> field which is generated by the
- message filters.</para>
-
- <para>The default value for the paragraph format string is:
- <programlisting><img src="%I" align="left">%R %S %L &nbsp;&nbsp;<b>%T</b><br>
-%M&nbsp;%D&nbsp;&nbsp;&nbsp;<i>%U</i>&nbsp;%i<br>
-%A %K
- </programlisting>
- You may, for example, try the following for a more web-like
- experience:
- <programlisting><u><b><a href="P%N">%T</a></b></u><br>
-%A<font color=#008000>%U - %S</font> - %L
- </programlisting>
- Or the clean looking:
- <programlisting><img src="%I" align="left">%L <font color="#900000">%R</font>
- <b>%T</b><br>%S
-<font color="#808080"><i>%U</i></font>
-<table bgcolor="#e0e0e0">
-<tr><td><div>%A</div></td></tr>
-</table>%K
- </programlisting>
- Note that the P%N link in the above paragraph makes the title a
- preview link.
- </para>
-
- <para>Due to the way the program handles right mouse clicks in the
- result list, if the custom formatting results in multiple
- paragraphs per result, right clicks will only work inside the first
- one.</para>
-
-
- </sect2>
- </sect1>
-
- </chapter>
-
- <chapter id="rcl.searchkio">
- <title>Searching with the KDE KIO slave</title>
-
- <sect1 id="rcl.searchkio.intro">
- <title>What's this</title>
-
- <para>The &RCL; KIO slave allows performing a &RCL; search
- by entering an appropriate URL in a KDE open dialog, or with an
- HTML-based interface displayed in
- <command>Konqueror</command>.</para>
-
- <para>The HTML-based interface is similar to the Qt-based
- interface, but slightly less powerful for now. Its advantage is
- that you can perform your search while staying fully within the
- KDE framework: drag and drop from the result list works normally
- and you have your normal choice of applications for opening
- files.</para>
-
- <para>The alternative interface uses a directory view of search
- results. Due to limitations in the current KIO slave interface,
- it is currently not obviously useful (to me).</para>
-
- <para>The interface is described in more detail inside a help
- file which you can access by entering
- <filename>recoll:/</filename> inside the
- <command>konqueror</command> URL line (this works only if the
- recoll KIO slave has been previously installed).</para>
-
-
- <para>The instructions for building this module are located in
- the source tree. See:
- <filename>kde/kio/recoll/00README.txt</filename></para>
- </sect1>
-
-
-
- <sect1 id="rcl.searchkio.searchabledocs">
- <title>Searchable documents</title>
-
- <para>As a sample application, the &RCL; KIO slave could allow
- preparing a set of HTML documents (for example a manual) so that
- they become their own search interface inside
- <command>konqueror</command>.</para>
-
- <para>This can be done by either explicitly inserting
- <literal><a href="recoll:/..."></literal> links
- around some document areas, or automatically by adding a
- very small <application>javascript</application> program to the
- documents, like the following example, which would initiate a search by
- double-clicking any term:</para>
-
- <programlisting><script language="JavaScript">
- function recollsearch() {
- var t = document.getSelection();
- window.location.href = 'recoll://search/query?qtp=a&p=0&q=' +
- encodeURIComponent(t);
- }
-</script>
- ....
-<body ondblclick="recollsearch()">
-
-</programlisting>
-
- </sect1>
-
- </chapter>
-
-
-
- <chapter id="rcl.searchkcl">
- <title>Searching on the command line</title>
-
- <para>There are several ways to obtain search results as a text
- stream, without a graphical interface:</para>
- <itemizedlist>
- <listitem><para>By passing option <literal>-t</literal> to the
- <command>recoll</command> program.</para>
- </listitem>
- <listitem><para>By using the <command>recollq</command> program.</para>
- </listitem>
- <listitem><para>By writing a custom
- <application>Python</application> program, using the
- <link linkend="rcl.program.api.python">Recoll Python API</link>.</para>
- </listitem>
- </itemizedlist>
-
- <para>The first two methods work in the same way and accept/need the same
- arguments (except for the additional <literal>-t</literal> to
- <command>recoll</command>). The query to be executed is specified
- as command line arguments.</para>
-
- <para><command>recollq</command> is not built by default. You can
- use the <filename>Makefile</filename> in the
- <filename>query</filename> directory to build it. This is a very
- simple program, and it will often be useful to taylor its output format
- to your needs.</para>
-
- <para><command>recollq</command> has a man page (not installed by
- default, look in the <filename>doc/man</filename> directory). The
- Usage string is as follows:</para>
-<programlisting>recollq [-o|-a|-f] <query string>
- Runs a recoll query and displays result lines.
- Default: will interpret the argument(s) as a query language string
- -o Emulate the gui simple search in ANY TERM mode
- -a Emulate the gui simple search in ALL TERMS mode
- -f Emulate the gui simple search in filename mode
-Common options:
- -c <configdir> : specify config directory, overriding $RECOLL_CONFDIR
- -d also dump file contents
- -n <cnt> limit the maximum number of results (0->no limit, default 2000)
- -b : basic. Just output urls, no mime types or titles
- -m : dump the whole document meta[] array
- -S fld : sort by field name
- -D : sort descending
-</programlisting>
-
- <para>Sample execution:</para>
-<programlisting>recollq 'ilur -nautique mime:text/html'
-Recoll query: ((((ilur:(wqf=11) OR ilurs) AND_NOT (nautique:(wqf=11)
- OR nautiques OR nautiqu OR nautiquement)) FILTER Ttext/html))
-4 results
-text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/comptes.html] [comptes.html] 18593 bytes
-text/html [file:///Users/uncrypted-dockes/projets/nautique/webnautique/articles/ilur1/index.html] [Constructio...
-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....
-</programlisting>
-
- </chapter>
+ </sect1> <!-- rcl.search.desktop -->
+
+ </chapter> <!-- Search -->
<chapter id="rcl.program">
<title>Programming interface</title>
@@ -2544,7 +2599,7 @@
<chapter id="rcl.install">
- <title>Installation</title>
+ <title>Installation and configuration</title>
<sect1 id="rcl.install.binary">
<title>Installing a binary copy</title>
@@ -3751,33 +3806,6 @@
</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>
</book>