recoll / Code / Diff of /src/INSTALL

Diff of /src/INSTALL [2d3576] .. [79119c]

Switch to unified view


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

   A list of common file types which need external commands follows. Many of
   the handlers 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
   http://www.recoll.org/features.html along with links to the home pages or
...
   from the package repositories. However, the packages are sometimes
   outdated, or not the best version for Recoll, so you should take a look at
   http://www.recoll.org/features.html 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 handler code now use the xsltproc command, which usually comes
   with libxslt. These are: abiword, fb2 (ebooks), kword, openoffice, svg.

   Now for the list:

     o Openoffice files need unzip and xsltproc.
...

     o 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
       Ubuntu) package.
...

     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
       handler based on mutagen for all audio file types.




     o 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
       (which needs chmlib).

     o 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 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
       introduces some mild weirdness, but still usable).

   Text, HTML, email folders, and Scribus files are processed internally. Lyx
   is used to index Lyx files. Many handlers need iconv and the standard sed
   and awk.

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

   Prev                                        Up                        Next 
...

   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 handler, 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 handler and install a supplementary Python
           module. The details are described on the Recoll wiki.

   followLinks

           Specifies if the indexer should follow symbolic links while
...
           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. Can be redefined for
           subdirectories.

   excludedmimetypes

           This list lets you exclude some MIME types from indexing. Can be
           redefined for subdirectories.

   compressedfilemaxkbs

           Size limit for compressed (.gz or .bz2) files. These need to be
           decompressed in a temporary directory for identification, which
...
   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.

   processwebqueue
...

   webcachemaxmbs

           This is only used by the web browser plugin indexing code, and
           defines the maximum size for the web page cache. Default: 40 MB.
           Quite unfortunately, this is only taken into account when creating
           the cache file. You need to delete the file for a change to be
           taken into account.

   idxflushmb

           Threshold (megabytes of new text data) where we flush from memory
           to disk index. Setting this can help control memory usage. A value
...
           These allow defining the ionice class and data used by the indexer
           (default class 3, no data).

   filtermaxseconds

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

   filtersdir

           A directory to search for the external input handler scripts used
           to index some types of files. The value should not be changed,
           except if you want to modify one of the default scripts. The value
           can be redefined for any sub-directory.

   iconsdir

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

           This section defines lists of synonyms for the canonical names
           used inside the [prefixes] and [stored] sections

   handler-specific sections

           Some input handlers may need specific configuration for handling
           fields. Only the email message handler currently has such a
           section (named [mail]). It allows indexing arbitrary email headers
           in addition to the ones indexed by default. Other such sections
           may appear in the future.

   Here follows a small example of a personal fields file. This would extract
   a specific email header and use it as a searchable field, with data
   displayable inside result lists. (Side note: as the email handler does no
   decoding on the values, only plain ascii headers can be indexed, and only
   the first occurrence will be used for headers that occur several times).

 [prefixes]
 # Index mailmytag contents (with the given prefix)
...
   translations from extended attributes names to Recoll field names. An
   empty translation disables use of the corresponding attribute data.

  5.4.3. The mimemap file

   mimemap specifies the file name extension to MIME type mappings.

   For file names without an extension, or with an unknown one, the system's
   file -i command will be executed to determine the MIME type (this can be
   switched off inside the main configuration file).

   The mappings can be specified on a per-subtree basis, which may be useful
   in some cases. Example: gaim logs have a .txt extension but should be
   handled specially, which is possible because they are usually all located
...
   given Recoll version. Having it there avoids cluttering the more
   user-oriented and locally customized skippedNames.

  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.

   Changing the parameters in the [index] section is probably not a good idea
   except if you are a Recoll developer.

...

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

   In this case, the xallexcepts top level variable defines a list of MIME
   type exceptions which will be processed according to the local entries
   instead of being passed to the desktop. This is so that specific Recoll
   options such as a page number or a search string can be passed to
   applications that support them, such as the evince viewer.

...
   non-default entries, which will override those from the central
   configuration file.

   All viewer definition 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

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

   The right side of each assignment holds a command to be executed for
   opening the file. The following substitutions are performed:
...
     o %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,
       currently only PDF, Postscript and DVI files. Can be used to start the
       editor at the right page for a match or snippet.

...
     o In $RECOLL_CONFDIR/mimemap (typically ~/.recoll/mimemap), add the
       following line:

 .blob = application/x-blobapp

       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:

 application/x-blobapp = blobviewer %f

       We are supposing that blobviewer wants a file name parameter here, you
       would use %u if it liked URLs better.

   If you just wanted to change the application used by Recoll to display a
   MIME type which it already knows, you would just need to edit mimeview.
   The entries you add in your personal file override those in the central
   configuration, which you do not need to alter. mimeview can also be
   modified from the Gui.

    5.4.7.2. Adding indexing support for a new file type
...

     o 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
       makes sense (you can also create a category). Categories may be used
       for filtering in advanced search.

   The rclblob handler should be an executable program or script which exists
   inside /usr/[local/]share/recoll/filters. It will be given a file name as
   argument and should output the text or html contents on the standard
   output.

   The filter programming section describes in more detail how to write an
   input handler.

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

   Prev                                Up                                     
   5.3. Building from source          Home                                    