Doxysearch usage

Doxysearch is a small, fast and highly portable search engine that allows you to search for strings or words in the documentation generated by doxygen or in the Qt documentation (see below). Doxysearch must be run as a CGI binary. This implies the following:

Ask your system administrator or provider if you are unsure if this is possible.

In order to be able to search fast and efficient, doxysearch does not search the generated documentation directly. Instead, it uses an index file, that should be generated with doxytag. The index file is extracted from the generated HTML files and contains all words and substrings of words present in the HTML files, in a compact form, together with their frequencies and links. Although I tried to store all information as compactly as possible, the size of the index is still quite large. Usually it is about the same size as the original HTML files.

I have tried to make the search engine highly portable, because it must run on the target system. As a result doxysearch does not require the Qt library. All that is required to build doxysearch is a C++ compiler. If you are using g++ for example, you can build the search engine manually, by typing:

  g++ doxysearch.cpp -o doxysearch

Generating the search engine

To include a search engine in the documentation generated by doxygen follow these steps:

  1. Generate a configuration file with doxygen using the -g option, if you haven't done this already.

  2. Edit the search engine section (see section Search engine options of the configuration file). Make sure the SEARCHENGINE tag is set to YES and that all paths are correct.

  3. Use doxygen to generate the documentation. Apart from the documentation, Doxygen will create the following files:
    Note:
    On the Windows platform Unix shell scripts cannot be used. In fact the HTTP daemon that I tried (apache for Windows) only recognized .cgi files that were renamed executables (so DOS batch files do not seem to work either). Therefore, on Windows a small C program will be generated by doxygen. You should compile and link the program with your favourite compiler and change the extension of the executable from .exe to .cgi.
  4. Copy (or move) the CGI script to the directory where the CGI binaries are located. This is usually a special directory on your system or in your home directory. Consult the manual of your HTTP daemon or your system administrator to find out where this directory resides on your system.

  5. Go to the directory where the generated HTML files are located and run doxytag as follows:
    doxytag -s search.idx
    This will create a search index with the name search.idx. Currently the index file must be called like this.

  6. If you change the location of the search engine or the documentation and you do not want to regenerate the HTML output, you can simply edit the generated search.cfg file and run the generated installdox script to correct the links in the documentation.

Creating a search engine to search in the Qt documentation

Using doxytag and doxysearch it is possible to create a search engine for the Qt documentation, without needing the sources! This can be done by carefully following these steps:

  1. Go to the html directory of the Qt-distribution:
    cd $QTDIR/html
  2. Generate the search index by typing:
    doxytag -s search.idx
    in the directory where the HTML files are located. This will parse all files and build a search index. Apart from the file search.idx two other files will be generated: search.gif and search.cgi
    Note:
    Doxytag requires quite a large amount of memory to generate the search index (about 30 MB on my Linux box)! The resulting index file requires about 3 MB space on your disk.
  3. Edit the shell script search.cgi with a text editor.

    Fill in the absolute path to the doxysearch binary after the DOXYSEARCH= tag. On my system this becomes:

    DOXYSEARCH=/usr/local/bin/doxysearch

    Fill in the absolute path to the qt documentation after the DOXYPATH= tag. On my system this becomes:

    DOXYPATH=/usr/local/qt/html
  4. CGI binaries are usually located in a special directory. Consult the manual of your HTTP daemon or your system administrator to find out, where this directory resides on your system. Copy (or move) the search.cgi script to this directory. If needed you may change the name of the script. On my system, this becomes:
    cp search.cgi /usr/local/lib/httpd/cgi-bin/

  5. Create a text-file with the name search.cfg. On the first line, you must put the absolute URL to the Qt documentation. Since, I only use the search engine on my own standalone system, I use the file: protocol. On the second line, you must put the absolute URL to the cgi script. On my system the resulting file looks like this:
    file:///usr/local/qt/html
    http://blizzard/cgi-bin/search.cgi
    

  6. Add a link to the search engine in the Qt documentation. On my system, I have put a line
    <li><a href="http://blizzard/cgi-bin/search.cgi">Search the documentation<a>
    
    in the additional information section of the index.html file.
  7. Start your favourite web browser and click on the link. If everything is OK, you should get a page where you can enter search terms.

Generated on Wed Mar 5 09:19:29 2003 for Doxygen manual by doxygen1.2.18