\hypertarget{doxysearch_usage}{}\section{Doxysearch usage}\label{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  \href{doxygen_usage.html}{\tt doxygen} or  in the Qt documentation (see \href{#searchqt}{\tt below}).  Doxysearch must be run as a CGI binary. This implies the following: \begin{CompactItemize}
\item 
 There must be a HTTP daemon running on the system where you want to  install the documentation (the {\em target}) \item 
 You must have permission to install and execute a CGI binary on the  target. \end{CompactItemize}
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  {\em index file}, that should be generated with  \href{doxytag_usage.html}{\tt 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 {\tt g++} for example, you can build the search engine manually,  by typing: 

\footnotesize\begin{verbatim}
  g++ doxysearch.cpp -o doxysearch
\end{verbatim}\normalsize 


\label{se}
 \subsubsection*{Generating the search engine}
 

To include a search engine in the documentation generated by doxygen follow these steps: \begin{enumerate}
\item 
Generate a configuration file with  \href{doxygen_usage.html}{\tt doxygen} using the  {\tt -g} option, if you haven't done this already.

\item 
Edit the search engine section (see section \hyperlink{config_search}{Search engine options} of the configuration file). Make sure the {\tt SEARCHENGINE} tag is set to {\tt YES} and that all paths are correct.

\item 
Use \href{doxygen_usage.html}{\tt doxygen} to generate the  documentation. Apart from the documentation, Doxygen will create the  following files: \begin{CompactItemize}
\item 
A small shell script. The name of the script is determined by the {\tt CGI\_\-NAME} tag in the configuration file. The script is a small wrapper that calls {\tt doxysearch} with the correct parameters. Using this script allows multiple  search engines for different projects to be present in one directory. \item 
{\tt search.cfg}: this file is a small configuration file  for the search engine. It contains two lines of text. The first line should be the absolute URL to the documentation. The second line should be the absolute URL to the CGI script. This information is taken from the configuration file. \item 
{\tt search.gif}: this is the image that is used for the search button. \end{CompactItemize}
\begin{Desc}
\item[Note:]\par
 On the Windows platform Unix shell scripts cannot be used.  In fact the HTTP daemon that I tried (apache for Windows) only  recognized {\tt .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  {\tt .exe} to {\tt .cgi}.\end{Desc}
\item 
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.

\item 
Go to the directory where the generated HTML files are located and run  doxytag as follows: \small\begin{alltt}doxytag -s search.idx\end{alltt}\normalsize 
 This will create a search index with the name {\tt search.idx}. Currently the index file {\em must} be called like this.

\item 
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 \href{installdox_usage.html}{\tt installdox} script to correct the links in the documentation.

\end{enumerate}
\label{searchqt}
 \subsubsection*{Creating a search engine to search in the Qt documentation}
 

Using {\tt doxytag} and {\tt 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: \begin{enumerate}
\item 
Go to the html directory of the Qt-distribution: \small\begin{alltt}cd $QTDIR/html\end{alltt}\normalsize 
 \item 
Generate the search index by typing: \small\begin{alltt}doxytag -s search.idx\end{alltt}\normalsize 
 in the directory where the HTML files are located. This will parse all files and build a search index. Apart from the file {\tt search.idx} two other files will be generated: {\tt search.gif} and {\tt search.cgi}\begin{Desc}
\item[Note:]\par
 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.\end{Desc}
\item 
Edit the shell script {\tt search.cgi} with a text editor.

Fill in the absolute path to the {\tt doxysearch} binary after  the {\tt DOXYSEARCH=} tag. On my system this becomes: \small\begin{alltt}DOXYSEARCH=/usr/local/bin/doxysearch\end{alltt}\normalsize 


Fill in the absolute path to the qt documentation after the {\tt DOXYPATH=} tag. On my system this becomes: \small\begin{alltt}DOXYPATH=/usr/local/qt/html\end{alltt}\normalsize 
 \item 
 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 {\tt search.cgi} script to this directory. If needed you may change the name of the script. On my system, this becomes: \small\begin{alltt}cp search.cgi /usr/local/lib/httpd/cgi-bin/\end{alltt}\normalsize 


\item 
Create a text-file with the name {\tt search.cfg}. On the first line, you must put the {\em absolute} URL to the Qt  documentation. Since, I only use the search engine on my own standalone system, I use the {\tt file:} protocol.  On the second line, you must put the {\em absolute} URL to the cgi script. On my system the resulting file looks like this: 

\footnotesize\begin{verbatim}
file:///usr/local/qt/html
http://blizzard/cgi-bin/search.cgi
\end{verbatim}\normalsize 


\item 
Add a link to the search engine in the Qt documentation. On my system, I have put a line  

\footnotesize\begin{verbatim}
<li><a href="http://blizzard/cgi-bin/search.cgi">Search the documentation<a>
\end{verbatim}\normalsize 
 in the additional information section of the {\tt index.html} file. \item 
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. \end{enumerate}
