--- a/src/INSTALL
+++ b/src/INSTALL
@@ -11,21 +11,19 @@
--------------------------------------------------------------------------
- Chapter 7. Installation
+ Chapter 5. Installation and configuration
Table of Contents
- 7.1. Installing a binary copy
-
- 7.2. Supporting packages
-
- 7.3. Building from source
-
- 7.4. Configuration overview
-
- 7.5. The KDE Kicker Recoll applet
-
- 7.1. Installing a binary copy
+ 5.1. Installing a binary copy
+
+ 5.2. Supporting packages
+
+ 5.3. Building from source
+
+ 5.4. Configuration overview
+
+ 5.1. Installing a binary copy
There are three types of binary Recoll installations:
@@ -47,13 +45,13 @@
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
+5.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
+5.1.2. Installing a prebuilt Recoll
The unpackaged binary versions on the Recoll web site are just compressed
tar files of a build tree, where only the useful parts were kept
@@ -76,11 +74,11 @@
Link: NEXT
Recoll user manual
- Prev Chapter 7. Installation Next
+ Prev Chapter 5. Installation and configuration Next
--------------------------------------------------------------------------
- 7.2. Supporting packages
+ 5.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
@@ -95,42 +93,58 @@
the filters need the iconv command, which is not always listed as a
dependancy.
+ Please note that, due to the relatively dynamic nature of this
+ information, the most up to date version is now kept on the Recoll helper
+ applications page along with links to the home pages or best
+ source/patches download links. The list below is not updated often and may
+ be quite stale.
+
+ For many Linux distributions, most of the commands listed can be installed
+ from the package repositories. However, the packages are sometimes
+ outdated, or not the best version for Recoll, so you should take a look at
+ the Recoll helper applications page if a file type is important to you.
+
As of Recoll release 1.14, a number of XML-based formats that were handled
- by ad hoc filter code now use xsltproc, which usually comes with libxslt.
- These are: abiword, fb2 (ebooks), kword, openoffice, svg.
-
- * Openoffice: supported natively, but needs the unzip command to be
- installed.
-
- * PDF: pdftotext is part of the Xpdf or Poppler packages.
-
- * Postscript: pstotext.
-
- * MS Word: antiword.
-
- * MS Excel and PowerPoint: catdoc.
-
- * MS Open XML (docx): needs xsltproc.
-
- * Wordperfect files: libwpd.
-
- * RTF: unrtf
-
- * TeX: Recoll uses the untex program. Your distribution may have a
- package for it. If it doesn't, there is a copy of the source on the
- Recoll web site, because the program has no obvious home. The filter
- can also work with detex and will use it if it is installed.
-
- * dvi: dvips
-
- * djvu: DjVuLibre
-
- * mp3, flac, ogg vorbis: Recoll releases before 1.13 use the id3info
- command from the id3lib package to extract mp3 tag information. (Some
- gcc versions after 4.4 may have trouble compiling id3lib. You can find
- a workaround here), metaflac (standard flac tools) for flac files, and
- ogginfo (vorbis tools) for ogg files. Releases 1.14 and later use a
- single Python filter based on mutagen for all audio file types.
+ by ad hoc filter code now use the xsltproc command, which usually comes
+ with libxslt. These are: abiword, fb2 (ebooks), kword, openoffice, svg.
+
+ Now for the list:
+
+ * Openoffice files need unzip and xsltproc.
+
+ * PDF files need pdftotext which is part of the Xpdf or Poppler
+ packages.
+
+ * Postscript files need pstotext. The original version has an issue with
+ shell character in file names, which is corrected in recent packages.
+ See the the Recoll helper applications page for more detail.
+
+ * MS Word needs antiword. It is also useful to have wvWare installed as
+ it may be be used as a fallback for some files which antiword does not
+ handle.
+
+ * MS Excel and PowerPoint need catdoc.
+
+ * MS Open XML (docx) needs xsltproc.
+
+ * Wordperfect files need wpd2html from the libwpd package.
+
+ * RTF files need unrtf, which, in its standard version, has much trouble
+ with non-western character sets. Check the Recoll helper applications
+ page.
+
+ * TeX files need untex or detex. Check the Recoll helper applications
+ page for sources if it's not packaged for your distribution.
+
+ * dvi files need dvips.
+
+ * djvu files need djvutxt and djvused from the DjVuLibre package.
+
+ * Audio files: Recoll releases before 1.13 used the id3info command from
+ the id3lib package to extract mp3 tag information, metaflac (standard
+ flac tools) for flac files, and ogginfo (vorbis tools) for ogg files.
+ Releases 1.14 and later use a single Python filter based on mutagen
+ for all audio file types.
* Pictures: Recoll uses the Exiftool Perl package to extract tag
information. Most image file formats are supported. Note that there
@@ -141,37 +155,43 @@
* chm: files in microsoft help format need Python and the pychm module
(which needs chmlib).
- * ics: up to Recoll 1.13, iCalendar files need Python and the icalendar
- module. For newer versions, icalendar is not needed
-
- * 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 iconv and
- the standard sed and awk.
+ * ICS: up to Recoll 1.13, iCalendar files need Python and the icalendar
+ module. icalendar is not needed for newer versions, which use internal
+ code.
+
+ * Zip archives need Python (and the standard zipfile module).
+
+ Text, HTML, mail folders, and Scribus files are processed internally. Lyx
+ is used to index Lyx files. Many filters need iconv and the standard sed
+ and awk.
--------------------------------------------------------------------------
- Prev Home Next
- Installation Up Building from source
+ Prev Home Next
+ Installation and configuration Up Building from source
Link: HOME
Link: UP
Link: PREVIOUS
Link: NEXT
Recoll user manual
- Prev Chapter 7. Installation Next
+ Prev Chapter 5. Installation and configuration Next
--------------------------------------------------------------------------
- 7.3. Building from source
-
-7.3.1. Prerequisites
+ 5.3. Building from source
+
+5.3.1. Prerequisites
C++ compiler. Up to Recoll version 1.13.04, its absence can manifest
itself by strange messages about a missing iconv_open.
- Development files for Xapian core
+ Development files for Xapian core.
+
+ Important: If you are building Xapian for an older CPU (before Pentium 4
+ or Athlon 64), you need to add the --disable-sse flag to the configure
+ command. Else all Xapian application will crash with an illegal
+ instruction error.
Development files for Qt .
@@ -187,7 +207,7 @@
not be critical). On Linux systems, the iconv interface is part of libc
and you should not need to do anything special.
-7.3.2. Building
+5.3.2. Building
Recoll has been built on Linux, FreeBSD, Mac OS X, and Solaris, most
versions after 2005 should be ok, maybe some older ones too (Solaris 8 is
@@ -254,7 +274,7 @@
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
+5.3.3. Installation
Either type make install or execute recollinstall prefix, in the root of
the source tree. This will copy the commands to prefix/bin and the sample
@@ -276,14 +296,13 @@
Link: HOME
Link: UP
Link: PREVIOUS
- Link: NEXT
Recoll user manual
- Prev Chapter 7. Installation Next
+ Prev Chapter 5. Installation and configuration
--------------------------------------------------------------------------
- 7.4. Configuration overview
+ 5.4. Configuration overview
Most of the parameters specific to the recoll GUI are set through the
Preferences menu and stored in the standard Qt place ($HOME/.qt/recollrc).
@@ -355,7 +374,7 @@
White space is used for separation inside lists. List elements with
embedded spaces can be quoted using double-quotes.
-7.4.1. Main configuration file
+5.4.1. Main configuration file
recoll.conf is the main configuration file. It defines things like what to
index (top directories and things to ignore), and the default character
@@ -370,7 +389,7 @@
Configuration menu in the recoll interface. Some can only be set by
editing the configuration file.
- 7.4.1.1. Parameters affecting what documents we index:
+ 5.4.1.1. Parameters affecting what documents we index:
topdirs
@@ -491,7 +510,7 @@
Beagle plugin as ~/.beagle/ToIndex so there should be no need to
change it.
- 7.4.1.2. Parameters affecting how we generate terms:
+ 5.4.1.2. Parameters affecting how we generate terms:
Changing some of these parameters will imply a full reindex. Also, when
using multiple indexes, it may not make sense to search indexes that don't
@@ -556,7 +575,7 @@
localfields= rclaptg=gnus:other = val, then select specifier
viewer with mimetype|tag=... in mimeview.
- 7.4.1.3. Parameters affecting where and how we store things:
+ 5.4.1.3. Parameters affecting where and how we store things:
dbdir
@@ -604,7 +623,7 @@
default, which is flushing every 10000 documents (memory usage
depends on average document size). The default value is 10.
- 7.4.1.4. Miscellaneous parameters:
+ 5.4.1.4. Miscellaneous parameters:
loglevel,daemloglevel
@@ -668,7 +687,7 @@
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 fields file
+5.4.2. The fields file
This file contains information about dynamic fields handling in Recoll.
Some very basic fields have hard-wired behaviour, and, mostly, you should
@@ -728,7 +747,7 @@
# mailmytag field name
x-my-tag = mailmytag
-7.4.3. The mimemap file
+5.4.3. The mimemap file
mimemap specifies the file name extension to mime type mappings.
@@ -752,7 +771,7 @@
given Recoll version. Having it there avoids cluttering the more
user-oriented and locally customized skippedNames.
-7.4.4. The mimeconf file
+5.4.4. The mimeconf file
mimeconf specifies how the different mime types are handled for indexing,
and which icons are displayed in the recoll result lists.
@@ -764,15 +783,20 @@
recoll in the result lists (the values are the basenames of the png images
inside the iconsdir directory (specified in recoll.conf).
-7.4.5. The mimeview file
-
- mimeview specifies which programs are started when you click on an Edit
+5.4.5. The mimeview file
+
+ mimeview specifies which programs are started when you click on an Open
link in a result list. Ie: HTML is normally displayed using firefox, but
you may prefer Konqueror, your openoffice.org program might be named
oofice instead of openoffice etc.
Changes to this file can be done by direct editing, or through the recoll
user preferences dialog.
+
+ If Use desktop preferences to choose document editor is checked in the
+ Recoll GUI user preferences, all mimeview entries will be ignored except
+ the one labelled application/x-all (which is set to use xdg-open by
+ default).
As for the other configuration files, the normal usage is to have a
mimeview inside your own configuration directory, with just the
@@ -786,21 +810,42 @@
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).
-
The nouncompforviewmts entry, (placed at the top level, outside of the
[view] section), holds a list of mime types that should not be
uncompressed before starting the viewer (if they are found compressed, ie:
mydoc.doc.gz).
-7.4.6. Examples of configuration adjustments
-
- 7.4.6.1. Adding an external viewer for an non-indexed type
+ The right side of each assignment holds a command to be executed for
+ opening the file. The following substitutions are performed:
+
+ * %D. Document date
+
+ * %f. File name. This may be the name of a temporary file if it was
+ necessary to create one (ie: to extract a subdocument from a
+ container).
+
+ * %F. Original file name. Same as %f except if a temporary file is used.
+
+ * %i. Internal path, for subdocuments of containers. The format depends
+ on the container type. If this appears in the command line, Recoll
+ will not create a temporary file to extract the subdocument, expecting
+ the called application (possibly a script) to be able to handle it.
+
+ * %M. Mime type
+
+ * %U, %u. Url.
+
+ In addition to the predefined values above, all strings like %(fieldname)
+ will be replaced by the value of the field named fieldname for the
+ document. This could be used in combination with field customisation to
+ help with opening the document.
+
+5.4.6. Examples of configuration adjustments
+
+ 5.4.6.1. Adding an external viewer for an non-indexed type
Imagine that you have some kind of file which does not have indexable
- content, but for which you would like to have a functional Edit link in
+ content, but for which you would like to have a functional Open link in
the result list (when found by file name). The file names end in .blob and
can be displayed by application blobviewer.
@@ -827,7 +872,7 @@
configuration, which you do not need to alter. mimeview can also be
modified from the Gui.
- 7.4.6.2. Adding indexing support for a new file type
+ 5.4.6.2. Adding indexing support for a new file type
Let us now imagine that the above .blob files actually contain indexable
text and that you know how to extract it with a command line program.
@@ -858,5 +903,5 @@
--------------------------------------------------------------------------
- Prev Home Next
- Building from source Up The KDE Kicker Recoll applet
+ Prev Home
+ Building from source Up