diff --git a/src/doc/user/usermanual.sgml b/src/doc/user/usermanual.sgml index 1ff4b09b..99553ed9 100644 --- a/src/doc/user/usermanual.sgml +++ b/src/doc/user/usermanual.sgml @@ -24,7 +24,7 @@ Dockes - $Id: usermanual.sgml,v 1.21 2006-09-29 11:43:45 dockes Exp $ + $Id: usermanual.sgml,v 1.22 2006-10-12 08:39:55 dockes Exp $ This document introduces full text search notions @@ -218,25 +218,57 @@ In some cases, it may be interesting to index different areas of the file system to separate databases. You can do this by using multiple configuration directories, each indexing a - file system area to a specific database. You would use the - RECOLL_CONFDIR environment variable or the - -c confdir option - to recollindex to indicate which - configuration to process. The recoll search - program can use any selection of the existing databases for each - search, this is configurable inside the user interface. + file system area to a specific database. See the section about using multiple + databases for more information on multiple configurations + and indexes. Index storage The default location for the index data is the - $HOME/.recoll/xapiandb/ directory. This can - be changed by setting the RECOLL_CONFDIR - environment variable, or by specifying the - dbdir parameter in the configuration file - (see the configuration - section). + xapiandb subdirectory of the &RCL; + configuration directory, typically + $HOME/.recoll/xapiandb/. This can be + changed via two different methods (with different purposes): + + + + You can specify a different configuration + directory by setting the RECOLL_CONFDIR + environment variable, or using the -c + 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 + following commands: + +export RECOLL_CONFDIR=~/.indexes-email +recoll + Then &RCL; would use configuration files + stored in ~/.indexes-email/ and, + (unless specified otherwise in + recoll.conf) would look for + the index in ~/.indexes-email/xapiandb/. + + Using multiple configuration directories and + configuration + options allows you to tailor multiple configurations + and indexes to handle whatever subset of the available data + that you wish to make searchable. + + + You can also specify a different storage + 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 + wanted to keep the configuration directory in its default location, + but desired another location for the index, typically out of + disk occupation concerns. + + + The size of the index is determined by the size of the set of documents, but the ratio can vary a lot. For a typical mixed @@ -254,8 +286,8 @@ total amount of data on the computer. The index data directory (xapiandb) - only contains data that will be rebuilt by an index run, and it - can always be destroyed safely. + only contains data that can be completely rebuilt by an index + run, and it can always be destroyed safely. Security aspects @@ -282,28 +314,32 @@ The indexing configuration - Values set in the system-wide configuration file (named - like - /usr/[local/]share/recoll/examples/recoll.conf) - can be overridden by those set in the personal one, named - $HOME/.recoll/recoll.conf by default or - $RECOLL_CONFDIR/recoll.conf if - RECOLL_CONFDIR is set. + You can control which areas of the file system are + indexed, and how files are processed, by setting variables inside + the &RCL; configuration + files. - The most accurate documentation for editing the file is - given by comments inside the central one. If you want to adjust - the configuration before indexing, just click - Cancel when the program asks if it should - start initial indexing. This will have created a - .recoll directory containing empty + 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. + + The first time you start recoll, you + will be asked whether or not you would like recoll to build the + index. If you want to adjust the configuration before indexing, + just click Cancel at this point. That way, + recoll will have created a ~/.recoll directory containing empty configuration files. - The configuration is also documented inside the installation chapter of - this document, or in the recoll.conf(5) man page. + The configuration is documented inside the installation chapter of + this document, or in the recoll.conf(5) man page. The most + immediately useful variable you may interested in is probably 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 + text, HTML or email (ie: pdf, postscript, ms-word...) are described in the external packages section @@ -327,8 +363,8 @@ It is best to avoid interrupting the indexing process, as this may sometimes leave the index in a bad state. This is - not a serious problem, as you then just need to clear - everything and restart the indexing: the index files are + not a serious problem, as you then just need to delete + the index files and restart the indexing. The index files are normally stored in the $HOME/.recoll/xapiandb directory, which you can just delete if needed. Alternatively, you can start recollindex with option @@ -1101,6 +1137,20 @@ Configuration overview + Most of the parameters specific to the + recoll GUI are set through the + Preferences menu and stored in the + standard QT place + ($HOME/.qt/recollrc). You probably do not + want to edit this by hand. + + For other options, &RCL; uses text configuration + files. You will have to edit them by hand for + now (there is still some hope for a GUI configuration tool + in the future). The most accurate documentation for the + configuration parameters is given by comments inside the default + files, and we will just give a general overview here. + There are two sets of configuration files. The system-wide files are kept in a directory named like /usr/[local/]share/recoll/examples, @@ -1120,19 +1170,6 @@ indexing. recollindex will proceed immediately. - Most of the parameters specific to the - recoll GUI are set through the - Preferences menu and stored in the - standard QT place - ($HOME/.qt/recollrc). You probably do not - want to edit this by hand. - - For other options, &RCL; uses text configuration - files. You will have to edit them by hand for - now (there is still some hope for a GUI configuration tool - in the future). The most accurate documentation for the - configuration parameters is given by comments inside the default - files, and we will just give a general overview here. All configuration files share the same format. For example, a short extract of the main configuration file might @@ -1158,10 +1195,12 @@ - Section lines allow redefining some parameters for a - directory sub-tree. Some of the parameters used for indexing - are looked up hierarchically from the more to the less - specific. Not all parameters can be meaningfully redefined, + Section definitions allow redefining some parameters for + a directory sub-tree. They stay in effect until another + section definition, or the end of file, is encountered. Some + of the parameters used for indexing are looked up + hierarchically from the current directory location + upwards. Not all parameters can be meaningfully redefined, this is specified for each in the next section. The tilde character (~) is expanded in file names to the @@ -1191,7 +1230,8 @@ - topdirs + + topdirs Specifies the list of directories or files to index (recursively for directories). The indexer will not follow symbolic links inside the indexed trees. If an entry in