diff --git a/.hgignore b/.hgignore index b703e288..2dfec0ca 100644 --- a/.hgignore +++ b/.hgignore @@ -31,8 +31,10 @@ src/doc/user/rcl.kicker-applet.html src/doc/user/rcl.program.api.html src/doc/user/rcl.program.fields.html src/doc/user/rcl.program.html +src/doc/user/rcl.search.commandline.html src/doc/user/rcl.search.complex.html src/doc/user/rcl.search.custom.html +src/doc/user/rcl.search.desktop.html src/doc/user/rcl.search.history.html src/doc/user/rcl.search.html src/doc/user/rcl.search.lang.html diff --git a/src/doc/user/usermanual.sgml b/src/doc/user/usermanual.sgml index 48eb6c80..93cab3b5 100644 --- a/src/doc/user/usermanual.sgml +++ b/src/doc/user/usermanual.sgml @@ -620,6 +620,9 @@ fvwm + Searching + + Searching with the Qt graphical user interface The recoll program provides the main user @@ -653,7 +656,7 @@ fvwm case (they would typically be printed without white space). - + Simple search @@ -733,9 +736,9 @@ fvwm You can use the Tools / Advanced search dialog for more complex searches. - + - + The result list After starting a search, a list of results will instantly @@ -797,7 +800,7 @@ fvwm results. - + The result list right-click menu Apart from the preview and edit links, you can display a @@ -851,10 +854,10 @@ fvwm exemple to start a chm viewer on the parent document for a help page. - - + + - + The preview window The preview window opens when you first click a @@ -908,203 +911,15 @@ fvwm ^P (Ctrl + P) in the window text. + - - - - The query language - - The query language processor is activated on the - simple search entry when the search mode selector is set to - Query Language. - - The language is roughly based on the - Xesam user search language specification. - - Here follows a sample request that we are going to - explain: - - - author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes - - - This would search for all documents with - John Doe - appearing as a phrase in the author field (exactly what this is - would depend on the document type, ie: the - From: header, for an email message), - and containing either beatles or - lennon and either - live or - unplugged but not - potatoes (in any part of the document). - - An element is composed of an optional field specification, - and a value, separated by a colon. Exemple: - Beatles, - author:balzac, - dc:title:grandet - - The colon, if present, means "contains". Xesam defines other - relations, which are not supported for now. - - All elements in the search entry are normally combined - with an implicit AND. It is possible to specify that elements be - OR'ed instead, as in Beatles - OR Lennon. The - OR must be entered literally (capitals), and - it has priority over the AND associations: - word1 - word2 OR - word3 - means - word1 AND - (word2 OR - word3) - not - (word1 AND - word2) OR - word3. Do not enter explicit - parenthesis, they are not supported for now. - - An element preceded by a - specifies a - term that should not appear. Pure negative - queries are forbidden. - - As usual, words inside quotes define a phrase - (the order of words is significant), so that - title:"prejudice pride" is not the same as - title:prejudice title:pride, and is - unlikely to find a result. - - &RCL; currently manages the following default fields: - - title, - subject or caption are - synonyms which specify data to be searched for in the - document title or subject. - - author or - from for searching the documents originators. - - recipient or - to for searching the documents recipients. - - keyword for searching the - document-specified keywords (few documents actually have any). - - filename for the document's - file name. - ext specifies the file - name extension (Ex: ext:html) - - - - The field syntax also supports a few field-like, but - special, criteria: - - dir for filtering the - results on 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. - - - date for searching or filtering - on dates. The syntax for the argument is based on the ISO8601 - standard for dates and time intervals. Only dates are supported, no - times. The general syntax is 2 elements separated by a - / character. Each element can be a date or a - period of time. Periods are specified as -PnYnMnD. - The n numbers are the respective numbers - of years, months or days, any of which may be missing. Dates are - specified as -YYYY-MM-DD. - The days and months parts may be missing. If the - / is present but an element is missing, the - missing element is interpreted as the lowest or highest date in the - index. Exemples: - - 2001-03-01/2002-05-01 the - basic syntax for an interval of dates. - - 2001-03-01/P1Y2M the - same specified with a period. - - 2001/ from the beginning of - 2001 to the latest date in the index. - - 2001 the whole year of - 2001 - P2D/ means 2 days ago up to - now if there are no documents with dates in the future. - - /2003 all documents from - 2003 or older. - - - Periods can also be specified with small letters (ie: - p2y). - - - mime or - format 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 specification is not supported and - will produce strange results. - - - type or - rclcat for specifying the category (as in - text/media/presentation/etc.). The classification of mime - types in categories is defined in the &RCL; configuration - (mimeconf), and can be modified or - extended. The default category names are those which permit - filtering results in the main GUI screen. Categories are OR'ed - like mime types above. - - - - - The document filters used while indexing have the - possibility to create other fields with arbitrary names, and - aliases may be defined in the configuration, so that the exact - field search possibilities may be different for you if someone - took care of the customisation. - - The query language is currently the only way to use the - &RCL; field search capability. - - Words inside phrases and capitalized words are not - stem-expanded. Wildcards may be used anywhere inside a term. - Specifying a wild-card on the left of a term can produce a very - slow search (or even an incorrect one if the expansion is - truncated because of excessive size). - - You can use the show query link at the - top of the result list to check the exact query which was - finally executed by Xapian. - - Most Xesam phrase modifiers are unsupported, except for - l (small ell) to disable stemming, and - p to turn a phrase into a NEAR (unordered) - search. Exemple: "prejudice pride"p - - - - + Complex/advanced search - The advanced search dialog helps you build more complex - queries. It can be opened through the Tools - menu or through the main toolbar. + The advanced search dialog helps you build more complex queries + without memorizing the search language constructs. It can be opened + through the Tools menu or through the main + toolbar. The dialog has three parts: @@ -1186,9 +1001,9 @@ fvwm Click on the Show query details link at the top of the result page to see the query expansion. - + - + The term explorer tool &RCL; automatically manages the expansion of search terms @@ -1265,57 +1080,9 @@ fvwm between the result list and any entry field (the end of lines will be taken care of). - + - - More about wildcards - - All words entered in &RCL; search fields will be processed - for wildcard expansion before the request is finally - executed. - - The wildcard characters are: - - - * which matches 0 or more - characters. - - ? which matches - a single character. - - [] which allow - defining sets of characters to be matched (ex: - [abc] - matches a single character which may be 'a' or 'b' or 'c', - [0-9] - matches any number. - - - - You should be aware of a few things before using - wildcards. - - - Using a wildcard character at the beginning of - a word can make for a slow search because &RCL; will have to - scan the whole index term list to find the matches. - - Using a * at the end of a - word can produce more matches than you would think, and - strange search results. You can use the term explorer tool to - check what completions exist for a given term. You can also - see exactly what search was performed by clicking on the link - at the top of the result list. In general, for natural - language terms, stem expansion will produce better results - than an ending * (stem expansion is turned - off when any wildcard character appears in the term). - - - - - - + Multiple databases Multiple &RCL; databases or indexes can be created by @@ -1370,9 +1137,9 @@ fvwm multiple indexes will have much better performance and may be worth the trouble. - + - + Document history Documents that you actually view (with the internal preview @@ -1385,9 +1152,9 @@ fvwm Erase document history entry in the File menu. - + - + Sorting search results and collapsing duplicates The documents in a result list are normally sorted in @@ -1421,13 +1188,12 @@ fvwm by an entry in the Query configuration dialog, and is off by default. - + - - + Search tips, shortcuts - + Terms and search expansion Term completion @@ -1489,10 +1255,10 @@ fvwm faster than the generic search especially when using wildcards. - + - + Working with phrases and proximity Phrases and Proximity searches @@ -1518,12 +1284,11 @@ fvwm both appear, but those which contain virtual reality should appear sooner in the list. - + - + Others - Using fields You can use the query language and field specifications @@ -1578,10 +1343,10 @@ fvwm Entering ^Q almost anywhere will close the application. - - + + - + Customizing the search interface You can customize some aspects of the search interface by using @@ -1767,7 +1532,7 @@ fvwm need to implement a way of purging the index from stale data, - + The result list paragraph format The presentation of each result inside the result list can be @@ -1863,15 +1628,15 @@ fvwm one. - - + + - + - + Searching with the KDE KIO slave - + What's this The &RCL; KIO slave allows performing a &RCL; search @@ -1897,14 +1662,16 @@ fvwm recoll KIO slave has been previously installed). - The instructions for building this module are located in - the source tree. See: - kde/kio/recoll/00README.txt - + The instructions for building this module are located in the + source tree. See: + kde/kio/recoll/00README.txt. Some Linux + distributions do package the kio-recoll module, so check before + diving into the build process, maybe it's already out there ready for + one-click installation. + - - + Searchable documents As a sample application, the &RCL; KIO slave could allow @@ -1930,14 +1697,11 @@ fvwm <body ondblclick="recollsearch()"> - + - - - - + Searching on the command line There are several ways to obtain search results as a text @@ -1962,8 +1726,8 @@ fvwm recollq is not built by default. You can use the Makefile in the query directory to build it. This is a very - simple program, and it will often be useful to taylor its output format - to your needs. + simple program, and if you can program a little c++, you may find it + useful to taylor its output format to your needs. recollq has a man page (not installed by default, look in the doc/man directory). The @@ -1994,8 +1758,299 @@ text/html [file:///Users/uncrypted-dockes/projets/nautique/webnautique/art text/html [file:///Users/uncrypted-dockes/projets/pagepers/index.html] [psxtcl/writemime/recoll]... text/html [file:///Users/uncrypted-dockes/projets/bateaux/ilur/factEtCie/recu-chasse-maree.... + - + + The query language + + The query language processor is activated in the GUI + simple search entry when the search mode selector is set to + Query Language. It can also be used with the KIO + slave or the command line search. It broadly has the same + capabilities as the complex search interface in the + GUI. Additionally, the query language is for now the only way to + access the important &RCL; field search capabilities. + + The language is roughly based on the + Xesam user search language specification. + + 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 + check the exact query which was finally executed by Xapian. + + Here follows a sample request that we are going to + explain: + + + author:"john doe" Beatles OR Lennon Live OR Unplugged -potatoes + + + This would search for all documents with + John Doe + appearing as a phrase in the author field (exactly what this is + would depend on the document type, ie: the + From: header, for an email message), + and containing either beatles or + lennon and either + live or + unplugged but not + potatoes (in any part of the document). + + An element is composed of an optional field specification, + and a value, separated by a colon. Exemple: + Beatles, + author:balzac, + dc:title:grandet + + The colon, if present, means "contains". Xesam defines other + relations, which are not supported for now. + + All elements in the search entry are normally combined + with an implicit AND. It is possible to specify that elements be + OR'ed instead, as in Beatles + OR Lennon. The + OR must be entered literally (capitals), and + it has priority over the AND associations: + word1 + word2 OR + word3 + means + word1 AND + (word2 OR + word3) + not + (word1 AND + word2) OR + word3. Do not enter explicit + parenthesis, they are not supported for now. + + An element preceded by a - specifies a + term that should not appear. Pure negative + queries are forbidden. + + As usual, words inside quotes define a phrase + (the order of words is significant), so that + title:"prejudice pride" is not the same as + title:prejudice title:pride, and is + unlikely to find a result. + Most Xesam phrase modifiers are unsupported, except for + l (small ell) to disable stemming, and + p to turn a phrase into a NEAR (unordered proximity) + search. Exemple: "prejudice pride"p + + &RCL; currently manages the following default fields: + + title, + subject or caption are + synonyms which specify data to be searched for in the + document title or subject. + + author or + from for searching the documents originators. + + recipient or + to for searching the documents recipients. + + keyword for searching the + document-specified keywords (few documents actually have any). + + filename for the document's + file name. + ext specifies the file + name extension (Ex: ext:html) + + + + The field syntax also supports a few field-like, but + special, criteria: + + dir for filtering the + results on 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. + + + date for searching or filtering + on dates. The syntax for the argument is based on the ISO8601 + standard for dates and time intervals. Only dates are supported, no + times. The general syntax is 2 elements separated by a + / character. Each element can be a date or a + period of time. Periods are specified as +PnYnMnD. + The n numbers are the respective numbers + of years, months or days, any of which may be missing. Dates are + specified as +YYYY-MM-DD. + The days and months parts may be missing. If the + / is present but an element is missing, the + missing element is interpreted as the lowest or highest date in the + index. Exemples: + + 2001-03-01/2002-05-01 the + basic syntax for an interval of dates. + + 2001-03-01/P1Y2M the + same specified with a period. + + 2001/ from the beginning of + 2001 to the latest date in the index. + + 2001 the whole year of + 2001 + P2D/ means 2 days ago up to + now if there are no documents with dates in the future. + + /2003 all documents from + 2003 or older. + + + Periods can also be specified with small letters (ie: + p2y). + + + mime or + format 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 specification is not supported and + will produce strange results. Note that mime is + the ONLY field with an OR default. You do need to use + OR with ext terms for + example. + + + type or + rclcat for specifying the category (as in + text/media/presentation/etc.). The classification of mime + types in categories is defined in the &RCL; configuration + (mimeconf), and can be modified or + extended. The default category names are those which permit + filtering results in the main GUI screen. Categories are OR'ed + like mime types above. + + + + + Words inside phrases and capitalized words are not + stem-expanded. Wildcards may be used anywhere inside a term. + Specifying a wild-card on the left of a term can produce a very + slow search (or even an incorrect one if the expansion is + truncated because of excessive size). Also see More about wildcards. + + The document filters used while indexing have the + possibility to create other fields with arbitrary names, and + aliases may be defined in the configuration, so that the exact + field search possibilities may be different for you if someone + took care of the customisation. + + + More about wildcards + + All words entered in &RCL; search fields will be processed + for wildcard expansion before the request is finally + executed. + + The wildcard characters are: + + + * which matches 0 or more + characters. + + ? which matches + a single character. + + [] which allow + defining sets of characters to be matched (ex: + [abc] + matches a single character which may be 'a' or 'b' or 'c', + [0-9] + matches any number. + + + + You should be aware of a few things before using + wildcards. + + + Using a wildcard character at the beginning of + a word can make for a slow search because &RCL; will have to + scan the whole index term list to find the matches. + + Using a * at the end of a + word can produce more matches than you would think, and + strange search results. You can use the term explorer tool to + check what completions exist for a given term. You can also + see exactly what search was performed by clicking on the link + at the top of the result list. In general, for natural + language terms, stem expansion will produce better results + than an ending * (stem expansion is turned + off when any wildcard character appears in the term). + + + + + + + + + Desktop integration + + Being independant of the desktop type has its drawbacks: &RCL; + desktop integration is minimal. Here follow a few things that may + help. + + + Hotkeying recoll + + 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 manager + interface library, which will allow you to do just this. The detailed + instructions are on + + this wiki page. + + + + + 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 + add a small &RCL; launcher to the KDE panel. + + The applet is not automatically built with the main &RCL; + programs, nor is it included with the main source distribution + (because the KDE build boilerplate makes it relatively big). You can + download its source from the recoll.org download page. Use the + omnipotent configure;make;make install + incantation to build and 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 &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. + + + + + + Programming interface @@ -2544,7 +2599,7 @@ while query.next >= 0 and query.next < nres: - Installation + Installation and configuration Installing a binary copy @@ -3751,33 +3806,6 @@ application/x-blobapp = exec rclblob - - 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 - add a small &RCL; launcher to the KDE panel. - - The applet is not automatically built with the main &RCL; - programs, nor is it included with the main source distribution - (because the KDE build boilerplate makes it relatively big). You - can download its source from the recoll.org download page. Use - the omnipotent configure;make;make - install incantation to build and 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 &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. - -