recoll / Code / Diff of /src/README

Diff of /src/README [775eff] .. [ad0da7]

Switch to unified view

-a/src/README
+b/src/README
 ...
 .1. Introduction
 .2. Index storage
-.2.1. Index formats
+.2.1. Xapian index formats
 .2.2. Security aspects
-.3. The indexing configuration
+.3. Indexing configuration
+.3.1. The indexing configuration GUI
 .4. Periodic indexing
 .4.1. Starting indexing
 ...
 .4.4. The mimeview file
 .4.5. Examples of configuration adjustments
+.5. The KDE Kicker Recoll applet
-.5. Extending Recoll
+.6. Extending Recoll
-.5.1. Writing a document filter
+.6.1. Writing a document filter
      ----------------------------------------------------------------------
                             Chapter 1. Introduction
 ...
    The index data directory (xapiandb) only contains data that can be
    completely rebuilt by an index run, and it can always be destroyed safely.
      ----------------------------------------------------------------------
-.2.1. Index formats
+.2.1. Xapian index formats
+   If your first installation of Recoll was 1.9.0 or more recent, you can
+   skip this section.
    Xapian has had two possible index formats for quite some time. The "old"
    one named Quartz, and the new one named Flint. Xapian 0.9 used Quartz by
    default, but could use Flint if a specific environment variable
    (XAPIAN_PREFER_FLINT) was set. Xapian 1.0 still supports Quartz but will
 ...
    mode of 0700 (access by owner only). As the index data directory is by
    default a sub-directory of the configuration directory, this should result
    in appropriate protection.
    If you use another setup, you should think of the kind of protection you
-   need for your index, and set the directory and files access modes
+   need for your index, set the directory and files access modes
-   appropriately.
+   appropriately, and also maybe adjust the umask used during index updates.
      ----------------------------------------------------------------------
-.3. The indexing configuration
+.3. Indexing configuration
-   You can control which areas of the file system are indexed, and how files
+   Variables set inside the Recoll configuration files control which areas of
-   are processed, by setting variables inside the Recoll configuration files.
+   the file system are indexed, and how files are processed. These variables
+   can be set either by editing the text files or using the dialogs in the
+   recoll GUI.
    You can also use multiple indexes defined by separate configurations,
    typically to separate personal and shared indexes, or to take advantage of
    the organization of your data to improve search precision.
 ...
    topdirs, which determines what subtrees get indexed.
    The applications needed to index file types other than text, HTML or email
    (ie: pdf, postscript, ms-word...) are described in the external packages
    section
+     ----------------------------------------------------------------------
+.3.1. The indexing configuration GUI
+   As of Recoll 1.10, most parameters for a given indexing configuration can
+   be set from a recoll GUI running on this configuration (either as default,
+   or by setting RECOLL_CONFDIR or the -c option.)
+   The interface is started from the Preferences menu. It has two main
+   panels. The first panel allows setting global variables, like the list of
+   top directories or the list of skipped paths. The second panel allows
+   setting variables that can be redefined for subdirectories. This second
+   panel has an initially empty list of customisation directories, to which
+   you can add. The variables are then set for the currently selected
+   directory (or at the top level if the empty line is selected).
+   The meaning for most entries in the interface is self-evident and
+   documented by a ToolTip popup on the text label. For more detail, you will
+   need to refer to the configuration section of this guide.
+   The configuration tool normally respects the comments and most of the
+   formatting inside the configuration file, so that it is quite possible to
+   use it on hand-edited files, which you might nevertheless want to backup
+   first...
      ----------------------------------------------------------------------
 .4. Periodic indexing
 ...
    There are two other elements which may be specified through the field
    syntax, but are somewhat special:
      * ext for specifying the file name extension (Ex: ext:html)
+     * dir for specifying the file location (Ex: dir:/home/me/somedir).
+       Please note that this is quite inefficient, that it may produce very
+       slow searches, and that it may be worth in some cases to set up
+       separate databases instead.
      * mime for specifying the mime type. This one is quite special because
        you can specify several values which will be OR'ed (the normal default
        for the language is AND). Ex: mime:text/plain mime:text/html.
        Specifying an explicit boolean operator or negation (-) before a mime
 ...
      * 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: Recoll will use the id3info command from the id3lib package to
 ...
            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.
+   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.
    indexallfilenames
            Recoll indexes file names in a special section of the database to
            allow specific file names searches using wild cards. This
 ...
            If this is set, the aspell dictionary generation is turned off.
            Useful for cases where you don't need the functionality or when it
            is unusable because aspell crashes during dictionary generation.
+   nocjk
+           If this set to true, specific east asian (Chinese Korean Japanese)
+           characters/word splitting is turned off. This will save a small
+           amount of cpu if you have no CJK documents. If your document base
+           does include such text but you are not interested in searching it,
+           setting nocjk may be a significant time and space saver.
+   cjkngramlen
+           This lets you adjust the size of n-grams used for indexing CJK
+           text. The default value of 2 is probably appropriate in most
+           cases. A value of 3 would allow more precision and efficiency on
+           longer words, but the index will be approximately twice as large.
      ----------------------------------------------------------------------
 .4.2. The mimemap file
    mimemap specifies the file name extension to mime type mappings.
 ...
    You can find more details about writing a Recoll filter in the section
    about writing filters
      ----------------------------------------------------------------------
+.5. The KDE Kicker Recoll applet
+   The Recoll source tree contains the source code to the recoll_applet, a
+   small application derived from the find_applet. This can be used to add a
+   small Recoll launcher to the KDE panel.
+   The applet is not automatically built with the main Recoll programs. To
+   build it, you need to unpack the Recoll source code, then go to the
+   kde/recoll_applet/ directory, and type the usual configure;make;make
+   install.
+   You can then add the applet to the panel by right-clicking the panel and
+   choosing the Add applet entry.
+   The recoll_applet has a small text window where you can type a Recoll
+   query (in query language form), and an icon which can be used to restrict
+   the search to certain types of files.
+     ----------------------------------------------------------------------
-.5. Extending Recoll
+.6. Extending Recoll
-.5.1. Writing a document filter
+.6.1. Writing a document filter
    Recoll filters are executable programs which translate from a specific
    format (ie: openoffice, acrobat, etc.) to the Recoll indexing input
    format, which was chosen to be HTML.