diff options
Diffstat (limited to 'doc/doxysearch_usage.doc')
| -rw-r--r-- | doc/doxysearch_usage.doc | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/doc/doxysearch_usage.doc b/doc/doxysearch_usage.doc new file mode 100644 index 0000000..a4a3e96 --- /dev/null +++ b/doc/doxysearch_usage.doc @@ -0,0 +1,169 @@ +/****************************************************************************** + * + * $Id$ + * + * Copyright (C) 1997-1999 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. + * + * All output generated with Doxygen is not covered 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 +<a href="doxygen_usage.html">doxygen</a> or +in the Qt documentation (see <a href="#searchqt">below</a>). +Doxysearch must be run as a CGI binary. This implies the following: +<ul> +<li> There must be a HTTP daemon running on the system where you want to + install the documentation (the <em>target</em>) +<li> You must have permission to install and execute a CGI binary on the + target. +</ul> +Ask you 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</em>, that should be generated with +<a href="doxytag_usage.html">doxytag</a>. 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 + +<a name="se"> +<h3>Generating the search engine</h3> +</a> + +To include a search engine in the documentation generated by doxygen +follow these steps: +<ol> +<li>Generate a configuration file with + <a href="doxygen_usage.html">doxygen</a> using the + <code>-g</code> option, if you haven't done this already. + +<li>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. + +<li>Use <a href="doxygen_usage.html">doxygen</a> to generate the + documentation. Apart from the documentation, Doxygen will create the + following files: + <ul> + <li>A small CGI script. the name of the script is determined by the + \c CGI_NAME tag in the configuration file. + The script is a small wrapper that calls \c doxysearch with + the correct parameters. Using this script allows multiple + search engines for different projects to be present in one directory. + <li>\c 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. + <li>\c search.gif: this is the image that is used for the search button. + </ul> + +<li>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. + +<li>Goto the directory where the generated HTML files are located and run + doxytag as follows: + <pre>doxytag -s search.idx</pre> + This will create a search index with the name <code>search.idx</code>. + Currently the index file <em>must</em> be called like this. + +<li>Run <a href="installdox_usage.html">installdox</a> to replace + any dummy links in the documentation with real links. + + <b>Notice:</b> When using a search engine this step is <em>required</em> + even if no tag files are used. If tag files are used you must specify + the correct options. +</ol> + +<a name="searchqt"> +<h3>Creating a search engine to search in the Qt documentation</h3> +</a> + +Using <code>doxytag</code> and <code>doxysearch</code> 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: +<ol> +<li>Goto the html directory of the Qt-distribution: + <pre>cd $QTDIR/html</pre> +<li>Generate the search index by typing: + <pre>doxytag -s search.idx *.html</pre> + This will parse all files and build a search index. + Apart from the file <code>search.idx</code> two other files + will be generated: <code>search.gif</code> and <code>search.cgi</code> + + \par Notice: + 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. + +<li>Edit the shell script <code>search.cgi</code> with a text editor. + + Fill in the absolute path to the <code>doxysearch</code> binary after + the <code>DOXYSEARCH=</code> tag. + On my system this becomes: + <pre>DOXYSEARCH=/usr/local/bin/doxysearch</pre> + + Fill in the absolute path to the qt documentation after the + <code>DOXYPATH=</code> tag. + On my system this becomes: + <pre>DOXYPATH=/usr/local/qt/html</pre> +<li> + 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 <code>search.cgi</code> script to this directory. + If needed you may change the name of the script. + On my system, this becomes: + <pre>cp search.cgi /usr/local/lib/httpd/cgi-bin/</pre> + +<li>Create a text-file with the name <code>search.cfg</code>. + On the first line, you must put the <em>absolute</em> URL to the Qt + documentation. + Since, I only use the search engine on my own standalone system, I use + the <code>file:</code> protocol. + On the second line, you must put the <em>absolute</em> 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 + +<li>Add a link to the search engine in the Qt documentation. + On my system, I have put a line +\verbatim +<li><a href="http://blizzard/cgi-bin/search.cgi">Search the documentation<a> +\endverbatim + in the additional information section of the <code>index.html</code> file. +<li>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. +</ol> + +*/ |