diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/doxysearch_usage.doc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Orb/Doxygen/doc/doxysearch_usage.doc Thu Jan 21 17:29:01 2010 +0000 @@ -0,0 +1,180 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2003 by Dimitri van Heesch. + * + * Permission to use, copy, modify, and distribute this software and its + * documentation under the terms of the GNU General Public License is hereby + * granted. No representations are made about the suitability of this software + * for any purpose. It is provided "as is" without express or implied warranty. + * See the GNU General Public License for more details. + * + * Documents produced by Doxygen are derivative works derived from the + * input used in their production; they are not affected by this license. + * + */ +/*! \page doxysearch_usage 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 \c g++ for example, you can build the search engine manually, +by typing: +\verbatim + g++ doxysearch.cpp -o doxysearch +\endverbatim + + +

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 \ref config_search of + the configuration file). + Make sure the \c SEARCHENGINE tag is set to \c YES + and that all paths are correct. + +
  3. Use doxygen to generate the + documentation. Apart from the documentation, Doxygen will create the + following files: + + + \par 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 + + \par 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 of 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: +\verbatim +file:///usr/local/qt/html +http://blizzard/cgi-bin/search.cgi +\endverbatim + +
  6. Add a link to the search engine in the Qt documentation. + On my system, I have put a line +\verbatim +
  7. Search the documentation +\endverbatim + in the additional information section of the index.html file. +
  8. 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. +
+ +*/