diff --git a/src/doc/user/usermanual.sgml b/src/doc/user/usermanual.sgml index ea39473a..966c6f97 100644 --- a/src/doc/user/usermanual.sgml +++ b/src/doc/user/usermanual.sgml @@ -297,7 +297,7 @@ the xapiandb directory (see next section), or, alternatively, start the next recollindex with the - -z option, which will reset the database before + option, which will reset the database before indexing. @@ -315,8 +315,8 @@ You can specify a different configuration - directory by setting the RECOLL_CONFDIR - environment variable, or using the -c + directory by setting the RECOLL_CONFDIR + environment variable, or using the option to the &RCL; commands. This method would typically be used to index different areas of the file system to different indexes. For example, if you were to issue the @@ -339,7 +339,7 @@ recoll You can also specify a different storage - location for the index by setting the dbdir + location for the index by setting the dbdir parameter in the configuration file (see the configuration section). This method would mainly be of use if you @@ -385,7 +385,7 @@ recoll explicitly delete the old index, then run a normal indexing process. - Unfortunately, using the -z option to + Unfortunately, using the option to recollindex is not sufficient to change the format, you will have to delete all files inside the index directory (typically ~/.recoll/xapiandb) @@ -460,7 +460,7 @@ recoll 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 + RECOLL_CONFDIR or the option.) The interface is started from the @@ -515,7 +515,7 @@ recoll This feature can be enabled in the GUI indexing configuration panel, or by editing the configuration file (set - processbeaglequeue to 1). + processbeaglequeue to 1). There are more recent instructions about how to find and install the Firefox extension on the @@ -543,8 +543,8 @@ recoll from the GUI, the indexing will run on the same configuration recoll was started on. When started from the command line, recollindex will use the - RECOLL_CONFDIR variable or accept a - -c confdir option + RECOLL_CONFDIR variable or accept a + confdir option to specify a non-default configuration directory. If the recoll program finds no index @@ -572,15 +572,15 @@ recoll recollindex has a number of other options which are described in its man page. - Of special interest maybe are the -i and - -f options. -i allows + Of special interest maybe are the and + options. allows indexing an explicit list of files (given as command line - parameters or read on stdin). -f tells + parameters or read on stdin). tells recollindex to ignore file selection parameters from the configuration. Together, these options allow building a custom file selection process for some area of the file system, by adding the top directory to the - skippedPaths list and using an appropriate + skippedPaths list and using an appropriate file selection method to build the file list to be fed to recollindex -if . @@ -671,16 +671,16 @@ fvwm indexing daemon will monitor the state of the X11 session, and exit when it finishes, it is not necessary to kill it explicitly. (The X11 server monitoring can be disabled with option - -x to recollindex). + to recollindex). If you use the daemon completely out of an X11 session, you - need to add option -x to disable X11 session + need to add option to disable X11 session monitoring (else the daemon will not start). By default, the messages from the indexing daemon will be discarded. You may want to change this by setting the - daemlogfilename and - daemloglevel configuration parameters. Also the + daemlogfilename and + daemloglevel configuration parameters. Also the log file will only be truncated when the daemon starts. If the daemon runs permanently, the log file may grow quite big, depending on the log level. @@ -688,8 +688,8 @@ fvwm When building &RCL;, the real time indexing support can be customised during package configuration with the - --with[out]-fam or - --with[out]-inotify options. The default is + or + options. The default is currently to include inotify monitoring on systems that support it, and, as of recoll 1.17, gamin support on FreeBSD. @@ -712,7 +712,7 @@ fvwm &RCL; provides a configuration option to specify the minimum time before which a file, specified by a wildcard pattern, cannot be - reindexed. See the mondelaypatterns parameter in + reindexed. See the mondelaypatterns parameter in the configuration section. @@ -1312,8 +1312,8 @@ fvwm using several configuration directories which are usually set to index different areas of the file system. A specific index can be selected for updating or searching, using the - RECOLL_CONFDIR environment variable or the - -c option to recoll and + RECOLL_CONFDIR environment variable or the + option to recoll and recollindex. A recollindex program instance can only @@ -1522,9 +1522,9 @@ fvwm Phrase searches can strongly slow down a query if most of the terms in the phrase are common. This is why the - autophrase option is off by default for &RCL; + autophrase option is off by default for &RCL; versions before 1.17. As of version 1.17, - autophrase is on by default, but very common + autophrase is on by default, but very common terms will be removed from the constructed phrase. The removal threshold can be adjusted from the search preferences. @@ -2070,7 +2070,7 @@ fvwm There are several ways to obtain search results as a text stream, without a graphical interface: - By passing option -t to the + By passing option to the recoll program. By using the recollq program. @@ -2082,7 +2082,7 @@ fvwm The first two methods work in the same way and accept/need the same - arguments (except for the additional -t to + arguments (except for the additional to recoll). The query to be executed is specified as command line arguments. @@ -2158,7 +2158,7 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r If the results of a query language search puzzle you and you doubt what has been actually searched for, you can use the GUI - show query link at the top of the result list to + Show Query link at the top of the result list to check the exact query which was finally executed by Xapian. Here follows a sample request that we are going to @@ -2489,7 +2489,7 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r It is surprisingly convenient to be able to show or hide the &RCL; GUI with a single keystroke. Recoll comes with a small - Python script, based on the libwnck window + Python script, based on the libwnck window manager interface library, which will allow you to do just this. The detailed instructions are on @@ -2501,8 +2501,8 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r The KDE Kicker Recoll applet The &RCL; source tree contains the source code to the - recoll_applet, a small application derived - from the find_applet. This can be used to + recoll_applet, a small application derived + from the find_applet. This can be used to add a small &RCL; launcher to the KDE panel. The applet is not automatically built with the main &RCL; @@ -2515,12 +2515,12 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r 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 &RCL; query (in query language form), and an - icon which can be used to restrict the search to certain types of - files. It is quite primitive, and launches a new recoll GUI instance - every time (even if it is already running). You may find it useful - anyway. + The recoll_applet has a small text + window where you can type a &RCL; query (in query language form), + and an icon which can be used to restrict the search to certain + types of files. It is quite primitive, and launches a new recoll + GUI instance every time (even if it is already running). You may + find it useful anyway. @@ -2601,7 +2601,7 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r extract metadata from the html header and use it for field searches.. - The RECOLL_FILTER_FORPREVIEW environment + The RECOLL_FILTER_FORPREVIEW environment variable (values yes, no) tells the filter if the operation is for indexing or previewing. Some filters use this to output a slightly different @@ -2609,8 +2609,8 @@ text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/r Subject: for email) when indexing. This is not essential. - You should look to one of the simple filters, for example - rclps for a starting point. + You should look at one of the simple filters, for example + rclps for a starting point. Don't forget to make your filter executable before testing ! @@ -2863,7 +2863,7 @@ application/x-chm = execm rclchm There is no significant disadvantage in using PIC objects for the main Recoll executables, so you can use the - --enable-pic option for the main build + option for the main build too. The python/recoll/ directory @@ -3385,29 +3385,29 @@ while query.next >= 0 and query.next < nres: Depending on the Qt 3 configuration on your system, you may have to set the - QTDIR and QMAKESPECS + QTDIR and QMAKESPECS variables in your environment: - QTDIR should point to the + QTDIR should point to the directory above the one that holds the qt include files (ie: if qt.h is /usr/local/qt/include/qt.h, QTDIR should be /usr/local/qt). - QMAKESPECS should + QMAKESPECS should be set to the name of one of the - qt mkspecs sub-directories (ie: - linux-g++). + Qt mkspecs sub-directories (ie: + linux-g++). - On many Linux systems, QTDIR is set - by the login scripts, and QMAKESPECS is not + On many Linux systems, QTDIR is set + by the login scripts, and QMAKESPECS is not needed because there is a default link in mkspecs/. - Neither QTDIR nor - QMAKESPECS should be needed with + Neither QTDIR nor + QMAKESPECS should be needed with Qt 4, configuration details are entirely determined by qmake (which is quite often installed as qmake-qt4). @@ -3415,28 +3415,28 @@ while query.next >= 0 and query.next < nres: Configure options: - --without-aspell + will disable the code for phonetic matching of search terms. - --with-fam or - --with-inotify will enable the code for + or + will enable the code for real time indexing. Inotify support is enabled by default on recent Linux systems. - --disable-webkit is available + 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. - --enable-xattr will enable + will enable code to fetch data from file extended attributes. This is only useful is some application stores data in there, and also needs some simple configuration (see comments in the fields configuration file). - --enable-camelcase will enable + will enable splitting camelCase words. This is not enabled by default as it has the unfortunate side-effect of making some phrase searches quite @@ -3445,24 +3445,24 @@ while query.next >= 0 and query.next < nres: "my sql manual" but not "mysql manual" (only inside phrase searches). - --with-file-command Specify + 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. - --disable-qtgui Disable the Qt + Disable the Qt interface. Will allow building the indexer and the command line search program in absence of a Qt environment. - --disable-x11mon Disable + Disable X11 connection monitoring inside recollindex. Together with --disable-qtgui, this allows building recoll without Qt and X11. Of course the usual autoconf configure - options, like --prefix apply. + options, like apply. @@ -3502,7 +3502,7 @@ while query.next >= 0 and query.next < nres: system default or the value which was specified when executing configure (as in configure --prefix /some/path), you - will have to set the RECOLL_DATADIR + will have to set the RECOLL_DATADIR environment variable to indicate where the shared data is to be found (ie for (ba)sh: export RECOLL_DATADIR=/some/path/share/recoll). @@ -3551,7 +3551,7 @@ while query.next >= 0 and query.next < nres: directory. This location can be changed, or others can be added with the - RECOLL_CONFDIR environment variable or the + RECOLL_CONFDIR environment variable or the -c option parameter to recoll and recollindex. @@ -3564,8 +3564,8 @@ while query.next >= 0 and query.next < nres: indexing. recollindex will proceed immediately. To avoid mistakes, the automatic directory creation will only occur for the - default location, not if -c or - RECOLL_CONFDIR were used (in the latter + default location, not if or + RECOLL_CONFDIR were used (in the latter cases, you will have to create the directory). @@ -3622,7 +3622,7 @@ while query.next >= 0 and query.next < nres: configuration file should use the system default locale encoding. - The unac_except_trans parameter + 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 @@ -3660,16 +3660,16 @@ while query.next >= 0 and query.next < nres: - topdirs + topdirs Specifies the list of directories or files to index (recursively for directories). You can use symbolic links as elements of this list. See the - followLinks option about following symbolic links + followLinks option about following symbolic links found under the top elements (not followed by default). - skippedNames + skippedNames A space-separated list of patterns for names of files or directories that should be completely @@ -3682,7 +3682,7 @@ skippedNames = #* bin CVS Cache cache* caughtspam tmp .thumbnails .svn \ The list can be redefined at any sub-directory in the indexed area. The top-level directories are not affected by this - list (that is, a directory in topdirs + list (that is, a directory in topdirs might match and would still be indexed). The list in the default configuration does not exclude hidden directories (names beginning with a @@ -3692,30 +3692,30 @@ skippedNames = #* bin CVS Cache cache* caughtspam tmp .thumbnails .svn \ usually store messages in hidden directories, and you probably want this indexed. One possible solution is to have .* in - skippedNames, and add things like + skippedNames, and add things like ~/.thunderbird or ~/.evolution in - topdirs. + topdirs. Not even the file names are indexed for patterns in this list. See the - recoll_noindex variable in + recoll_noindex variable in mimemap for an alternative approach which indexes the file names. - skippedPaths and - daemSkippedPaths + skippedPaths and + daemSkippedPaths A space-separated list of patterns for paths of files or directories that should be skipped. There is no default in the sample configuration file, but the code always adds the configuration and database directories in there. - skippedPaths is used both by + skippedPaths is used both by batch and real time - indexing. daemSkippedPaths can be + indexing. daemSkippedPaths can be used to specify things that should be indexed at startup, but not monitored. Example of use for skipping text files only in a @@ -3727,13 +3727,13 @@ skippedPaths = ~/somedir/∗.txt - skippedPathsFnmPathname + skippedPathsFnmPathname The values in the - *skippedPaths variables are matched by + *skippedPaths variables are matched by default with fnmatch(3), with the FNM_PATHNAME and FNM_LEADING_DIR flags. This means that '/' characters must be matched explicitely. You can set - skippedPathsFnmPathname to 0 to disable + skippedPathsFnmPathname to 0 to disable the use of FNM_PATHNAME (meaning that /*/dir3 will match /dir1/dir2/dir3). @@ -3741,19 +3741,19 @@ skippedPaths = ~/somedir/∗.txt - followLinks + followLinks Specifies if the indexer should follow symbolic links while walking the file tree. The default is to ignore symbolic links to avoid multiple indexing of linked files. No effort is made to avoid duplication when this option is set to true. This option can be set - individually for each of the topdirs + individually for each of the topdirs members by using sections. It can not be changed below the - topdirs level. + topdirs level. - indexedmimetypes + indexedmimetypes &RCL; 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 @@ -3762,7 +3762,7 @@ skippedPaths = ~/somedir/∗.txt - compressedfilemaxkbs + compressedfilemaxkbs Size limit for compressed (.gz or .bz2) files. These need to be decompressed in a temporary directory for identification, which can be very wasteful @@ -3772,14 +3772,14 @@ skippedPaths = ~/somedir/∗.txt - textfilemaxmbs + textfilemaxmbs Maximum size for text files. Very big text files are often uninteresting logs. Set to -1 to disable (default 20MB). - textfilepagekbs + textfilepagekbs If set to other than -1, text files will be indexed as multiple documents of the given page size. This may be useful if you do want to index very big text files as it @@ -3789,7 +3789,7 @@ skippedPaths = ~/somedir/∗.txt - indexallfilenames + indexallfilenames &RCL; indexes file names in a special section of the database to allow specific file names searches using wild cards. This parameter decides if @@ -3800,7 +3800,7 @@ skippedPaths = ~/somedir/∗.txt - usesystemfilecommand + 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 @@ -3811,7 +3811,7 @@ skippedPaths = ~/somedir/∗.txt - processbeaglequeue + processbeaglequeue If this is set, process the directory where Beagle Web browser plugins copy visited pages for indexing. Of course, Beagle MUST NOT be running, else things will behave @@ -3819,7 +3819,7 @@ skippedPaths = ~/somedir/∗.txt - beaglequeuedir + beaglequeuedir The path to the Beagle indexing queue. This is hard-coded in the Beagle plugin as ~/.beagle/ToIndex so there should be no @@ -3840,7 +3840,7 @@ skippedPaths = ~/somedir/∗.txt - nonumbers + nonumbers If this set to true, no terms will be generated for numbers. For example "123", "1.5e6", 192.168.1.4, would not be indexed ("value123" would still be). Numbers are often quite @@ -3851,18 +3851,18 @@ skippedPaths = ~/somedir/∗.txt - nocjk + 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 + setting nocjk may be a significant time and space saver. - cjkngramlen + 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 @@ -3870,7 +3870,7 @@ skippedPaths = ~/somedir/∗.txt the index will be approximately twice as large. - indexstemminglanguages + indexstemminglanguages A list of languages for which the stem expansion databases will be built. See recollindex(1) or use the recollindex -l command for @@ -3882,7 +3882,7 @@ skippedPaths = ~/somedir/∗.txt - defaultcharset + defaultcharset The name of the character set used for files that do not contain a character set definition (ie: plain text files). This can be redefined for any @@ -3892,11 +3892,11 @@ skippedPaths = ~/somedir/∗.txt - unac_except_trans + unac_except_trans This is a list of characters, encoded in UTF-8, which should be handled specially when converting text to unaccented lowercase. For example, in Swedish, the letter - a with diaeresis has full alphabet + a with diaeresis has full alphabet citizenship and should not be turned into an a. Each element in the space-separated list has the special character as first element and the translation @@ -3919,7 +3919,7 @@ unac_except_trans = - maildefcharset + maildefcharset This can be used to define the default character set specifically for email messages which don't specify it. This is mainly useful for readpst (libpst) dumps, @@ -3927,7 +3927,7 @@ unac_except_trans = - localfields + localfields This allows setting fields for all documents under a given directory. Typical usage would be to set an "rclaptg" field, to be used in mimeview to @@ -3947,7 +3947,7 @@ unac_except_trans = Parameters affecting where and how we store things: - dbdir + dbdir The name of the Xapian data directory. It will be created if needed when the index is initialized. If this is not an absolute path, it will be @@ -3957,7 +3957,7 @@ unac_except_trans = - idxstatusfile + idxstatusfile The name of the scratch file where the indexer process updates its status. Default: idxstatus.txt inside the configuration @@ -3965,7 +3965,7 @@ unac_except_trans = - maxfsoccuppc + maxfsoccuppc Maximum file system occupation before we stop indexing. The value is a percentage, corresponding to what the "Capacity" df output column shows. The default @@ -3973,7 +3973,7 @@ unac_except_trans = - mboxcachedir + mboxcachedir The directory where mbox message offsets cache files are held. This is normally $RECOLL_CONFDIR/mboxcache, but it may be useful to share a directory between different @@ -3981,14 +3981,14 @@ unac_except_trans = - mboxcacheminmbs + mboxcacheminmbs The minimum mbox file size over which we cache the offsets. There is really no sense in caching offsets for small files. The default is 5 MB. - webcachedir + webcachedir This is only used by the Beagle web browser plugin indexing code, and defines where the cache for visited pages will live. Default: @@ -3996,7 +3996,7 @@ unac_except_trans = - webcachemaxmbs + webcachemaxmbs This is only used by the Beagle web browser plugin indexing code, and defines the maximum size for the web page cache. Default: 40 MB. @@ -4004,7 +4004,7 @@ unac_except_trans = - idxflushmb + idxflushmb Threshold (megabytes of new text data) where we flush from memory to disk index. Setting this can help control memory usage. A value of 0 means no explicit flushing, letting @@ -4023,7 +4023,7 @@ unac_except_trans = - loglevel,daemloglevel + loglevel,daemloglevel Verbosity level for recoll and recollindex. A value of 4 lists quite a lot of debug/information messages. 2 only lists errors. The @@ -4032,8 +4032,8 @@ unac_except_trans = - logfilename, - daemlogfilename + logfilename, + daemlogfilename Where the messages should go. 'stderr' can be used as a special value, and is the default. The daemversion is specific to the indexing monitor @@ -4042,7 +4042,7 @@ unac_except_trans = - mondelaypatterns + mondelaypatterns This allows specify wildcard path patterns (processed with fnmatch(3) with 0 flag), to match files which change too often and for which a delay should be observed before @@ -4056,7 +4056,7 @@ mondelaypatterns = *.log:20 "this one has spaces*:10" - monixinterval + monixinterval Minimum interval (seconds) for processing the indexing queue. The real time monitor does not process each event when it comes in, but will wait this time for the queue @@ -4065,7 +4065,7 @@ mondelaypatterns = *.log:20 "this one has spaces*:10" - monauxinterval + monauxinterval Period (in seconds) at which the real time monitor will regenerate the auxiliary databases (spelling, stemming) if needed. The default is one hour. @@ -4075,13 +4075,13 @@ mondelaypatterns = *.log:20 "this one has spaces*:10" - filtermaxseconds + filtermaxseconds Maximum filter execution time, after which it is aborted. Some postscript programs just loop... - filtersdir + filtersdir A directory to search for the external filter scripts used to index some types of files. The value should not be changed, except if you want to modify @@ -4090,7 +4090,7 @@ mondelaypatterns = *.log:20 "this one has spaces*:10" - iconsdir + iconsdir The name of the directory where recoll result list icons are stored. You can change this if you want different @@ -4098,14 +4098,14 @@ mondelaypatterns = *.log:20 "this one has spaces*:10" - idxabsmlen + idxabsmlen &RCL; stores an abstract for each indexed file inside the database. The text can come from an actual 'abstract' section in the document or will just be the beginning of the document. It is stored in the index so that it can be displayed inside the result lists without decoding the original - file. The idxabsmlen parameter defines + file. The idxabsmlen parameter defines the size of the stored abstract. The default value is 250 bytes. The search interface gives you the choice to display this stored text or a synthetic abstract built by extracting @@ -4116,7 +4116,7 @@ mondelaypatterns = *.log:20 "this one has spaces*:10" - aspellLanguage + aspellLanguage Language definitions to use when creating the aspell dictionary. The value must match a set of aspell language definition files. You can type "aspell @@ -4127,7 +4127,7 @@ mondelaypatterns = *.log:20 "this one has spaces*:10" - noaspell + noaspell 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 @@ -4240,20 +4240,20 @@ x-my-tag = mailmytag are usually all located in one place. mimemap also has a - recoll_noindex variable which is a list of + recoll_noindex variable which is a list of suffixes. Matching files will be skipped (which avoids unnecessary decompressions or file executions). This is partially redundant with - skippedNames in the main configuration + skippedNames in the main configuration file, with a few differences: it will not affect directories, it cannot be made dependant on the file-system location (it is a configuration-wide parameter), and the file names will still be indexed (not even the file names are indexed for patterns - in skippedNames. - recoll_noindex is used mostly for things + in skippedNames. + recoll_noindex is used mostly for things known to be unindexable by a given &RCL; version. Having it there avoids cluttering the more user-oriented and locally - customized skippedNames. + customized skippedNames. @@ -4307,11 +4307,11 @@ x-my-tag = mailmytag 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 + filesystem (using a localfields specification in mimeconf). The syntax for the key is mimetype|tag - The nouncompforviewmts entry, (placed at + 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: