recoll / Code / Diff of /src/README

Diff of /src/README [7f856f] .. [4741d2]

Switch to unified view


...

   Copyright (c) 2005 Jean-Francois Dockes

   This document introduces full text search notions and describes the
   installation and use of the Recoll application. It currently describes
   Recoll 1.12-1.13.

   [ Split HTML / Single HTML ]

     ----------------------------------------------------------------------

   Table of Contents

...

                2.3. Indexing configuration

                             2.3.1. The indexing configuration GUI

                2.4. Using Beagle WEB browser plugins

                2.5. Periodic indexing

                             2.5.1. Starting indexing

                             2.5.2. Using cron to automate indexing

                2.6. Real time indexing

   3. Searching with the Qt graphical user interface

                3.1. Simple search

...

                             3.11.3. Others

                3.12. Customizing the search interface

                             3.12.1. The result list paragraph format

   4. Searching with the KDE KIO slave

                4.1. What's this

                4.2. Searchable documents
...

                             6.3.2. Python interface

   7. Installation

                7.1. Installing a binary copy

                             7.1.1. Installing through a package system

                             7.1.2. Installing a prebuilt Recoll

...
   

   Recoll knows about quite a few different document types. The parameters
   for document types recognition and processing are set in configuration
   files Most file types, like HTML or word processing files, only hold one
   document. Some file types, like mail folder files, can hold many
   individually indexed documents.

   Recoll indexing processes plain text, HTML, openoffice and e-mail files
   internally (a few more actually).

   Other file types (ie: postscript, pdf, ms-word, rtf ...) need external
   applications for preprocessing. The list is in the installation section.
   After every indexing operation, Recoll updates a list of commands that
   would be needed for indexing existing files types. This list can be
...
   system to separate databases. You can do this by using multiple
   configuration directories, each indexing a file system area to a specific
   database. See the section about using multiple databases for more
   information on multiple configurations and indexes.

   In the rare case where the index becomes corrupted (which can signal
   itself by weird search results or crashes), the index files need to be
   erased before restarting a clean indexing pass. Just delete the xapiandb
   directory (see next section), or, alternatively, start the next
   recollindex with the -z option, which will reset the database before
   indexing.

     ----------------------------------------------------------------------

2.2. Index storage

   The default location for the index data is the xapiandb subdirectory of
...
       configuration section). This method would mainly be of use if you
       wanted to keep the configuration directory in its default location,
       but desired another location for the index, typically out of disk
       occupation concerns.

   The size of the index is determined by the document set size, but the
   ratio can vary a lot. For a typical mixed set of documents, the index size
   will often be close to the data set size. In specific cases (a set of
   compressed mbox files for example), the index can become much bigger than
   the documents. It may also be much smaller if the documents contain a lot
   of images or other non-indexed data (an extreme example being a set of mp3
   files where only the tags would be indexed).

   Of course, images, sound and video do not increase the index size, which
   means that it will be quite typical nowadays (2006), that even a big index
   will be negligible against the total amount of data on the computer.

...
   You can also use multiple indexes defined by separate configurations,
   typically to separate personal and shared indexes, or to take advantage of
   the organization of your data to improve search precision.

   The first time you start recoll, you will be asked whether or not you
   would like it to build the index. If you want to adjust the configuration
   before indexing, just click Cancel at this point, which will get you into
   the configuration interface. If you exit, recoll will have created a
   ~/.recoll directory containing empty configuration files, which you can
   edit by hand.

   The configuration is documented inside the installation chapter of this
   document, or in the recoll.conf(5) man page, but the most current
   information will most likely be the comments inside the sample file. The
   most immediately useful variable you may interested in is probably
...
   use it on hand-edited files, which you might nevertheless want to backup
   first...

     ----------------------------------------------------------------------

2.4. Using Beagle WEB browser plugins

   Beagle is a concurrent desktop indexer, built on Lucene and the Mono
   project (C#), for which a number of add-on browser plugins were written.
   These work by copying visited web pages to an indexing queue directory,
   which the indexer then processes.

   If, for any reason, you so happen to prefer Recoll to Beagle, you can
   still use the browser plugins (they are written in Javascript and
   completely independant of C#, Beagle, Lucene...). Recoll can process the
   Beagle queue directory. Of course, this supposes that Beagle is not
   running, else both programs will fight for the same files.

   This feature can be enabled in the GUI indexing configuration panel, or by
   editing the configuration file (set processbeaglequeue to 1).

     ----------------------------------------------------------------------

2.5. Periodic indexing

  2.5.1. Starting indexing

   Indexing is performed either by the recollindex program, or by the
   indexing thread inside the recoll program (use the File menu). Both
   programs will use the RECOLL_CONFDIR variable or accept a -c confdir
   option to specify a non-default configuration directory.

   If the recoll program finds no index when it starts, it will automatically
   start indexing (except if canceled).

   The indexing process can be interrupted by sending an interrupt (^C,
   SIGINT) or terminate (SIGTERM) signal. Some time may elapse before the
   process exits, because it needs to properly flush and close the index. The
   indexing will restart at the interruption point the next time (the full
   file tree will still be traversed, but files that were indexed up to the
   interruption and are still up to date will not need to be reindexed).


   After such an interruption, the index will be somewhat inconsistent
   because some operations which are normally performed at the end of the
   indexing pass will have been skipped (for exemple, the stemming and
   spelling databases will be inexistant or out of date). You just need to
   restart indexing at a later time to restore consistency.

     ----------------------------------------------------------------------

  2.5.2. Using cron to automate indexing

   The most common way to set up indexing is to have a cron task execute it
   every night. For example the following crontab entry would do it every day
   at 3:30AM (supposing recollindex is in your PATH):

 30 3 * * * recollindex > /some/tmp/dir/recolltrace 2>&1

   Or, using anacron:

 1  15  su mylogin -c "recollindex recollindex > /tmp/rcltraceme 2>&1"

   The usual command to edit your crontab is crontab -e (which will usually
   start the vi editor to edit the file). You may have more sophisticated
   tools available on your system.

     ----------------------------------------------------------------------

2.6. Real time indexing

   Real time monitoring/indexing is performed by starting the recollindex -m
   command. With this option, recollindex will detach from the terminal and
   become a daemon, permanently monitoring file changes and updating the
   index.
...

   The indexing daemon gets started, then the window manager, for which the
   session waits.

   By default the indexing daemon will monitor the state of the X11 session,
   and exit when it finishes, it is not necessary to kill it explicitly. (The
   X11 server monitoring can be disabled with option -x to recollindex).

   Under KDE, you can place a small script to start recollindex -m under
   $HOME/.kde/Autostart. This will be executed when the session begins.

   There is a similar mechanism under Gnome (find the session control tool in
   the menus and use the "Startup programs" tab).

   By default, the messages from the indexing daemon will be discarded. You
   may want to change this by setting the daemlogfilename and daemloglevel
   configuration parameters. Also the log file will only be truncated when
   the daemon starts. If the daemon runs permanently, the log file may grow
   quite big, depending on the log level.


   While it is convenient that data is indexed in real time, repeated
   indexing can generate a significant load on the system when files such as
   email folders change. Also, monitoring large file trees by itself
   significantly taxes system resources. You probably do not want to enable
...
   better scores). Any term will search for documents where at least one of
   the terms appear.

   File name will specifically look for file names. The entry will be split
   at white space characters, and each pattern will be separately expanded.
   If you want to search for a pattern including white space, use double
   quotes. The point of having a separate file name search is that wild card
   expansion can be performed more efficiently on a relatively small subset
   of the index.

   The fourth entry (Query Language) is described in its own section.

   All search modes allow wildcards inside terms (*, ?, []). You may want to
   have a look at the section about wildcards for more information about
...
   enclosing the input inside double quotes. Ex: "virtual reality".

   Character case has no influence on search, except that you can disable
   stem expansion for any term by capitalizing it. Ie: a search for floor
   will also normally look for flooring, floored, etc., but a search for
   Floor will only look for floor, in any character case. Stemming can also
   be disabled globally in the preferences.

   Recoll remembers the last few searches that you performed. You can use the
   simple search text entry widget (a combobox) to recall them (click on the
   thing at the right of the text field). Please note, however, that only the
...
   extracted from the database.

   Double-clicking on a word in the result list or a preview window will
   insert it into the simple search entry field.


   You can cut and paste any text into an All terms or Any term search field,
   punctuation, newlines and all - except for wildcard characters (single ?
   characters are ok). Recoll will process it and produce a meaningful
   search. This is what most differentiates this mode from the Query Language
   mode, where you have to care about the syntax.

   You can use the Tools / Advanced search dialog for more complex searches.

     ----------------------------------------------------------------------

...
   open tabs in the existing preview window. You can use Shift+Click to force
   the creation of another preview window, which may be useful to view the
   documents side by side. (You can also browse successive results in a
   single preview window by typing Shift+ArrowUp/Down in the window).

   Clicking the Open link will attempt to start an external viewer. The
   viewer for each document type can be configured through the user
   preferences dialog, or by editing the mimeview configuration file. You can
   also check the Use desktop preferences option in the user preferences
   dialog to use the desktop defaults for all documents. This is probably the
   best option if you are using a well configured Gnome or KDE desktop.

   The Preview and Open edit links may not be present for all entries,
   meaning that Recoll has no configured way to preview a given file type
   (which was indexed by name only), or no configured external editor for the
   file type. This can sometimes be adjusted simply by tweaking the mimemap
   and mimeview configuration files (the latter can be modified with the user
   preferences dialog).
...

     * Save to File

     * Find similar

     * Preview Parent document

     * Open Parent document

   The Preview and Edit entries do the same thing as the corresponding links.

   The Copy File Name and Copy Url copy the relevant data to the clipboard,
   for later pasting.
...
   The Find similar entry will select a number of relevant term from the
   current document and enter them into the simple search field. You can then
   start a simple search, with a good chance of finding documents related to
   the current result.

   The Parent document entries will appear for documents which are not
   actually files but are part of, or attached to, a higher level document.
   This entry is mainly useful for email attachments and permits viewing the
   message to which the document is attached. Note that the entry will also
   appear for an email which is part of an mbox folder file, but that you
   can't actually visualize the folder (there will be an error dialog if you
   try). Recoll is unfortunately not yet smart enough to disable the entry in
   this case. In other cases, the Open option makes sense, for exemple to
   start a chm viewer on the parent document for a help page.

     ----------------------------------------------------------------------

3.3. The preview window

...
   A right-click menu in the text area allows switching between displaying
   the main text or the contents of fields associated to the document (ie:
   author, abtract, etc.). This is especially useful in cases where the term
   match did not occur in the main text but in one of the fields.

   You can print the current preview window contents by typing ^P (Ctrl + P)
   in the window text.

     ----------------------------------------------------------------------

3.4. The query language

   The query language processor is activated on the simple search entry when
...

   You can use the show query link at the top of the result list to check the
   exact query which was finally executed by Xapian.

   Most Xesam phrase modifiers are unsupported, except for l (small ell) to
   disable stemming, and p to turn a phrase into a NEAR (unordered) search.
   Exemple: "prejudice pride"p

     ----------------------------------------------------------------------

3.5. Complex/advanced search
...
   Browsing the result list inside a preview window. Entering Shift-Down or
   Shift-Up (Shift + 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.

   Scrolling the result list from the keyboard. You can use PageUp and
   PageDown to scroll the result list, Shift+Home to go back to the first
   page. These work even while the focus is in the search entry.

   Forced opening of a preview window. You can use Shift+Click on a result
   list Preview link to force the creation of a preview window instead of a
   new tab in the existing one.

   Closing previews. Entering ^W in a tab will close it (and, for the last
   tab, close the preview window). Entering Esc will close the preview window
   and all its tabs.

   Printing previews. Entering ^P in a preview window will print the
   currently displayed text.

   Quitting. Entering ^Q almost anywhere will close the application.

     ----------------------------------------------------------------------

3.12. Customizing the search interface

   You can customize some aspects of the search interface by using the Query
   configuration entry in the Preferences menu.

   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.

   User interface parameters:

     * Number of results in a result page:

...
       result list, and you may want to customize the font and/or font size.
       The rest of the fonts used by Recoll are determined by your generic QT
       config (try the qtconfig command).

     * Result paragraph format string: allows you to change the presentation
       of each result list entry. This is described in its own section.


     * Maximum text size highlighted for preview 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.

     * Use desktop preferences to choose document editor: if this is checked,
       the xdg-open utility will be used to open files when you click the
       Edit link in the result list, instead of the application defined in
       mimeview. xdg-open will in term use your desktop preferences to choose
       an appropriate application.

     * Choose editor applications this will let you choose the command
       started by the Edit links inside the result list, for specific
       document types.

     * Display category filter as toolbar... this will let you choose if the
       document categories are displayed as a list or a set of buttons.

     * Auto-start simple search on white space entry: 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...

     * Start with advanced search dialog open and Start with sort dialog
       open: If you use these dialogs all the time, checking these entries
       will get them to open when recoll starts.

     * Remember sort activation state if set, Recoll will remember the sort
       tool stat between invocations. It normally starts with sorting
       disabled.

     * Prefer HTML to plain text for preview 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.

   Search parameters:

     * Stemming language: 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 main
       configuration file), or later added with recollindex -s (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.

     * Dynamically add phrase to simple searches: a phrase will be
       automatically built and added to simple searches when looking for Any
       terms. This will give a relevance boost to the results where the
       search terms appear as a phrase (consecutive and in order).

     * Replace abstracts from documents: this decides if we should synthesize
       and display an abstract in place of an explicit abstract found within
       the document itself.

     * Dynamically build abstracts: this decides if Recoll 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.

     * Replace abstracts from documents: this decides if we should synthesize
       and display an abstract in place of an explicit abstract found within
       the document itself.

     * Synthetic abstract size: adjust to taste...

     * Synthetic abstract context words: how many words should be displayed
       around each term occurrence.

   External indexes: This panel will let you browse for additional indexes
   that you may want to search. External indexes are designated by their
   database directory (ie: /home/someothergui/.recoll/xapiandb,
   /usr/local/recollglobal/xapiandb).

   Once entered, the indexes will appear in the External indexes list, and
   you can chose which ones you want to use at any moment by checking or
   unchecking their entries.

   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,

     ----------------------------------------------------------------------

  3.12.1. The result list paragraph format

   The presentation of each result inside the result list can be customized
   by setting the result list paragraph format inside the User Interface tab
   of the Query configuration.

   This is a Qt HTML string where the following printf-like % substitutions
   will be performed:

     * %A. Abstract

     * %D. Date

     * %I. Icon image name

     * %K. Keywords (if any)

     * %L. Preview and Edit links

     * %M. Mime type

     * %N. result Number

     * %R. Relevance percentage

     * %S. Size information

     * %T. Title

     * %U. Url

   The format of the Preview and Edit links is <a href="P%N"> and <a
   href="E%N"> where docnum (%N expands to the document number inside the
   result list).

   In addition to the predefined values above, all strings like %(fieldname)
   will be replaced by the value of the field named fieldname 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 field configuration). There are currently very few fields
   stored by default, apart from the values above (only author), 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
   recipient field which is generated by the message filters.

   The default value for the paragraph format string is:

 <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
       

   You may, for example, try the following for a more web-like experience:


 <u><b><a href="P%N">%T</a></b></u><br>
 %A<font color=#008000>%U - %S</font> - %L
       

   Or the clean looking:

 <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
       

   Note that the P%N link in the above paragraph makes the title a preview
   link.


   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.






























































     ----------------------------------------------------------------------

                  Chapter 4. Searching with the KDE KIO slave

...

 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....

     ----------------------------------------------------------------------

                        Chapter 6. Programming interface

...

   Recoll filters are executable programs which translate from a specific
   format (ie: openoffice, acrobat, etc.) to the Recoll indexing input
   format, which may be text/plain or text/html.

   As of Recoll 1.13, there are two kinds of filters:

     * Simple filters (the old ones) run once and exit. They can be bare
       programs like antiword, or shell-scripts using other programs. They
       are very simple to write, just having to write the text to the
       standard output.

     * Multiple filters, new in 1.13, run as long as their master process
       (ie: recollindex) is active. They can process multiple files (sparing
       the process startup time which can be very significant), or multiple
       documents per file (ie: for zip or chm files). They communicate with
       the indexer through a simple protocol, but are nevertheless a bit more
       complicated than the older kind. Most of these new filters are written
       in Python, using a common module to handle the protocol.

   The following will just describe the simple filters, if you are programmer
   enough to write one of the other kind, it shouldn't be too difficult to
   make sense of one of the existing modules (ie: rclzip).

   Recoll simple filters are usually shell-scripts, but this is in no way
   necessary. These programs are extremely simple and most of the difficulty
   lies in extracting the text from the native format, not outputting what is
   expected by Recoll. Happily enough, most document formats already have
   translators or text extractors which handle the difficult part and can be
   called from the filter. In some case the output of the translating program
   is appropriate, and no intermediate shell-script is needed.

...
   The association of file types to filters is performed in the mimeconf
   file. A sample:

 
[index]
 application/msword = exec antiword -t -i 1 -m UTF-8;\
      mimetype = text/plain ; charset=utf-8

 application/ogg = exec rclogg

 text/rtf = exec unrtf --nopict --html; charset=iso-8859-1; mimetype=text/html

 application/x-chm = execm rclchm

   The fragment specifies that:

     * application/msword files are processed by executing the antiword
       program, which outputs text/plain encoded in utf-8.

     * application/ogg files are processed by the rclogg script, with default
       output type (text/html, with encoding specified in the header, or
       utf-8 by default).

     * text/rtf is processed by unrtf, which outputs text/html. The
       iso-8859-1 encoding is specified because it is not the utf-8 default,
       and not output by unrtf in the HTML header section.

     * application/x-chm is processed by a persistant filter. This is
       determined by the execm keyword.

   The easiest way to write a new filter is probably to start from an
   existing one.

   Filters which output text/plain text are generally simpler, but they
...
   A field becomes indexed by having a prefix defined in the [prefixes]
   section of the fields file. See the comments in there for details

   A field becomes stored by appearing in the [stored] section of the fields
   file.

   See the comments inside the fields for more details.

     ----------------------------------------------------------------------

6.3. API

...

     ----------------------------------------------------------------------

                            Chapter 7. Installation

7.1. Installing a binary copy

   There are three types of binary Recoll installations:

     * Through your system normal software distribution framework (ie,
       Debian/Ubuntu apt, FreeBSD ports, etc.).

     * From a package downloaded from the Recoll web site.

     * From a prebuilt tree downloaded from the Recoll web site.

   In all cases, the strict software dependancies (ie on Xapian or iconv)
   will be automatically satisfied, you should not have to worry about them.

   You will only have to check or install supporting applications for the
   file types that you want to index beyond those that are natively processed
   by Recoll (text, HTML, mail files, and a few others).

   You should also maybe have a look at the configuration section (but this
   may not be necessary for a quick test with default parameters). Most
   parameters can be more conveniently set from the GUI interface.

     ----------------------------------------------------------------------

  7.1.1. Installing through a package system

   If you use a BSD-type port system or a prebuilt package (DEB, RPM,
   manually or through the system software configuration utility), just
   follow the usual procedure for your system.

     ----------------------------------------------------------------------

  7.1.2. Installing a prebuilt Recoll

...

7.2. Supporting packages

   Recoll uses external applications to index some file types. You need to
   install them for the file types that you wish to have indexed (these are
   run-time optional dependencies. None is needed for building or running
   Recoll except for indexing their specific file type).

   After an indexing pass, the commands that were found missing can be
   displayed from the recoll File menu. The list is stored in the missing
   text file inside the configuration directory.

...

     * dvi: dvips

     * djvu: DjVuLibre

     * mp3: Recoll will use the id3info command from the id3lib package to
       extract tag information. Without it, only the file names will be
       indexed.

     * flac files need metaflac.

     * ogg files need ogginfo.

     * Pictures: Recoll uses the Exiftool Perl package to extract tag
       information. Most image file formats are supported. Note that there
       may not be much interest in indexing the technical tags (image size,
       aperture, etc.). This is only of interest if you store personal tags
       or textual descriptions inside the image files.

     * chm: files in microsoft help format need Python and the pychm module
       (which needs chmlib).

     * ics: iCalendar files need Python and the icalendar module.

     * zip: Zip archives need Python (and the standard zipfile module).

   Text, HTML, mail folders, Openoffice and Scribus files are processed
   internally. Lyx is used to index Lyx files. Many filters need sed and awk.

     ----------------------------------------------------------------------

7.3. Building from source

  7.3.1. Prerequisites

   At the very least, you will need to download and install the xapian core
   package and the qt run-time and development packages. Check the Recoll
   download page for up to date version information.



   You will most probably be able to find a binary package for qt for your
   system. You may have to compile Xapian but this is not difficult (if you
   are using FreeBSD, there is a port).

...

     ----------------------------------------------------------------------

  7.3.2. Building

   Recoll has been built on Linux, FreeBSD, macosx, and Solaris, most
   versions after 2005 should be ok, maybe some older ones too (Solaris 8 is
   ok). If you build on another system, and need to modify things, I would
   very much welcome patches.

   Depending on the qt configuration on your system, you may have to set the
   QTDIR and QMAKESPECS variables in your environment:

     * QTDIR should point to the directory above the one that holds the qt
...

     * QMAKESPECS should be set to the name of one of the qt mkspecs
       sub-directories (ie: linux-g++).

   On many Linux systems, QTDIR is set by the login scripts, and QMAKESPECS
   is not needed because there is a default link in mkspecs/. Neither should
   be needed with Qt 4.

   Configure options:

     * --without-aspell will disable the code for phonetic matching of search
       terms.

     * --with-fam or --with-inotify will enable the code for real time
       indexing. Inotify support is enabled by default on recent Linux
       systems.

     * --enable-xattr will enable code to fetch data from file extended
       attributes. This is only useful is some application stores data in
       there, and also needs some simple configuration (see comments in the
       fields configuration file).

     * --with-file-command Specify the version of the 'file' command to use
       (ie: --with-file-command=/usr/local/bin/file). Can be useful to enable
       the gnu version on systems where the native one is bad.

     * --without-gui Disable the Qt interface, and auxiliary uses of X11, and
       compile the command line version.

   Normal procedure:

         cd recoll-xxx
         configure
         make
         (practices usual hardship-repelling invocations)
     

   There is little auto-configuration. The configure script will mainly link
   one of the system-specific files in the mk directory to mk/sysconf. If
   your system is not known yet, it will tell you as much, and you may want
   to manually copy and modify one of the existing files (the new file name
   should be the output of uname -s).

     ----------------------------------------------------------------------

  7.3.3. Installation
...
   The default configuration will index your home directory. If this is not
   appropriate, start recoll to create a blank configuration, click Cancel,
   and edit the configuration file before restarting the command. This will
   start the initial indexing, which may take some time.

   Paramers affecting what we index:

   topdirs

           Specifies the list of directories or files to index (recursively
           for directories). The indexer will not follow symbolic links
           inside the indexed trees by default (see the followLinks options
           though).









   skippedNames

           A space-separated list of patterns for names of files or
           directories that should be completely ignored. The list defined in
           the default file is:

 skippedNames = #* bin CVS  Cache cache* caughtspam  tmp .thumbnails .svn \
            *~ .beagle .git .hg .bzr loop.ps .xsession-errors \
            .recoll* xapiandb recollrc recoll.conf

           The list can be redefined at any sub-directory in the indexed
           area.

           The top-level directories are not affected by this list (that is,
           a directory in topdirs might match and would still be indexed).

           The list in the default configuration does not exclude hidden
...
           avoid multiple indexing of linked files. No effort is made to
           avoid duplication when this option is set to true. This option can
           be set individually for each of the topdirs members by using
           sections. It can not be changed below the topdirs level.

   indexedmimetypes

           Recoll normally indexes any file which it knows how to read. This
           list lets you restrict the indexed mime types to what you specify.
           If the variable is unspecified or the list empty (the default),
           all supported types are processed.

   compressedfilemaxkbs

           Size limit for compressed (.gz or .bz2) files. These need to be
           decompressed in a temporary directory for identification, which
           can be very wasteful if 'uninteresting' big compressed files are
           present. Negative means no limit, 0 means no processing of any
           compressed file. Defaults to -1.

   textfilemaxmbs

           Maximum size for text files. Very big text files are often
           uninteresting logs. Set to -1 to disable (default 20MB).

   textfilepagekbs

           If set to other than -1, text files will be indexed as multiple
           documents of the given page size. This may be useful if you do
           want to index very big text files as it will both reduce memory
           usage at index time and help with loading data to the preview
           window. A size of a few megabytes would seem reasonable (default:
           1MB).

   indexallfilenames

           Recoll indexes file names in a special section of the database to
           allow specific file names searches using wild cards. This
           parameter decides if file name indexing is performed only for
           files with mime types that would qualify them for full text
           indexing, or for all files inside the selected subtrees,
           independently of mime type.

   usesystemfilecommand

           Decide if we use the file -i system command as a final step for
           determining the mime type for a file (the main procedure uses
           suffix associations as defined in the mimemap file). This can be
           useful for files with suffix-less names, but it will also cause
           the indexing of many bogus "text" files.

   processbeaglequeue

           If this is set, process the directory where Beagle Web browser
           plugins copy visited pages for indexing. Of course, Beagle MUST
           NOT be running, else things will behave strangely.

   beaglequeuedir

           The path to the Beagle indexing queue. This is hard-coded in the
           Beagle plugin as ~/.beagle/ToIndex so there should be no need to
           change it.

   Parameters affecting where and how we store things:

   dbdir

           The name of the Xapian data directory. It will be created if
           needed when the index is initialized. If this is not an absolute
           path, it will be interpreted relative to the configuration
           directory. The value can have embedded spaces but starting or
           trailing spaces will be trimmed. You cannot use quotes here.

   maxfsoccuppc

           Maximum file system occupation before we stop indexing. The value
           is a percentage, corresponding to what the "Capacity" df output
           column shows. The default value is 0, meaning no checking.

   mboxcachedir

           The directory where mbox message offsets cache files are held.
           This is normally $RECOLL_CONFDIR/mboxcache, but it may be useful
           to share a directory between different configurations.

   mboxcacheminmbs

           The minimum mbox file size over which we cache the offsets. There
           is really no sense in caching offsets for small files. The default
           is 5 MB.

   webcachedir

           This is only used by the Beagle web browser plugin indexing code,
           and defines where the cache for visited pages will live. Default:
           $RECOLL_CONFDIR/webcache

   webcachemaxmbs

           This is only used by the Beagle web browser plugin indexing code,
           and defines the maximum size for the web page cache. Default: 40
           MB.

   idxflushmb

           Threshold (megabytes of new text data) where we flush from memory
           to disk index. Setting this can help control memory usage. A value
           of 0 means no explicit flushing, letting Xapian use its own
           default, which is flushing every 10000 documents (memory usage
           depends on average document size). The default value is 10.

   Miscellani:

   loglevel,daemloglevel

           Verbosity level for recoll and recollindex. A value of 4 lists
           quite a lot of debug/information messages. 2 only lists errors.
           The daemversion is specific to the indexing monitor daemon.
...
           character set definition (ie: plain text files). This can be
           redefined for any sub-directory. If it is not set at all, the
           character set used is the one defined by the nls environment
           (LC_ALL, LC_CTYPE, LANG), or iso8859-1 if nothing is set.

   filtermaxseconds

           Maximum filter execution time, after which it is aborted. Some
           postscript programs just loop...


   maildefcharset

           This can be used to define the default character set specifically
           for mail messages which don't specify it. This is mainly useful
           for readpst (libpst) dumps, which are utf-8 but do not say so.

   localfields

           This allows setting fields for all documents under a given
           directory. Typical usage would be to set an "rclaptg" field, to be
           used in mimeview to select a specific viewer. Ie:
           localfields=rclaptg=gnus;other=val, then select specifier viewer
           with mimetype|tag=... in mimeview.

   filtersdir

           A directory to search for the external filter scripts used to
           index some types of files. The value should not be changed, except
...

   iconsdir

           The name of the directory where recoll result list icons are
           stored. You can change this if you want different images.







































   idxabsmlen

           Recoll stores an abstract for each indexed file inside the
           database. The text can come from an actual 'abstract' section in
...
           This lets you adjust the size of n-grams used for indexing CJK
           text. The default value of 2 is probably appropriate in most
           cases. A value of 3 would allow more precision and efficiency on
           longer words, but the index will be approximately twice as large.

   guesscharset

           Decide if we try to guess the character set of files if no
           internal value is available (ie: for plain text files). This does
           not work well in general, and should probably not be used.

     ----------------------------------------------------------------------

  7.4.2. The mimemap file

   mimemap specifies the file name extension to mime type mappings.
...
   non-default entries, which will override those from the central
   configuration file.

   Please note that these entries must be placed under a [view] section.

   The keys in the file are normally mime types. You can add an application
   tag to specialize the choice for an area of the filesystem (using a
   localfields specification in mimeconf). The syntax for the key is
   mimetype|tag

   If Use desktop preferences to choose document editor is checked in the
   user preferences, all mimeview entries will be ignored except the one
   labelled application/x-all (which is set to use xdg-open by default).

     ----------------------------------------------------------------------

	a/src/README		b/src/README
	...		...
10		10
11	Copyright (c) 2005 Jean-Francois Dockes	11	Copyright (c) 2005 Jean-Francois Dockes
12		12
13	This document introduces full text search notions and describes the	13	This document introduces full text search notions and describes the
14	installation and use of the Recoll application. It currently describes	14	installation and use of the Recoll application. It currently describes
15	Recoll 1.12.	15	Recoll 1.12-1.13.
		16
		17	[ Split HTML / Single HTML ]
16		18
17	----------------------------------------------------------------------	19	----------------------------------------------------------------------
18		20
19	Table of Contents	21	Table of Contents
20		22
	...		...
38		40
39	2.3. Indexing configuration	41	2.3. Indexing configuration
40		42
41	2.3.1. The indexing configuration GUI	43	2.3.1. The indexing configuration GUI
42		44
		45	2.4. Using Beagle WEB browser plugins
		46
43	2.4. Periodic indexing	47	2.5. Periodic indexing
44		48
45	2.4.1. Starting indexing	49	2.5.1. Starting indexing
46		50
47	2.4.2. Using cron to automate indexing	51	2.5.2. Using cron to automate indexing
48		52
49	2.5. Real time indexing	53	2.6. Real time indexing
50		54
51	3. Searching with the Qt graphical user interface	55	3. Searching with the Qt graphical user interface
52		56
53	3.1. Simple search	57	3.1. Simple search
54		58
	...		...
80		84
81	3.11.3. Others	85	3.11.3. Others
82		86
83	3.12. Customizing the search interface	87	3.12. Customizing the search interface
84		88
		89	3.12.1. The result list paragraph format
		90
85	4. Searching with the KDE KIO slave	91	4. Searching with the KDE KIO slave
86		92
87	4.1. What's this	93	4.1. What's this
88		94
89	4.2. Searchable documents	95	4.2. Searchable documents
	...		...
104		110
105	6.3.2. Python interface	111	6.3.2. Python interface
106		112
107	7. Installation	113	7. Installation
108		114
109	7.1. Installing a prebuilt copy	115	7.1. Installing a binary copy
110		116
111	7.1.1. Installing through a package system	117	7.1.1. Installing through a package system
112		118
113	7.1.2. Installing a prebuilt Recoll	119	7.1.2. Installing a prebuilt Recoll
114		120
	...		...
271		277
272		278
273	Recoll knows about quite a few different document types. The parameters	279	Recoll knows about quite a few different document types. The parameters
274	for document types recognition and processing are set in configuration	280	for document types recognition and processing are set in configuration
275	files Most file types, like HTML or word processing files, only hold one	281	files Most file types, like HTML or word processing files, only hold one
276	document. Some file types, like mail folder files can hold many	282	document. Some file types, like mail folder files, can hold many
277	individually indexed documents.	283	individually indexed documents.
278		284
279	Recoll indexing processes plain text, HTML, openoffice and e-mail files	285	Recoll indexing processes plain text, HTML, openoffice and e-mail files
280	internally.	286	internally (a few more actually).
281		287
282	Other file types (ie: postscript, pdf, ms-word, rtf ...) need external	288	Other file types (ie: postscript, pdf, ms-word, rtf ...) need external
283	applications for preprocessing. The list is in the installation section.	289	applications for preprocessing. The list is in the installation section.
284	After every indexing operation, Recoll updates a list of commands that	290	After every indexing operation, Recoll updates a list of commands that
285	would be needed for indexing existing files types. This list can be	291	would be needed for indexing existing files types. This list can be
	...		...
293	system to separate databases. You can do this by using multiple	299	system to separate databases. You can do this by using multiple
294	configuration directories, each indexing a file system area to a specific	300	configuration directories, each indexing a file system area to a specific
295	database. See the section about using multiple databases for more	301	database. See the section about using multiple databases for more
296	information on multiple configurations and indexes.	302	information on multiple configurations and indexes.
297		303
		304	In the rare case where the index becomes corrupted (which can signal
		305	itself by weird search results or crashes), the index files need to be
		306	erased before restarting a clean indexing pass. Just delete the xapiandb
		307	directory (see next section), or, alternatively, start the next
		308	recollindex with the -z option, which will reset the database before
		309	indexing.
		310
298	----------------------------------------------------------------------	311	----------------------------------------------------------------------
299		312
300	2.2. Index storage	313	2.2. Index storage
301		314
302	The default location for the index data is the xapiandb subdirectory of	315	The default location for the index data is the xapiandb subdirectory of
	...		...
327	configuration section). This method would mainly be of use if you	340	configuration section). This method would mainly be of use if you
328	wanted to keep the configuration directory in its default location,	341	wanted to keep the configuration directory in its default location,
329	but desired another location for the index, typically out of disk	342	but desired another location for the index, typically out of disk
330	occupation concerns.	343	occupation concerns.
331		344
332	The size of the index is determined by the size of the set of documents,	345	The size of the index is determined by the document set size, but the
333	but the ratio can vary a lot. For a typical mixed set of documents, the	346	ratio can vary a lot. For a typical mixed set of documents, the index size
334	index size will often be close to the data set size. In specific cases (a	347	will often be close to the data set size. In specific cases (a set of
335	set of compressed mbox files for example), the index can become much	348	compressed mbox files for example), the index can become much bigger than
336	bigger than the documents. It may also be much smaller if the documents	349	the documents. It may also be much smaller if the documents contain a lot
337	contain a lot of images or other non-indexed data (an extreme example	350	of images or other non-indexed data (an extreme example being a set of mp3
338	being a set of mp3 files where only the tags would be indexed).	351	files where only the tags would be indexed).
339		352
340	Of course, images, sound and video do not increase the index size, which	353	Of course, images, sound and video do not increase the index size, which
341	means that it will be quite typical nowadays (2006), that even a big index	354	means that it will be quite typical nowadays (2006), that even a big index
342	will be negligible against the total amount of data on the computer.	355	will be negligible against the total amount of data on the computer.
343		356
	...		...
403	You can also use multiple indexes defined by separate configurations,	416	You can also use multiple indexes defined by separate configurations,
404	typically to separate personal and shared indexes, or to take advantage of	417	typically to separate personal and shared indexes, or to take advantage of
405	the organization of your data to improve search precision.	418	the organization of your data to improve search precision.
406		419
407	The first time you start recoll, you will be asked whether or not you	420	The first time you start recoll, you will be asked whether or not you
408	would like recoll to build the index. If you want to adjust the	421	would like it to build the index. If you want to adjust the configuration
409	configuration before indexing, just click Cancel at this point. That way,	422	before indexing, just click Cancel at this point, which will get you into
410	recoll will have created a ~/.recoll directory containing empty	423	the configuration interface. If you exit, recoll will have created a
411	configuration files.	424	~/.recoll directory containing empty configuration files, which you can
		425	edit by hand.
412		426
413	The configuration is documented inside the installation chapter of this	427	The configuration is documented inside the installation chapter of this
414	document, or in the recoll.conf(5) man page, but the most current	428	document, or in the recoll.conf(5) man page, but the most current
415	information will most likely be the comments inside the sample file. The	429	information will most likely be the comments inside the sample file. The
416	most immediately useful variable you may interested in is probably	430	most immediately useful variable you may interested in is probably
	...		...
445	use it on hand-edited files, which you might nevertheless want to backup	459	use it on hand-edited files, which you might nevertheless want to backup
446	first...	460	first...
447		461
448	----------------------------------------------------------------------	462	----------------------------------------------------------------------
449		463
		464	2.4. Using Beagle WEB browser plugins
		465
		466	Beagle is a concurrent desktop indexer, built on Lucene and the Mono
		467	project (C#), for which a number of add-on browser plugins were written.
		468	These work by copying visited web pages to an indexing queue directory,
		469	which the indexer then processes.
		470
		471	If, for any reason, you so happen to prefer Recoll to Beagle, you can
		472	still use the browser plugins (they are written in Javascript and
		473	completely independant of C#, Beagle, Lucene...). Recoll can process the
		474	Beagle queue directory. Of course, this supposes that Beagle is not
		475	running, else both programs will fight for the same files.
		476
		477	This feature can be enabled in the GUI indexing configuration panel, or by
		478	editing the configuration file (set processbeaglequeue to 1).
		479
		480	----------------------------------------------------------------------
		481
450	2.4. Periodic indexing	482	2.5. Periodic indexing
451		483
452	2.4.1. Starting indexing	484	2.5.1. Starting indexing
453		485
454	Indexing is performed either by the recollindex program, or by the	486	Indexing is performed either by the recollindex program, or by the
455	indexing thread inside the recoll program (use the File menu). Both	487	indexing thread inside the recoll program (use the File menu). Both
456	programs will use the RECOLL_CONFDIR variable or accept a -c confdir	488	programs will use the RECOLL_CONFDIR variable or accept a -c confdir
457	option to specify a non-default configuration directory.	489	option to specify a non-default configuration directory.
458		490
459	If the recoll program finds no index when it starts, it will automatically	491	If the recoll program finds no index when it starts, it will automatically
460	start indexing (except if canceled).	492	start indexing (except if canceled).
461		493
462	It is best to avoid interrupting the indexing process, as this may	494	The indexing process can be interrupted by sending an interrupt (^C,
463	sometimes leave the index in a bad state. This is not a serious problem,	495	SIGINT) or terminate (SIGTERM) signal. Some time may elapse before the
464	as you then just need to delete the index files and restart the indexing.	496	process exits, because it needs to properly flush and close the index. The
465	The index files are normally stored in the $HOME/.recoll/xapiandb	497	indexing will restart at the interruption point the next time (the full
466	directory, which you can just delete if needed. Alternatively, you can	498	file tree will still be traversed, but files that were indexed up to the
467	start recollindex with option -z, which will reset the database before	499	interruption and are still up to date will not need to be reindexed).
468	indexing.
469		500
470	----------------------------------------------------------------------	501	After such an interruption, the index will be somewhat inconsistent
		502	because some operations which are normally performed at the end of the
		503	indexing pass will have been skipped (for exemple, the stemming and
		504	spelling databases will be inexistant or out of date). You just need to
		505	restart indexing at a later time to restore consistency.
471		506
		507	----------------------------------------------------------------------
		508
472	2.4.2. Using cron to automate indexing	509	2.5.2. Using cron to automate indexing
473		510
474	The most common way to set up indexing is to have a cron task execute it	511	The most common way to set up indexing is to have a cron task execute it
475	every night. For example the following crontab entry would do it every day	512	every night. For example the following crontab entry would do it every day
476	at 3:30AM (supposing recollindex is in your PATH):	513	at 3:30AM (supposing recollindex is in your PATH):
477		514
478	30 3 * * * recollindex > /tmp/recolltrace 2>&1	515	30 3 * * * recollindex > /some/tmp/dir/recolltrace 2>&1
		516
		517	Or, using anacron:
		518
		519	1 15 su mylogin -c "recollindex recollindex > /tmp/rcltraceme 2>&1"
479		520
480	The usual command to edit your crontab is crontab -e (which will usually	521	The usual command to edit your crontab is crontab -e (which will usually
481	start the vi editor to edit the file). You may have more sophisticated	522	start the vi editor to edit the file). You may have more sophisticated
482	tools available on your system.	523	tools available on your system.
483		524
484	----------------------------------------------------------------------	525	----------------------------------------------------------------------
485		526
486	2.5. Real time indexing	527	2.6. Real time indexing
487		528
488	Real time monitoring/indexing is performed by starting the recollindex -m	529	Real time monitoring/indexing is performed by starting the recollindex -m
489	command. With this option, recollindex will detach from the terminal and	530	command. With this option, recollindex will detach from the terminal and
490	become a daemon, permanently monitoring file changes and updating the	531	become a daemon, permanently monitoring file changes and updating the
491	index.	532	index.
	...		...
511		552
512	The indexing daemon gets started, then the window manager, for which the	553	The indexing daemon gets started, then the window manager, for which the
513	session waits.	554	session waits.
514		555
515	By default the indexing daemon will monitor the state of the X11 session,	556	By default the indexing daemon will monitor the state of the X11 session,
516	and exit when it finishes, it is not necessary to kill it explicitly.	557	and exit when it finishes, it is not necessary to kill it explicitly. (The
517	(The X11 server monitoring can be disabled with option -x to recollindex).	558	X11 server monitoring can be disabled with option -x to recollindex).
518		559
519	Under KDE, you can place a small script to start recollindex -m under	560	Under KDE, you can place a small script to start recollindex -m under
520	$HOME/.kde/Autostart. This will be executed when the session begins.	561	$HOME/.kde/Autostart. This will be executed when the session begins.
521		562
522	There is a similar mechanism under Gnome (find the session control tool in	563	There is a similar mechanism under Gnome (find the session control tool in
523	the menus and use the "Startup programs" tab).	564	the menus and use the "Startup programs" tab).
524		565
525	By default, the indexing daemon will write its messages to a file inside	566	By default, the messages from the indexing daemon will be discarded. You
526	the configuration directory (this is controlled by the daemlogfilename and	567	may want to change this by setting the daemlogfilename and daemloglevel
527	daemloglevel configuration parameters). You may want to change this. Also	568	configuration parameters. Also the log file will only be truncated when
528	the log file will only be truncated when the daemon starts. If the daemon	569	the daemon starts. If the daemon runs permanently, the log file may grow
529	runs permanently, the log file may grow quite big, depending on the log	570	quite big, depending on the log level.
530	level.
531		571
532	While it is convenient that data is indexed in real time, repeated	572	While it is convenient that data is indexed in real time, repeated
533	indexing can generate a significant load on the system when files such as	573	indexing can generate a significant load on the system when files such as
534	email folders change. Also, monitoring large file trees by itself	574	email folders change. Also, monitoring large file trees by itself
535	significantly taxes system resources. You probably do not want to enable	575	significantly taxes system resources. You probably do not want to enable
	...		...
582	better scores). Any term will search for documents where at least one of	622	better scores). Any term will search for documents where at least one of
583	the terms appear.	623	the terms appear.
584		624
585	File name will specifically look for file names. The entry will be split	625	File name will specifically look for file names. The entry will be split
586	at white space characters, and each pattern will be separately expanded.	626	at white space characters, and each pattern will be separately expanded.
587	If you want to search for a pattern including white space, you need to use	627	If you want to search for a pattern including white space, use double
588	double quotes. The point of having a separate file name search is that	628	quotes. The point of having a separate file name search is that wild card
589	wild card expansion can be performed more efficiently on a relatively	629	expansion can be performed more efficiently on a relatively small subset
590	small subset of the index.	630	of the index.
591		631
592	The fourth entry (Query Language) is described in its own section.	632	The fourth entry (Query Language) is described in its own section.
593		633
594	All search modes allow wildcards inside terms (*, ?, []). You may want to	634	All search modes allow wildcards inside terms (*, ?, []). You may want to
595	have a look at the section about wildcards for more information about	635	have a look at the section about wildcards for more information about
	...		...
599	enclosing the input inside double quotes. Ex: "virtual reality".	639	enclosing the input inside double quotes. Ex: "virtual reality".
600		640
601	Character case has no influence on search, except that you can disable	641	Character case has no influence on search, except that you can disable
602	stem expansion for any term by capitalizing it. Ie: a search for floor	642	stem expansion for any term by capitalizing it. Ie: a search for floor
603	will also normally look for flooring, floored, etc., but a search for	643	will also normally look for flooring, floored, etc., but a search for
604	Floor will only look for floor, in any character case. Sstemming can also	644	Floor will only look for floor, in any character case. Stemming can also
605	be disabled globally in the preferences.	645	be disabled globally in the preferences.
606		646
607	Recoll remembers the last few searches that you performed. You can use the	647	Recoll remembers the last few searches that you performed. You can use the
608	simple search text entry widget (a combobox) to recall them (click on the	648	simple search text entry widget (a combobox) to recall them (click on the
609	thing at the right of the text field). Please note, however, that only the	649	thing at the right of the text field). Please note, however, that only the
	...		...
614	extracted from the database.	654	extracted from the database.
615		655
616	Double-clicking on a word in the result list or a preview window will	656	Double-clicking on a word in the result list or a preview window will
617	insert it into the simple search entry field.	657	insert it into the simple search entry field.
618		658
619	Note that, apart from wildcard characters (single ? characters are ok),
620	you can cut and paste any text into an All terms or Any term search field,	659	You can cut and paste any text into an All terms or Any term search field,
621	punctuation, newlines and all. Recoll will process it and produce a	660	punctuation, newlines and all - except for wildcard characters (single ?
		661	characters are ok). Recoll will process it and produce a meaningful
622	meaningful search. This is what most differentiates this mode from the	662	search. This is what most differentiates this mode from the Query Language
623	Query Language mode, where you have to care about the syntax.	663	mode, where you have to care about the syntax.
624		664
625	You can use the Tools / Advanced search dialog for more complex searches.	665	You can use the Tools / Advanced search dialog for more complex searches.
626		666
627	----------------------------------------------------------------------	667	----------------------------------------------------------------------
628		668
	...		...
640	open tabs in the existing preview window. You can use Shift+Click to force	680	open tabs in the existing preview window. You can use Shift+Click to force
641	the creation of another preview window, which may be useful to view the	681	the creation of another preview window, which may be useful to view the
642	documents side by side. (You can also browse successive results in a	682	documents side by side. (You can also browse successive results in a
643	single preview window by typing Shift+ArrowUp/Down in the window).	683	single preview window by typing Shift+ArrowUp/Down in the window).
644		684
645	Clicking the Edit link will attempt to start an external editor. The	685	Clicking the Open link will attempt to start an external viewer. The
646	editors can be configured through the user preferences dialog, or by	686	viewer for each document type can be configured through the user
647	editing the mimeview configuration file.	687	preferences dialog, or by editing the mimeview configuration file. You can
		688	also check the Use desktop preferences option in the user preferences
		689	dialog to use the desktop defaults for all documents. This is probably the
		690	best option if you are using a well configured Gnome or KDE desktop.
648		691
649	The Preview and Edit edit links may not be present for all entries,	692	The Preview and Open edit links may not be present for all entries,
650	meaning that Recoll has no configured way to preview a given file type	693	meaning that Recoll has no configured way to preview a given file type
651	(which was indexed by name only), or no configured external editor for the	694	(which was indexed by name only), or no configured external editor for the
652	file type. This can sometimes be adjusted simply by tweaking the mimemap	695	file type. This can sometimes be adjusted simply by tweaking the mimemap
653	and mimeview configuration files (the latter can be modified with the user	696	and mimeview configuration files (the latter can be modified with the user
654	preferences dialog).	697	preferences dialog).
	...		...
685		728
686	* Save to File	729	* Save to File
687		730
688	* Find similar	731	* Find similar
689		732
		733	* Preview Parent document
		734
690	* Parent document	735	* Open Parent document
691		736
692	The Preview and Edit entries do the same thing as the corresponding links.	737	The Preview and Edit entries do the same thing as the corresponding links.
693		738
694	The Copy File Name and Copy Url copy the relevant data to the clipboard,	739	The Copy File Name and Copy Url copy the relevant data to the clipboard,
695	for later pasting.	740	for later pasting.
	...		...
703	The Find similar entry will select a number of relevant term from the	748	The Find similar entry will select a number of relevant term from the
704	current document and enter them into the simple search field. You can then	749	current document and enter them into the simple search field. You can then
705	start a simple search, with a good chance of finding documents related to	750	start a simple search, with a good chance of finding documents related to
706	the current result.	751	the current result.
707		752
708	The Parent document entry will appear for documents which are not actually	753	The Parent document entries will appear for documents which are not
709	files but are part of, or attached to, a higher level document. This entry	754	actually files but are part of, or attached to, a higher level document.
710	is mainly useful for email attachments and permits viewing the message to	755	This entry is mainly useful for email attachments and permits viewing the
711	which the document is attached. Note that the entry will also appear for	756	message to which the document is attached. Note that the entry will also
712	an email which is part of an mbox folder file, but that you can't actually	757	appear for an email which is part of an mbox folder file, but that you
713	visualize the folder (there will be an error dialog if you try). Recoll is	758	can't actually visualize the folder (there will be an error dialog if you
714	unfortunately not yet smart enough to disable the entry in this case.	759	try). Recoll is unfortunately not yet smart enough to disable the entry in
		760	this case. In other cases, the Open option makes sense, for exemple to
		761	start a chm viewer on the parent document for a help page.
715		762
716	----------------------------------------------------------------------	763	----------------------------------------------------------------------
717		764
718	3.3. The preview window	765	3.3. The preview window
719		766
	...		...
752	A right-click menu in the text area allows switching between displaying	799	A right-click menu in the text area allows switching between displaying
753	the main text or the contents of fields associated to the document (ie:	800	the main text or the contents of fields associated to the document (ie:
754	author, abtract, etc.). This is especially useful in cases where the term	801	author, abtract, etc.). This is especially useful in cases where the term
755	match did not occur in the main text but in one of the fields.	802	match did not occur in the main text but in one of the fields.
756		803
		804	You can print the current preview window contents by typing ^P (Ctrl + P)
		805	in the window text.
		806
757	----------------------------------------------------------------------	807	----------------------------------------------------------------------
758		808
759	3.4. The query language	809	3.4. The query language
760		810
761	The query language processor is activated on the simple search entry when	811	The query language processor is activated on the simple search entry when
	...		...
846		896
847	You can use the show query link at the top of the result list to check the	897	You can use the show query link at the top of the result list to check the
848	exact query which was finally executed by Xapian.	898	exact query which was finally executed by Xapian.
849		899
850	Most Xesam phrase modifiers are unsupported, except for l (small ell) to	900	Most Xesam phrase modifiers are unsupported, except for l (small ell) to
851	disable stemming, and p to turn an phrase into a NEAR (unordered) search.	901	disable stemming, and p to turn a phrase into a NEAR (unordered) search.
852	Exemple: "prejudice pride"p	902	Exemple: "prejudice pride"p
853		903
854	----------------------------------------------------------------------	904	----------------------------------------------------------------------
855		905
856	3.5. Complex/advanced search	906	3.5. Complex/advanced search
	...		...
1160	Browsing the result list inside a preview window. Entering Shift-Down or	1210	Browsing the result list inside a preview window. Entering Shift-Down or
1161	Shift-Up (Shift + an arrow key) in a preview window will display the next	1211	Shift-Up (Shift + an arrow key) in a preview window will display the next
1162	or the previous document from the result list. Any secondary search	1212	or the previous document from the result list. Any secondary search
1163	currently active will be executed on the new document.	1213	currently active will be executed on the new document.
1164		1214
		1215	Scrolling the result list from the keyboard. You can use PageUp and
		1216	PageDown to scroll the result list, Shift+Home to go back to the first
		1217	page. These work even while the focus is in the search entry.
		1218
1165	Forced opening of a preview window. You can use Shift+Click on a result	1219	Forced opening of a preview window. You can use Shift+Click on a result
1166	list Preview link to force the creation of a preview window instead of a	1220	list Preview link to force the creation of a preview window instead of a
1167	new tab in the existing one.	1221	new tab in the existing one.
1168		1222
1169	Closing previews. Entering ^W in a tab will close it (and, for the last	1223	Closing previews. Entering ^W in a tab will close it (and, for the last
1170	tab, close the preview window). Entering Esc will close the preview window	1224	tab, close the preview window). Entering Esc will close the preview window
1171	and all its tabs.	1225	and all its tabs.
1172		1226
		1227	Printing previews. Entering ^P in a preview window will print the
		1228	currently displayed text.
		1229
1173	Quitting. Entering ^Q almost anywhere will close the application.	1230	Quitting. Entering ^Q almost anywhere will close the application.
1174		1231
1175	----------------------------------------------------------------------	1232	----------------------------------------------------------------------
1176		1233
1177	3.12. Customizing the search interface	1234	3.12. Customizing the search interface
1178		1235
1179	It is possible to customize some aspects of the search interface by using	1236	You can customize some aspects of the search interface by using the Query
1180	Query configuration entry in the Preferences menu.	1237	configuration entry in the Preferences menu.
1181		1238
1182	There are two tabs in the dialog, dealing with the interface itself, and	1239	There are several tabs in the dialog, dealing with the interface itself,
1183	with the parameters used for searching and returning results.	1240	the parameters used for searching and returning results, and what indexes
		1241	are searched.
1184		1242
1185	User interface parameters:	1243	User interface parameters:
1186		1244
1187	* Number of results in a result page:	1245	* Number of results in a result page:
1188		1246
	...		...
1198	result list, and you may want to customize the font and/or font size.	1256	result list, and you may want to customize the font and/or font size.
1199	The rest of the fonts used by Recoll are determined by your generic QT	1257	The rest of the fonts used by Recoll are determined by your generic QT
1200	config (try the qtconfig command).	1258	config (try the qtconfig command).
1201		1259
1202	* Result paragraph format string: allows you to change the presentation	1260	* Result paragraph format string: allows you to change the presentation
1203	of each result list entry. This is a qt-html string where the	1261	of each result list entry. This is described in its own section.
1204	following printf-like % substitutions will be performed:
1205		1262
		1263	* Maximum text size highlighted for preview Inserting highlights on
		1264	search term inside the text before inserting it in the preview window
		1265	involves quite a lot of processing, and can be disabled over the given
		1266	text size to speed up loading.
		1267
		1268	* Use desktop preferences to choose document editor: if this is checked,
		1269	the xdg-open utility will be used to open files when you click the
		1270	Edit link in the result list, instead of the application defined in
		1271	mimeview. xdg-open will in term use your desktop preferences to choose
		1272	an appropriate application.
		1273
		1274	* Choose editor applications this will let you choose the command
		1275	started by the Edit links inside the result list, for specific
		1276	document types.
		1277
		1278	* Display category filter as toolbar... this will let you choose if the
		1279	document categories are displayed as a list or a set of buttons.
		1280
		1281	* Auto-start simple search on white space entry: if this is checked, a
		1282	search will be executed each time you enter a space in the simple
		1283	search input field. This lets you look at the result list as you enter
		1284	new terms. This is off by default, you may like it or not...
		1285
		1286	* Start with advanced search dialog open and Start with sort dialog
		1287	open: If you use these dialogs all the time, checking these entries
		1288	will get them to open when recoll starts.
		1289
		1290	* Remember sort activation state if set, Recoll will remember the sort
		1291	tool stat between invocations. It normally starts with sorting
		1292	disabled.
		1293
		1294	* Prefer HTML to plain text for preview if set, Recoll will display HTML
		1295	as such inside the preview window. If this causes problems with the Qt
		1296	HTML display, you can uncheck it to display the plain text version
		1297	instead.
		1298
		1299	Search parameters:
		1300
		1301	* Stemming language: stemming obviously depends on the document's
		1302	language. This listbox will let you chose among the stemming databases
		1303	which were built during indexing (this is set in the main
		1304	configuration file), or later added with recollindex -s (See the
		1305	recollindex manual). Stemming languages which are dynamically added
		1306	will be deleted at the next indexing pass unless they are also added
		1307	in the configuration file.
		1308
		1309	* Dynamically add phrase to simple searches: a phrase will be
		1310	automatically built and added to simple searches when looking for Any
		1311	terms. This will give a relevance boost to the results where the
		1312	search terms appear as a phrase (consecutive and in order).
		1313
		1314	* Replace abstracts from documents: this decides if we should synthesize
		1315	and display an abstract in place of an explicit abstract found within
		1316	the document itself.
		1317
		1318	* Dynamically build abstracts: this decides if Recoll tries to build
		1319	document abstracts when displaying the result list. Abstracts are
		1320	constructed by taking context from the document information, around
		1321	the search terms. This can slow down result list display significantly
		1322	for big documents, and you may want to turn it off.
		1323
		1324	* Replace abstracts from documents: this decides if we should synthesize
		1325	and display an abstract in place of an explicit abstract found within
		1326	the document itself.
		1327
		1328	* Synthetic abstract size: adjust to taste...
		1329
		1330	* Synthetic abstract context words: how many words should be displayed
		1331	around each term occurrence.
		1332
		1333	External indexes: This panel will let you browse for additional indexes
		1334	that you may want to search. External indexes are designated by their
		1335	database directory (ie: /home/someothergui/.recoll/xapiandb,
		1336	/usr/local/recollglobal/xapiandb).
		1337
		1338	Once entered, the indexes will appear in the External indexes list, and
		1339	you can chose which ones you want to use at any moment by checking or
		1340	unchecking their entries.
		1341
		1342	Your main database (the one the current configuration indexes to), is
		1343	always implicitly active. If this is not desirable, you can set up your
		1344	configuration so that it indexes, for example, an empty directory. An
		1345	alternative indexer may also need to implement a way of purging the index
		1346	from stale data,
		1347
		1348	----------------------------------------------------------------------
		1349
		1350	3.12.1. The result list paragraph format
		1351
		1352	The presentation of each result inside the result list can be customized
		1353	by setting the result list paragraph format inside the User Interface tab
		1354	of the Query configuration.
		1355
		1356	This is a Qt HTML string where the following printf-like % substitutions
		1357	will be performed:
		1358
1206	* %A. Abstract	1359	* %A. Abstract
1207		1360
1208	* %D. Date	1361	* %D. Date
1209		1362
1210	* %I. Icon image name	1363	* %I. Icon image name