diff --git a/src/doc/user/usermanual.sgml b/src/doc/user/usermanual.sgml index 00194db6..4bc0b579 100644 --- a/src/doc/user/usermanual.sgml +++ b/src/doc/user/usermanual.sgml @@ -24,7 +24,7 @@ Dockes - $Id: usermanual.sgml,v 1.36 2007-01-25 15:47:45 dockes Exp $ + $Id: usermanual.sgml,v 1.37 2007-02-02 10:05:07 dockes Exp $ This document introduces full text search notions @@ -553,6 +553,15 @@ fvwm Double-clicking on a word in the result list or a preview window will insert it into the simple search entry field. + Note that, apart from wildcard characters (single + ? characters are ok), you can cut and paste + any text into an All terms or + Any term search field, punctuation, + newlines and all. &RCL; will process it and produce a meaningful + search. This is what most differentiates this mode from the + Query Language mode, where you have to care + about the syntax. + You can use the Tools / Advanced search dialog for more complex searches. @@ -1882,6 +1891,126 @@ fvwm + + Examples of configuration adjustments + + + Adding an external viewer for an non-indexed type + + Imagine that you have some kind of file which does not + have indexable content, but for which you would like to have a + functional Edit link in the result list + (when found by file name). The file names end in + .blob and can be displayed by + application blobviewer. + + You need two entries in the configuration files for this + to work: + + In $RECOLL_CONFDIR/mimemap + (typically ~/.recoll/mimemap), add the + following line: + + application/x-blobapp = .blob + + Note that the mime type is made up here, and you could + call it diesel/oil just the + same. + + In + $RECOLL_CONFDIR/mimeview under the + [view] section: + + application/x-blobapp = blobviewer %f + + + We are supposing that + blobviewer wants a file name + parameter here, you would use %u if + it liked URLs better. + + + + If you just wanted to change the application used by + &RCL; to display a mime type which it already knows, you + would just need to edit mimeview. The + entries you add in your personal file override those in the + central configuration, which you do not need to alter + + + + + Adding indexing support for a new file type + + Let us now imagine that the above + .blob files actually contain + indexable text and that you know how to extract it with a + command line program. Getting &RCL; to index the files is + easy. You need to perform the above alteration, and also to + add data to the mimeconf file + (typically in ~/.recoll/mimeconf): + + + Under the [index] + section, add the following line (more about the + rclblob indexing script later): + + application/x-blobapp = exec rclblob + + + + + Under the [icons] + section, you should choose an icon to be displayed for the + files inside the result lists. Icons are normally 64x64 + pixels PNG files which live in + /usr/[local/]share/recoll/images. + + + + Under the [categories] + section, you should add the mime type where it makes sense + (you can also create a category). Categories may be used + for filtering in advanced search. + + + + + The rclblob filter should + be an executable program or script which exists inside + /usr/[local/]share/recoll/filters. It + will be given a file name as argument and should output the + text contents in html format on the standard output. + + The html could be very minimal like the following + example: + <html><head> +<meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> +</head> +<body>some text content</body></html> + + + You should take care to escape some characters inside + the text by transforming them into appropriate + entities. "&" should be transformed into + "&amp;", "<" + should be transformed into "&lt;". + + The character set needs to be specified in the + header. It does not need to be UTF-8 (&RCL; will take care + of translating it), but it must be accurate for good + results. + + &RCL; will also make use of other header fields if + they are present: title, + description, keywords. + + The easiest way to write a new filter is probably to start + from an existing one. + + + +