POV-Ray documentation search tool - Documentation

For using these scripts the following prerequisites are required:

• a Unix/Linux system with the html version of the POV-Ray 3.6 documentation.
• a bash-compatible shell.

The following things are optional:

• the SWISH++ indexing and search program.
• the KDE desktop and the kdialog program (included in all recent versions of KDE).

This script is licensed under the BSD license.

Installation

The povdocserach script installs itself when being called the first time. It detects available programs and adjusts its operation accordingly. Copy the script to a directory in your PATH and start it. If you are using KDE this will install an entry in the KDE panel in the POV-Ray submenu if this has been generated by the POV-Ray install and installs an external tool in Kate to search for words from the current file from the editor.

Installation will generate a copy of the POV-Ray documentation in the system /tmp directory.

Searching

There are two possibilities to call the search script. The first is to pass the search expression as a parameter. If no parameter is given the script uses kdialog to show a dialog window to enter the search string.

If SWISH++ was found to be available during installation it will be used for search. The rules for the search expression are described in the SWISH++ documentation. When using complicated rules the script might have trouble creating the search result links and highlighting the found places but the search itself will work with any SWISH++ compatible search expression.

Without SWISH++ grep(1) is used for searching. Search is slower, you don't have as much possibilities to specify search rules and don't get a meaningful ranking of search results in this case.

After the search the results are displayed in a browser (depending on what is available on the system). The results are displayed in a table with the following columns:

1. Rank: the Rank returned by SWISH++.
2. '*': a mark for all results where an anchor could be found for the matching section. Otherwise only the link to the matching file will be given.
3. Section: a link to the section the search expression was found in. The found words are highlighted in this version.
4. Original: a link to original file.

The KDE integration

The installation mode of the povdocserach script generates an entry in the KDE panel that calls the script without parameters (so kdialog asks for the search string). The entry in the Kate extra tools menu searches for the the text currently selected in the editor. You can assign a shortcut for it in the Kate configuration.