diff --git a/src/doc/user/usermanual.sgml b/src/doc/user/usermanual.sgml index 5bb65df9..7a1d8eb3 100644 --- a/src/doc/user/usermanual.sgml +++ b/src/doc/user/usermanual.sgml @@ -195,7 +195,7 @@ - Periodic indexing: + Periodic (or Batch) indexing: indexing takes place at discrete times, by executing the recollindex command. The typical usage is to have a nightly indexing run @@ -336,8 +336,9 @@ recoll total amount of data on the computer. The index data directory (xapiandb) - only contains data that can be completely rebuilt by an index - run, and it can always be destroyed safely. + only contains data that can be completely rebuilt by an index run + (as long as the original documents exist), and it can always be + destroyed safely. Xapian index formats @@ -405,7 +406,7 @@ recoll will be asked whether or not you would like it to build the index. If you want to adjust the configuration before indexing, just click Cancel at this point, which will get - you into the configuration interface. If you exit, + you into the configuration interface. If you exit at this point, recoll will have created a ~/.recoll directory containing empty configuration files, which you can edit by hand. @@ -485,6 +486,12 @@ recoll Recoll wiki. + Unfortunately, it seems that the plugin does not work anymore + with recent Firefox versions (tried with 10.0). This is not the + trival installation version check issue, explicit manual indexing + requests still work, but automatic indexing on page load does + not. + @@ -493,50 +500,26 @@ recoll Running indexing - Indexing is performed either by the - recollindex program, or by the indexing thread - inside the recoll program (start it from the - File menu). Both programs will use the + Indexing is always performed by the + recollindex program, which can be started + either from the command line or from the File + menu in the recoll GUI program. When started + 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 to specify a non-default configuration directory. - There are reasons to use either the indexing thread or the - recollindex command, but it is also a matter of - personal preferences: - - Starting the indexing thread is more convenient, - being just one click away. - - The recollindex command has - more options, especially the one to reset the index - (-z). - - The recollindex command will - not take down your GUI if it crashes (a rare occurrence, - but who knows...) - - The recollindex command uses - setpriority/nice to lower its priority - while indexing. When available (and for &RCL; version - 1.16.2 and newer), it also uses the - ionice command to lower its IO - priority. The thread can't do it, else it would also slow - down the user/search interface. - - - - If the recoll program finds no index when it starts, it will automatically start indexing (except if canceled). The recollindex indexing process can be - interrupted by sending an - interrupt (^C, SIGINT) or terminate (SIGTERM) signal. Some time may - elapse before the process exits, because it needs to properly flush - and close the index. The indexing thread can be equivalently - stopped from the menu. + interrupted by sending an interrupt (^C, SIGINT) or terminate + (SIGTERM) signal. Some time may elapse before the process exits, + because it needs to properly flush and close the index. The + indexing thread can be equivalently stopped from the menu. After such an interruption, the index will be somewhat inconsistent because some operations which are normally performed @@ -585,6 +568,13 @@ recoll 1 15 su mylogin -c "recollindex recollindex > /tmp/rcltraceme 2>&1" + As of version 1.17 the &RCL; GUI has dialogs to manage + crontab entries for + recollindex. You can reach them from the + Preferences->Indexing Schedule menu. They only + work with the good old cron, and do not give + access to all features of cron scheduling. + The usual command to edit your crontab is crontab -e (which will usually start @@ -593,10 +583,11 @@ recoll system. Please be aware that there may be differences between your - usual interactive command line environment and the one seen by - crontab commands. Especially the PATH variable may be of - concern. Please check the crontab manual pages about possible - issues. + usual interactive command line environment and the one seen by + crontab commands. Especially the PATH variable may be of + concern. Please check the crontab manual pages about possible + issues. + @@ -605,27 +596,28 @@ recoll Real time indexing Real time monitoring/indexing is performed by starting the - recollindex -m command. With this option, - recollindex will detach from the terminal and - become a daemon, permanently monitoring file changes and updating - the index. + recollindex -m command. With this option, + recollindex will detach from the terminal and + become a daemon, permanently monitoring file changes and updating + the index. - The real time indexing support can be customised during package - configuration - with the --with[out]-fam or - --with[out]-inotify options. The default is - currently to include inotify monitoring on systems that support - it, and, as of recoll 1.17, gamin support on FreeBSD. + Under KDE, Gnome and some other desktop environments, the daemon + can automatically started when you log in, by creating a desktop + file inside the ~/.config/autostart directory. + This can be done for you by the &RCL; GUI. Use the + Preferences->Indexing Schedule menu. + + With older X11 setups, starting the daemon is normally + performed as part of the user session script. The rclmon.sh script can be used to easily start and stop the daemon. It can be found in the examples directory (typically /usr/local/[share/]recoll/examples). - Starting the daemon is normally performed as part - of the user session script. For example, my out of fashion - xdm-based session has a .xsession script - with the following lines at the end: + For example, my out of fashion xdm-based session has a + .xsession script with the following lines at + the end: recollconf=$HOME/.recoll-home recolldata=/usr/local/share/recoll @@ -636,24 +628,15 @@ fvwm The indexing daemon gets started, then the window manager, - for which the session waits. By default the - 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). - - - Under KDE, you can place a small script to start - recollindex -m under - $HOME/.kde/Autostart. This will be executed - when the session begins. - - There is a similar mechanism under Gnome (find the session - control tool in the menus and use the "Startup programs" tab). + for which the session waits. By default the + 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). If you use the daemon completely out of an X11 session, you - need to add option -x to disable X11 session - monitoring (else the daemon will not start). + need to add option -x 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 @@ -663,6 +646,14 @@ fvwm daemon runs permanently, the log file may grow quite big, depending on the log level. + 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 + currently to include inotify monitoring on systems that support + it, and, as of recoll 1.17, gamin support on FreeBSD. + While it is convenient that data is indexed in real time, repeated indexing can generate a significant load on the system when files such as email folders change. Also, @@ -3319,6 +3310,11 @@ while query.next >= 0 and query.next < nres: real time indexing. Inotify support is enabled by default on recent Linux systems. + --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. --enable-xattr will enable code to fetch data from file extended attributes. This is only useful is some application stores data in there, and also needs diff --git a/website/howtos/buildindex.sh b/website/howtos/buildindex.sh deleted file mode 100644 index 775159e9..00000000 --- a/website/howtos/buildindex.sh +++ /dev/null @@ -1,26 +0,0 @@ -#!/bin/sh -# Build howto index page from howto subdirs - -fatal() -{ - echo $*;exit 1 -} -#set -x - -test -f fraghead.html || \ - fatal repertoire courant pas un repertoire de construction - -cat fraghead.html > index.html -subdirs=`ls -F | grep /` - -for dir in $subdirs -do - echo processing $dir - title=`grep '

' $dir/index.html | sed -e 's/

//' -e 's!

!!'` - test "$title" = "" && fatal No title line in $dir/index.html - - # Add title/label to list of articles - echo "
  • $title
    • " >> index.html -done - -cat fragend.html >> index.html diff --git a/website/howtos/fragend.html b/website/howtos/fragend.html deleted file mode 100644 index 811dd310..00000000 --- a/website/howtos/fragend.html +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/website/howtos/fraghead.html b/website/howtos/fraghead.html deleted file mode 100644 index 0c4fcbde..00000000 --- a/website/howtos/fraghead.html +++ /dev/null @@ -1,40 +0,0 @@ - - - - - Recoll howtos - - - - - - - - - - - - - - -
    - -
    - -
    - -

    Recoll howtos

    - -

    The following short documents contain information - mostly extracted from the main user manual (possibly out of - separate sections), arranged differently in order to explain - how to achieve a given goal.

    - -
      diff --git a/website/howtos/index.html b/website/howtos/index.html deleted file mode 100644 index cee9fff2..00000000 --- a/website/howtos/index.html +++ /dev/null @@ -1,47 +0,0 @@ - - - - - Recoll howtos - - - - - - - - - - - - - - -
      - -
      - -
      - -

      Recoll howtos

      - -

      The following short documents contain information - mostly extracted from the main user manual (possibly out of - separate sections), arranged differently in order to explain - how to achieve a given goal.

      - - - -
      - - diff --git a/website/howtos/newdir.sh b/website/howtos/newdir.sh deleted file mode 100644 index 24770e60..00000000 --- a/website/howtos/newdir.sh +++ /dev/null @@ -1,22 +0,0 @@ -#!/bin/sh - -fatal() -{ - echo $*; exit 1 -} -usage() -{ - fatal 'Usage: newdir nom' -} - -test $# -gt 1 || usage - -dir=`echo $* | sed -e 's/ /_/g' -e 's!/!_!g'` - -echo dir: $dir - -mkdir $dir || fatal mkdir failed - -cp -i template.html $dir/index.html - -open -a emacs $dir/index.html diff --git a/website/howtos/prevent_indexing_a_directory/index.html b/website/howtos/prevent_indexing_a_directory/index.html deleted file mode 100644 index 9034d364..00000000 --- a/website/howtos/prevent_indexing_a_directory/index.html +++ /dev/null @@ -1,68 +0,0 @@ - - - - - Recoll howtos - - - - - - - - - - - - - - -
      - -
      - -
      - -

      Preventing indexing in a directory

      - -

      Why would you want to do this ?

      -

      By default, recollindex (or the indexing thread inside the - recoll QT user interface) will process your home directories and - most its subdirectories, at the exception of some well known - places (thumbnails, beagle and web browser caches, etc.)

      - -

      You may want to prevent indexing in some directories where - you don't expect interesting search results. This will avoid - polluting the search result lists, speed up indexing times and - make the index smaller.

      - -

      How to do it

      -

      There are two ways to block indexing at certain points: - either by listing specific paths, or by directory name pattern - matches.

      -
        -
      • Blocking specific paths: this is controlled by - the skippedPaths variable in the main configuration - file. You can adjust the value either by editing the file or - by using the indexing configuration dialog: - Preferences->Indexing configuration->Global parameters->Skipped paths
        • - -
      • Using pattern matches: these are listed in the - skippedNames variable in the main configuration file. You - can adjust the value either by editing the file or by using - the GUI: - Preferences->Indexing configuration->Local parameters->Skipped names
        • - -
      - - -
      - - diff --git a/website/howtos/template.html b/website/howtos/template.html deleted file mode 100644 index 7046ee91..00000000 --- a/website/howtos/template.html +++ /dev/null @@ -1,40 +0,0 @@ - - - - - Recoll howtos - - - - - - - - - - - - - - -
      - -
      - -
      - -

      Howto do something

      -

      Why would you want to do this ?

      -

      How to do it

      - - -
      - - diff --git a/website/howtos/use_multiple_indexes/index.html b/website/howtos/use_multiple_indexes/index.html deleted file mode 100644 index 0c1c40c0..00000000 --- a/website/howtos/use_multiple_indexes/index.html +++ /dev/null @@ -1,109 +0,0 @@ - - - - - Recoll howtos - - - - - - - - - - - - - - -
      - -
      - -
      - -

      Creating and using multiple indexes

      - -

      Why would you want to do this ?

      -
        -
      • Easy adjustment of search areas: you can filter - results by using the directory filter in the advanced search - panel, but, if you have separate well defined places where - you store different kind of data, it is easier to maintain - separate index and use the External indexes dialog - to switch them on or off, and it will also yield much better - search performance.
        • -
      • Shared indexes: it may be useful to maintain one or - several indexes for shared data, and separate personal - indexes for each user.
        • -
      - -

      How to do it

      - -

      As an example we'll suppose that you - have Recoll installed and indexing your - home directory, and that you would like to have a separate index - for /usr/shared/doc.

      - -

      You need to create a separate configuration for the new index, - then add it to the external indexes list in the user - interface, and activate it as needed.

      - -
        -
      1. Create a directory for the new index: - 
        cd
-mkdir .recoll-sharedoc
-
        -
        2. -
      2. Create a minimal configuration file: - 
        cd .recoll-sharedoc
-echo "topdirs = /usr/share/doc" > recoll.conf
-
        -
        3. -
      3. Perform initial indexing: - 
        recollindex -c ~/.recoll-sharedoc
        -
        4. -
      4. Optionally set up cron to perform nightly indexing, use - 
        crontab -e
        - and insert a line like the following: - 
        45 20 * * * recollindex -c ~/.recoll-sharedoc
        - This would start the indexing at - 20:45. crontab -e will use the - vi editor by default, you can - change this by using the EDITOR - environment variable. Exemple: - 
        EDITOR=kate crontab -e
        - Your favorite desktop may also have a dedicated tool to add - crontab entries. -
        5. -
      5. Start recoll and choose - the Preferences->External index dialog - menu entry, then click the Browse button - (near the bottom), and select the new index Xapian database - directory: - 
        ~/.recoll-sharedoc/xapiandb
        - Then click Add index. -
        6. -
      6. You can then activate or deactivate the new index by - clicking the box in front of the directory name in the list. -
        7. -
      - -

      When adding an index shared by multiple users, it may - be helpful to use - the RECOLL_EXTRA_DBS environment - variable instead of editing individual configurations, see the - manual for more details.

      - -
      - -