Switch to side-by-side view

--- a/src/INSTALL
+++ b/src/INSTALL
@@ -12,18 +12,18 @@
 
      ----------------------------------------------------------------------
 
-Chapter 5. Installation and configuration
+                   Chapter 5. Installation and configuration
 
 5.1. Installing a binary copy
 
    There are three types of binary Recoll installations:
 
-     o Through your system normal software distribution framework (ie,
+     * Through your system normal software distribution framework (ie,
        Debian/Ubuntu apt, FreeBSD ports, etc.).
 
-     o From a package downloaded from the Recoll web site.
-
-     o From a prebuilt tree downloaded from the Recoll web site.
+     * 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.
@@ -58,7 +58,7 @@
      ----------------------------------------------------------------------
 
    Prev                                                                  Next 
-   4.3. API                           Home           5.2. Supporting packages 
+   4.3. API  Home                                    5.2. Supporting packages 
    Link: home: Recoll user manual
    Link: up: Chapter 5. Installation and configuration
    Link: prev: Chapter 5. Installation and configuration
@@ -101,64 +101,64 @@
 
    Now for the list:
 
-     o Openoffice files need unzip and xsltproc.
-
-     o PDF files need pdftotext which is part of the Xpdf or Poppler
+     * Openoffice files need unzip and xsltproc.
+
+     * PDF files need pdftotext which is part of the Xpdf or Poppler
        packages.
 
-     o Postscript files need pstotext. The original version has an issue with
+     * Postscript files need pstotext. The original version has an issue with
        shell character in file names, which is corrected in recent packages.
        See http://www.recoll.org/features.html for more detail.
 
-     o MS Word needs antiword. It is also useful to have wvWare installed as
+     * 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.
 
-     o MS Excel and PowerPoint are processed by internal Python handlers.
-
-     o MS Open XML (docx) needs xsltproc.
-
-     o Wordperfect files need wpd2html from the libwpd (or libwpd-tools on
+     * MS Excel and PowerPoint are processed by internal Python handlers.
+
+     * MS Open XML (docx) needs xsltproc.
+
+     * Wordperfect files need wpd2html from the libwpd (or libwpd-tools on
        Ubuntu) package.
 
-     o RTF files need unrtf, which, in its standard version, has much trouble
+     * RTF files need unrtf, which, in its standard version, has much trouble
        with non-western character sets. Check
        http://www.recoll.org/features.html.
 
-     o TeX files need untex or detex. Check
+     * TeX files need untex or detex. Check
        http://www.recoll.org/features.html for sources if it's not packaged
        for your distribution.
 
-     o dvi files need dvips.
-
-     o djvu files need djvutxt and djvused from the DjVuLibre package.
-
-     o Audio files: Recoll releases 1.14 and later use a single Python
+     * dvi files need dvips.
+
+     * djvu files need djvutxt and djvused from the DjVuLibre package.
+
+     * Audio files: Recoll releases 1.14 and later use a single Python
        handler based on mutagen for all audio file types.
 
-     o Pictures: Recoll uses the Exiftool Perl package to extract tag
+     * 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.
 
-     o chm: files in Microsoft help format need Python and the pychm module
+     * chm: files in Microsoft help format need Python and the pychm module
        (which needs chmlib).
 
-     o ICS: up to Recoll 1.13, iCalendar files need Python and the icalendar
+     * 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.
 
-     o Zip archives need Python (and the standard zipfile module).
-
-     o Rar archives need Python, the rarfile Python module and the unrar
+     * Zip archives need Python (and the standard zipfile module).
+
+     * Rar archives need Python, the rarfile Python module and the unrar
        utility.
 
-     o Midi karaoke files need Python and the Midi module
-
-     o Konqueror webarchive format with Python (uses the Tarfile module).
-
-     o Mimehtml web archive format (support based on the email handler, which
+     * Midi karaoke files need Python and the Midi module
+
+     * Konqueror webarchive format with Python (uses the Tarfile module).
+
+     * Mimehtml web archive format (support based on the email handler, which
        introduces some mild weirdness, but still usable).
 
    Text, HTML, email folders, and Scribus files are processed internally. Lyx
@@ -191,10 +191,10 @@
 
    The shopping list:
 
-     o C++ compiler. Up to Recoll version 1.13.04, its absence can manifest
+     * C++ compiler. Up to Recoll version 1.13.04, its absence can manifest
        itself by strange messages about a missing iconv_open.
 
-     o Development files for Xapian core.
+     * Development files for Xapian core.
 
   Important
 
@@ -203,14 +203,14 @@
        command. Else all Xapian application will crash with an illegal
        instruction error.
 
-     o Development files for Qt 4 . Recoll has not been tested with Qt 5 yet.
+     * Development files for Qt 4 . Recoll has not been tested with Qt 5 yet.
        Recoll 1.15.9 was the last version to support Qt 3. If you do not want
        to install or build the Qt Webkit module, Recoll has a configuration
        option to disable its use (see further).
 
-     o Development files for X11 and zlib.
-
-     o You may also need libiconv. On Linux systems, the iconv interface is
+     * Development files for X11 and zlib.
+
+     * You may also need libiconv. On Linux systems, the iconv interface is
        part of libc and you should not need to do anything special.
 
    Check the Recoll download page for up to date version information.
@@ -224,21 +224,21 @@
 
    Configure options: 
 
-     o --without-aspell will disable the code for phonetic matching of search
+     * --without-aspell will disable the code for phonetic matching of search
        terms.
 
-     o --with-fam or --with-inotify will enable the code for real time
+     * --with-fam or --with-inotify will enable the code for real time
        indexing. Inotify support is enabled by default on recent Linux
        systems.
 
-     o --with-qzeitgeist will enable sending Zeitgeist events about the
+     * --with-qzeitgeist will enable sending Zeitgeist events about the
        visited search results, and needs the qzeitgeist package.
 
-     o --disable-webkit is available from version 1.17 to implement the
+     * --disable-webkit is available from version 1.17 to implement the
        result list with a Qt QTextBrowser instead of a WebKit widget if you
        do not or can't depend on the latter.
 
-     o --disable-idxthreads is available from version 1.19 to suppress
+     * --disable-idxthreads is available from version 1.19 to suppress
        multithreading inside the indexing process. You can also use the
        run-time configuration to restrict recollindex to using a single
        thread, but the compile-time option may disable a few more unused
@@ -246,37 +246,37 @@
        index processing (data input). The Recoll monitor mode always uses at
        least two threads of execution.
 
-     o --disable-python-module will avoid building the Python module.
-
-     o --disable-xattr will prevent fetching data from file extended
+     * --disable-python-module will avoid building the Python module.
+
+     * --disable-xattr will prevent fetching data from file extended
        attributes. Beyond a few standard attributes, fetching extended
        attributes data can only be useful is some application stores data in
        there, and also needs some simple configuration (see comments in the
        fields configuration file).
 
-     o --enable-camelcase will enable splitting camelCase words. This is not
+     * --enable-camelcase will enable splitting camelCase words. This is not
        enabled by default as it has the unfortunate side-effect of making
        some phrase searches quite confusing: ie, "MySQL manual" would be
        matched by "MySQL manual" and "my sql manual" but not "mysql manual"
        (only inside phrase searches).
 
-     o --with-file-command Specify the version of the 'file' command to use
+     * --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.
 
-     o --disable-qtgui Disable the Qt interface. Will allow building the
+     * --disable-qtgui Disable the Qt interface. Will allow building the
        indexer and the command line search program in absence of a Qt
        environment.
 
-     o --disable-x11mon Disable X11 connection monitoring inside recollindex.
+     * --disable-x11mon Disable X11 connection monitoring inside recollindex.
        Together with --disable-qtgui, this allows building recoll without Qt
        and X11.
 
-     o --disable-pic will compile Recoll with position-dependant code. This
+     * --disable-pic will compile Recoll with position-dependant code. This
        is incompatible with building the KIO or the Python or PHP extensions,
        but might yield very marginally faster code.
 
-     o Of course the usual autoconf configure options, like --prefix apply.
+     * Of course the usual autoconf configure options, like --prefix apply.
 
    Normal procedure:
 
@@ -318,14 +318,14 @@
 
      ----------------------------------------------------------------------
 
-   Prev                                Up                                Next 
-   5.2. Supporting packages           Home        5.4. Configuration overview 
+   Prev                       Up                                         Next 
+   5.2. Supporting packages  Home                 5.4. Configuration overview 
    Link: home: Recoll user manual
    Link: up: Chapter 5. Installation and configuration
    Link: prev: 5.3. Building from source
 
                           5.4. Configuration overview
-   Prev            Chapter 5. Installation and configuration                  
+   Prev              Chapter 5. Installation and configuration                
 
      ----------------------------------------------------------------------
 
@@ -395,11 +395,11 @@
 
    There are three kinds of lines:
 
-     o Comment (starts with #) or empty.
-
-     o Parameter affectation (name = value).
-
-     o Section definition ([somedirname]).
+     * Comment (starts with #) or empty.
+
+     * Parameter affectation (name = value).
+
+     * Section definition ([somedirname]).
 
    Depending on the type of configuration file, section definitions either
    separate groups of parameters or allow redefining some parameters for a
@@ -418,12 +418,12 @@
    Encoding issues. Most of the configuration parameters are plain ASCII. Two
    particular sets of values may cause encoding issues:
 
-     o File path parameters may contain non-ascii characters and should use
+     * File path parameters may contain non-ascii characters and should use
        the exact same byte values as found in the file system directory.
        Usually, this means that the configuration file should use the system
        default locale encoding.
 
-     o The unac_except_trans parameter should be encoded in UTF-8. If your
+     * The unac_except_trans parameter should be encoded in UTF-8. If your
        system locale is not UTF-8, and you need to also specify non-ascii
        file paths, this poses a difficulty because common text editors cannot
        handle multiple encodings in a single file. In this relatively
@@ -578,11 +578,17 @@
 
    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.
+           Decide if we execute a system command (file -i by default) 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.
+
+   systemfilecommand
+
+           Command to use for mime for mime type determination if
+           usesystefilecommand is set. Recent versions of xdg-mime sometimes
+           work better than file.
 
    processwebqueue
 
@@ -1004,7 +1010,7 @@
    obtain the desired behaviour.
 
    We will only give a short description here, you should refer to the
-   comments inside the file for more detailed information.
+   comments inside the default file for more detailed information.
 
    Field names should be lowercase alphabetic ASCII.
 
@@ -1022,6 +1028,13 @@
 
            This section defines lists of synonyms for the canonical names
            used inside the [prefixes] and [stored] sections
+
+   [queryaliases]
+
+           This section also defines aliases for the canonic field names,
+           with the difference that the substitution will only be used at
+           query time, avoiding any possibility that the value would pick-up
+           random metadata from documents.
 
    handler-specific sections
 
@@ -1045,6 +1058,10 @@
  # Store mailmytag inside the document data record (so that it can be
  # displayed - as %(mailmytag) - in result lists).
  mailmytag =
+
+ [queryaliases]
+ filename = fn
+ containerfilename = cfn
 
  [mail]
  # Extract the X-My-Tag mail header, and use it internally with the
@@ -1139,31 +1156,29 @@
    The right side of each assignment holds a command to be executed for
    opening the file. The following substitutions are performed:
 
-     o %D. Document date
-
-     o %f. File name. This may be the name of a temporary file if it was
+     * %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).
 
-     o %F. Original file name. Same as %f except if a temporary file is used.
-
-     o %i. Internal path, for subdocuments of containers. The format depends
+     * %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.
 
-     o %M. MIME type
-
-     o %p. Page index. Only significant for a subset of document types,
+     * %M. MIME type
+
+     * %p. Page index. Only significant for a subset of document types,
        currently only PDF, Postscript and DVI files. Can be used to start the
        editor at the right page for a match or snippet.
 
-     o %s. Search term. The value will only be set for documents with indexed
+     * %s. Search term. The value will only be set for documents with indexed
        page numbers (ie: PDF). The value will be one of the matched search
        terms. It would allow pre-setting the value in the "Find" entry inside
        Evince for example, for easy highlighting of the term.
 
-     o %U, %u. Url.
+     * %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
@@ -1200,7 +1215,7 @@
 
    You need two entries in the configuration files for this to work:
 
-     o In $RECOLL_CONFDIR/mimemap (typically ~/.recoll/mimemap), add the
+     * In $RECOLL_CONFDIR/mimemap (typically ~/.recoll/mimemap), add the
        following line:
 
  .blob = application/x-blobapp
@@ -1208,7 +1223,7 @@
        Note that the MIME type is made up here, and you could call it
        diesel/oil just the same.
 
-     o In $RECOLL_CONFDIR/mimeview under the [view] section, add:
+     * In $RECOLL_CONFDIR/mimeview under the [view] section, add:
 
  application/x-blobapp = blobviewer %f
 
@@ -1229,16 +1244,16 @@
    alteration, and also to add data to the mimeconf file (typically in
    ~/.recoll/mimeconf):
 
-     o Under the [index] section, add the following line (more about the
+     * Under the [index] section, add the following line (more about the
        rclblob indexing script later):
 
  application/x-blobapp = exec rclblob
 
-     o Under the [icons] section, you should choose an icon to be displayed
+     * Under the [icons] section, you should choose an icon to be displayed
        for the files inside the result lists. Icons are normally 64x64 pixels
        PNG files which live in /usr/[local/]share/recoll/images.
 
-     o Under the [categories] section, you should add the MIME type where it
+     * Under the [categories] section, you should add the MIME type where it
        makes sense (you can also create a category). Categories may be used
        for filtering in advanced search.
 
@@ -1252,5 +1267,5 @@
 
      ----------------------------------------------------------------------
 
-   Prev                                Up                                     
-   5.3. Building from source          Home                                    
+   Prev                                                                 Up    
+   5.3. Building from source                                           Home