doc

src/doc/user/usermanual.sgml

@@ -4743,13 +4743,30 @@ except:
         configuration parameters is given by comments inside the default
         files, and we will just give a general overview here.</para>
 
-      <para>For each index, there are two sets of configuration
+      <para>By default, for each index, there are two sets of
-        files. System-wide configuration files are kept in a directory named
+        configuration files. System-wide configuration files are kept
+        in a directory named
         like <filename>/usr/[local/]share/recoll/examples</filename>,
         and define default values, shared by all indexes. For each
         index, a parallel set of files defines the customized
         parameters.</para>
 
+      <para>In addition (as of &RCL; 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 <envar>RECOLL_CONFTOP</envar>
+        and <envar>RECOLL_CONFMID</envar> environment
+        variables. Values from the top directory will override user
+        ones, values from the middle directory will override system
+        ones and be overriden by user ones. These two variables may be
+        of use to applications which augment &RCL; 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.</para>
+
       <para>The default location of the configuration is the
         <filename>.recoll</filename>
         directory in your home. Most people will only use this
@@ -5212,18 +5229,46 @@ unac_except_trans =  åå Åå ää Ää öö Öö
             </listitem>
            </varlistentry>
 
+          <varlistentry><term><varname>noxattrfields</varname></term>
+            <listitem><para>Recoll versions 1.19 and later
+                automatically translate file extended attributes into
+                document fields (to be processed according to the
+                parameters from the <filename>fields</filename>
+                file). Setting this variable to 1 will disable the
+                behaviour.</para></listitem>
+          </varlistentry>
+
           <varlistentry id="RCL.INSTALL.CONFIG.RECOLLCONF.METADATACMDS">
             <term><varname>metadatacmds</varname></term>
             <listitem><para>This allows executing external commands
-            for each file and storing the output in a &RCL;
+                for each file and storing the output in &RCL; document
-            field. This could be used for example to index external
+                fields. This could be used for example to index
-            tag data. The value is a list of field names and commands,
+                external tag data. The value is a list of field names
-            don't forget an initial semi-colon. Example: 
+                and commands, don't forget an initial
+                semi-colon. Example:
                 <programlisting>
 [/some/area/of/the/fs]
 metadatacmds = ; tags = tmsu tags %f; otherfield = somecmd -xx %f
                 </programlisting>
-              </para>
+              </para> <para>As a specially disgusting hack brought by
+                &RCL; 1.19.7, if a "field name" begins
+                with <literal>rclmulti</literal>, 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:
+                <programlisting>
+metadatacmds = ; rclmulti1 = somecmd %f
+                </programlisting>
+                If <literal>somecmd</literal> returns data in the form
+                of:
+                <programlisting>
+field1 = value1
+field2 = "value for field2"
+                </programlisting>
+                <literal>field1</literal>
+                and <literal>field2</literal> will be set inside the
+                document metadata.</para>
             </listitem>
           </varlistentry>
 

src/sampleconf/recoll.conf.in

@@ -308,8 +308,13 @@ noxattrfields = 0
 # which field name the data goes into and the command to use. Don't forget the
 # initial semi-colon. All the field names must be different. You can use
 # aliases in the "field" file if necessary. 
+# As a not too pretty hack conceded to convenience, any field name
+# beginning with "rclmulti" will be taken as an indication that the command
+# returns multiple field values inside a text blob formatted as a recoll
+# configuration file ("fieldname = fieldvalue" lines). The rclmultixx name
+# will be ignored, and field names and values will be parsed from the data.
 #[/some/area/of/the/fs]
-#metadatacmds = ; tags = tmsu tags %f
+#metadatacmds = ; tags = tmsu tags %f; rclmulti1 = cmdOutputsConf %f
 
 [/usr/share/man]
 followSymlinks = 1