summaryrefslogtreecommitdiffstats
path: root/doc/doxysearch_usage.doc
diff options
context:
space:
mode:
authormueller <mueller@afe2bf4a-e733-0410-8a33-86f594647bc7>1999-12-15 19:25:10 (GMT)
committermueller <mueller@afe2bf4a-e733-0410-8a33-86f594647bc7>1999-12-15 19:25:10 (GMT)
commit719f0a35063be88eddcc4ed8fe7a940de47ef20c (patch)
treecc1cd70cf5761ddf72ff114c0b65576c3f4c1d2a /doc/doxysearch_usage.doc
parentbd30c025c4651ddda467f1af09d4c7ccab397bde (diff)
downloadDoxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.zip
Doxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.tar.gz
Doxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.tar.bz2
initial version
Diffstat (limited to 'doc/doxysearch_usage.doc')
-rw-r--r--doc/doxysearch_usage.doc169
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>
+
+*/