From 0965ce6dc6f28deeaa0bd0e3e769ab5817f8f2dc Mon Sep 17 00:00:00 2001 From: "\"Jean-Francois Dockes ext:(%22)" Date: Thu, 19 Apr 2012 21:39:47 +0200 Subject: [PATCH] Applied a bunch of markup corrections and improvements as suggested by JCP, our kind Spanish translator and docbook guru --- src/doc/user/usermanual.sgml | 286 +++++++++++++++++++++-------------- 1 file changed, 175 insertions(+), 111 deletions(-) diff --git a/src/doc/user/usermanual.sgml b/src/doc/user/usermanual.sgml index 966c6f97..ff5cd9cc 100644 --- a/src/doc/user/usermanual.sgml +++ b/src/doc/user/usermanual.sgml @@ -214,7 +214,7 @@ they have been modified. On the first execution, all documents will need processing. A full index build can be forced later by specifying an option to the indexing command - (recollindex -z). + (recollindex ). &RCL; indexing can be performed with two different methods: @@ -274,7 +274,10 @@ section. After every indexing operation, &RCL; updates a list of commands that would be needed for indexing existing files types. This list can be displayed by selecting the menu option - File->Show Missing Helpers + + File + Show Missing Helpers + in the recoll GUI. It is stored in the missing text file inside the configuration directory. @@ -434,25 +437,32 @@ recoll The first time you start recoll, you 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 at this point, - recoll will have created a ~/.recoll directory - containing empty configuration files, which you can edit by hand. + 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 at this point, recoll will have + created a ~/.recoll directory containing + empty configuration files, which you can edit by hand. The configuration is documented inside the installation chapter - of this document, or in the recoll.conf(5) man page, but the most + of this document, or in the + + recoll.conf + 5 + + man page, but the most current information will most likely be the comments inside the sample file. The most immediately useful variable you may interested in is probably - topdirs, + + 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 + packages section. The indexing configuration GUI @@ -464,8 +474,11 @@ recoll option.) The interface is started from the - Preferences->Indexing - Configuration menu entry. It is divided in three tabs, + + Preferences + Indexing Configuration + + menu entry. It is divided in three tabs, Global parameters, Local parameters, and Beagle web history, which is explained in the next section. @@ -498,7 +511,9 @@ recoll Using Beagle WEB browser plugins Beagle is (was?) a concurrent desktop - indexer, built on Lucene and the Mono project (C#), for which a + indexer, built on Lucene and + the Mono project + (C#), for which a number of add-on browser plugins were written. These work by copying visited web pages to an indexing queue directory, which the indexer then processes. Especially, there is a @@ -507,7 +522,9 @@ recoll If, for any reason, you so happen to prefer &RCL; to Beagle, you can still use the Firefox plugin, which is written in - Javascript and completely independant of C#, Beagle, Lucene..., and + Javascript and completely independant of + C#, Beagle, + Lucene..., and set &RCL; to process the Beagle queue directory. This supposes that Beagle is not running, else both programs will fight for the same @@ -523,7 +540,8 @@ 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 + 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. @@ -552,11 +570,15 @@ recoll if canceled). The recollindex indexing process can be - interrupted by sending an interrupt (Ctrl-C, SIGINT) or terminate + interrupted by sending an interrupt (Ctrl-C, + SIGINT) or terminate (SIGTERM) signal. Some time may elapse before the process exits, because it needs to properly flush and close the index. This can also be done from the recoll GUI - File->Stop Indexing + + File + Stop Indexing + menu entry. After such an interruption, the index will be somewhat @@ -575,17 +597,23 @@ recoll Of special interest maybe are the and options. allows indexing an explicit list of files (given as command line - parameters or read on stdin). 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 file selection method to build the file list to be fed to - recollindex -if . + recollindex . + Trivial example: + + find . -name indexable.txt -print | recollindex -if + - recollindex -i will not descend into - directory parameters, but just add them as index entries. It is + recollindex will + not descend into subdirectories specified as parameters, + but just add them as index entries. It is up to the external file selection method to build the complete file list. @@ -600,26 +628,32 @@ recoll 3:30AM (supposing recollindex is in your PATH): - 30 3 * * * recollindex > /some/tmp/dir/recolltrace 2>&1 + /some/tmp/dir/recolltrace 2>&1 +]]> Or, using anacron: -1 15 su mylogin -c "recollindex recollindex > /tmp/rcltraceme 2>&1" + /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 + + 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 - the vi editor to edit the file). You may - have more sophisticated tools available on your - system. + crontab is crontab + (which will usually start the + vi editor to edit the file). You may have + more sophisticated tools available on your system. Please be aware that there may be differences between your usual interactive command line environment and the one seen by @@ -635,28 +669,32 @@ 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 command. + With this option, recollindex will detach + from the terminal and become a daemon, permanently monitoring + file changes and updating the index. - 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. + 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. + 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). - 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 @@ -670,12 +708,14 @@ fvwm 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 - to recollindex). + explicitly. (The X11 server + monitoring can be disabled with option to + recollindex). - If you use the daemon completely out of an X11 session, you - need to add option to disable X11 session - monitoring (else the daemon will not start). + If you use the daemon completely out of an + X11 session, you 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 @@ -687,12 +727,13 @@ fvwm When building &RCL;, the real time indexing support can be customised during package configuration with the - or + linkend="rcl.install.building.build">configuration with + the 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. + currently to include inotify + monitoring on systems that support it, and, as of &RCL; 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 @@ -867,8 +908,12 @@ fvwm you have to care about the syntax. You can use the - Tools / Advanced search - dialog for more complex searches. + + Tools + Advanced search + + dialog for more complex searches. + @@ -904,7 +949,8 @@ fvwm the Use desktop preferences option in the user preferences dialog to use the desktop defaults for all documents. This is probably the best option if you are using a well - configured Gnome or KDE desktop. + configured Gnome or + KDE desktop. The Preview and Open edit links may not be present for all entries, meaning that @@ -1961,25 +2007,31 @@ fvwm by the message filters. The default value for the paragraph format string is: - <img src="%I" align="left">%R %S %L &nbsp;&nbsp;<b>%T</b><br> -%M&nbsp;%D&nbsp;&nbsp;&nbsp;<i>%U</i>&nbsp;%i<br> + %R %S %L   %T
+%M %D   %U %i
%A %K - +]]> + You may, for example, try the following for a more web-like experience: - <u><b><a href="P%N">%T</a></b></u><br> -%A<font color=#008000>%U - %S</font> - %L - - Or the clean looking: - <img src="%I" align="left">%L <font color="#900000">%R</font> -  <b>%T</b><br>%S  -<font color="#808080"><i>%U</i></font> -<table bgcolor="#e0e0e0"> -<tr><td><div>%A</div></td></tr> -</table>%K - - Note that the P%N link in the above paragraph makes the title a - preview link. + + %T
+%A%U - %S - %L +]]> + + Note that the P%N link in the above paragraph makes the title a + preview link. Or the clean looking: + + %L %R +  %T&
%S  +%U + + +
%A
%K +]]> These samples, and some others are @@ -3338,14 +3390,14 @@ while query.next >= 0 and query.next < nres: manifest itself by strange messages about a missing iconv_open. - Development files for - - Xapian core. If you - are building Xapian for an older CPU (before Pentium 4 or Athlon - 64), you need to add the --disable-sse flag to the configure - command. Else all Xapian application will crash with an - illegal instruction error. - + Development files for Xapian + core. If you are + building Xapian for an older CPU (before Pentium 4 or Athlon + 64), you need to add the flag + to the configure command. Else all Xapian application will + crash with an illegal instruction + error. Development files for @@ -3455,11 +3507,14 @@ while query.next >= 0 and query.next < nres: interface. Will allow building the indexer and the command line search program in absence of a Qt environment. - Disable - X11 connection monitoring inside recollindex. Together with - --disable-qtgui, this allows building recoll without Qt and - X11. - + + 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 apply. @@ -3483,8 +3538,10 @@ while query.next >= 0 and query.next < nres: directory to mk/sysconf. If your system is not known yet, it will tell you as much, and you may want to manually copy and modify one of the existing files (the new - file name should be the output of uname -s). - + file name should be the output of uname + ). + + Installation @@ -3552,7 +3609,7 @@ while query.next >= 0 and query.next < nres: This location can be changed, or others can be added with the RECOLL_CONFDIR environment variable or the - -c option parameter to recoll and + option parameter to recoll and recollindex. If the .recoll directory does not @@ -3632,6 +3689,7 @@ while query.next >= 0 and query.next < nres: configuration. + Main configuration file @@ -3801,15 +3859,15 @@ skippedPaths = ~/somedir/∗.txt 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. - - + Decide if we use the + file 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. + + processbeaglequeue If this is set, process the directory where @@ -3870,16 +3928,19 @@ skippedPaths = ~/somedir/∗.txt the index will be approximately twice as large. + indexstemminglanguages A list of languages for which the stem - expansion databases will be built. See recollindex(1) or - use the recollindex -l command for - possible values. You can add a stem expansion database for - a different language by using recollindex - -s, but it will be deleted during the next - indexing. Only languages listed in the configuration - file are permanent. - + expansion databases will be built. See + recollindex + 1 or use the + recollindex command + for possible values. You can add a stem expansion database + for a different language by using + recollindex , but it + will be deleted during the next indexing. Only languages + listed in the configuration file are permanent. + defaultcharset @@ -3887,8 +3948,10 @@ skippedPaths = ~/somedir/∗.txt files that do not contain a character set definition (ie: plain text files). This can be redefined for any sub-directory. If it is not set at all, the character set - used is the one defined by the nls environment (LC_ALL, - LC_CTYPE, LANG), or iso8859-1 if nothing is set. + used is the one defined by the nls environment ( + LC_ALL, LC_CTYPE, + LANG), or iso8859-1 + if nothing is set. @@ -3905,12 +3968,12 @@ skippedPaths = ~/somedir/∗.txt the list will turn-off both standard accent and case processing. Example for Swedish: -unac_except_trans = åå Åå ää Ää öö Öö +unac_except_trans = åå Ã…Ã¥ ää Ää öö Öö Note that the translation is not limited to a single character, you could very well have something like - üue in the list. + üue in the list. This parameter can't be defined for subdirectories, it is global, because there is no way to do otherwise when @@ -4228,7 +4291,8 @@ x-my-tag = mailmytag 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 + one, the system's file + command will be executed to determine the mime type (this can be switched off inside the main configuration file).