release 1.20.0

src/INSTALL

@@ -294,6 +294,15 @@ Chapter 5. Installation and configuration
    to manually copy and modify one of the existing files (the new file name
    should be the output of uname -s).
 
+    5.3.2.1. Building on Solaris
+
+   We did not test building the GUI on Solaris for recent versions. You will
+   need at least Qt 4.4. There are some hints on an old web site page, they
+   may still be valid.
+
+   Someone did test the 1.19 indexer and Python module build, they do work,
+   with a few minor glitches. Be sure to use GNU make and install.
+
   5.3.3. Installation
 
    Either type make install or execute recollinstall prefix, in the root of
@@ -342,12 +351,25 @@ Chapter 5. Installation and configuration
    by comments inside the default files, and we will just give a general
    overview here.
 
-   For each index, there are two sets of configuration files. System-wide
-   configuration files are kept in a directory named like
+   By default, for each index, there are two sets of configuration files.
+   System-wide configuration files are kept in a directory named like
    /usr/[local/]share/recoll/examples, and define default values, shared by
    all indexes. For each index, a parallel set of files defines the
    customized parameters.
 
+   In addition (as of Recoll version 1.19.7), it is possible to specify two
+   additional configuration directories which will be stacked before and
+   after the user configuration directory. These are defined by the
+   RECOLL_CONFTOP and RECOLL_CONFMID environment variables. Values from
+   configuration files inside the top directory will override user ones,
+   values from configuration files inside the middle directory will override
+   system ones and be overriden by user ones. These two variables may be of
+   use to applications which augment Recoll functionality, and need to add
+   configuration data without disturbing the user's files. Please note that
+   the two, currently single, values will probably be interpreted as
+   colon-separated lists in the future: do not use colon characters inside
+   the directory paths.
+
    The default location of the configuration is the .recoll directory in your
    home. Most people will only use this directory.
 
@@ -411,7 +433,7 @@ Chapter 5. Installation and configuration
        text files with appropriate encodings, and concatenate them to create
        the complete configuration.
 
-  5.4.1. Main configuration file
+  5.4.1. The main configuration file, recoll.conf
 
    recoll.conf is the main configuration file. It defines things like what to
    index (top directories and things to ignore), and the default character
@@ -437,7 +459,7 @@ Chapter 5. Installation and configuration
 
    skippedNames
 
-           A space-separated list of patterns for names of files or
+           A space-separated list of wilcard patterns for names of files or
            directories that should be completely ignored. The list defined in
            the default file is:
 
@@ -488,6 +510,16 @@ Chapter 5. Installation and configuration
            can set skippedPathsFnmPathname to 0 to disable the use of
            FNM_PATHNAME (meaning that /*/dir3 will match /dir1/dir2/dir3).
 
+   zipSkippedNames
+
+           A space-separated list of patterns for names of files or
+           directories that should be ignored inside zip archives. This is
+           used directly by the zip filter, and has a function similar to
+           skippedNames, but works independantly. Can be redefined for
+           filesystem subdirectories. For versions up to 1.19, you will need
+           to update the Zip filter and install a supplementary Python
+           module. The details are described on the Recoll wiki.
+
    followLinks
 
            Specifies if the indexer should follow symbolic links while
@@ -679,17 +711,41 @@ Chapter 5. Installation and configuration
            = val, then select specifier viewer with mimetype|tag=... in
            mimeview.
 
+   noxattrfields
+
+           Recoll versions 1.19 and later automatically translate file
+           extended attributes into document fields (to be processed
+           according to the parameters from the fields file). Setting this
+           variable to 1 will disable the behaviour.
+
    metadatacmds
 
            This allows executing external commands for each file and storing
-           the output in a Recoll field. This could be used for example to
-           index external tag data. The value is a list of field names and
-           commands, don't forget an initial semi-colon. Example:
+           the output in Recoll document fields. This could be used for
+           example to index external tag data. The value is a list of field
+           names and commands, don't forget an initial semi-colon. Example:
 
  [/some/area/of/the/fs]
  metadatacmds = ; tags = tmsu tags %f; otherfield = somecmd -xx %f
                 
 
+           As a specially disgusting hack brought by Recoll 1.19.7, if a
+           "field name" begins with rclmulti, the data returned by the
+           command is expected to contain multiple field values, in
+           configuration file format. This allows setting several fields by
+           executing a single command. Example:
+
+ metadatacmds = ; rclmulti1 = somecmd %f
+                
+
+           If somecmd returns data in the form of:
+
+ field1 = value1
+ field2 = value for field2
+                
+
+           field1 and field2 will be set inside the document metadata.
+
     5.4.1.3. Parameters affecting where and how we store things:
 
    dbdir
@@ -746,7 +802,7 @@ Chapter 5. Installation and configuration
            memory, you can try higher values between 20 and 80. In my
            experience, values beyond 100 are always counterproductive.
 
-    5.4.1.4. Indexing parallelism configuration
+    5.4.1.4. Parameters affecting multithread processing
 
    The Recoll indexing process recollindex can use multiple threads to speed
    up indexing on multiprocessor systems. The work done to index files is
@@ -774,7 +830,7 @@ Chapter 5. Installation and configuration
            stage. In practise, deep queues have not been shown to increase
            performance. A value of 0 for the first queue tells Recoll to
            perform autoconfiguration (no need for the two other values in
-           this case)- this is the default configuration.
+           this case) - this is the default configuration.
 
    thrTCounts
 
@@ -804,6 +860,11 @@ Chapter 5. Installation and configuration
  thrQSizes = 2 -1 -1
  thrTCounts =  6 1 1
 
+   The following example would disable multithreading. Indexing will be
+   performed by a single thread.
+
+ thrQSizes = -1 -1 -1
+
     5.4.1.5. Miscellaneous parameters:
 
    autodiacsens