1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
/******************************************************************************
*
*
*
* Copyright (C) 1997-2002 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
<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 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</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"></a>
<h3>Generating the search engine</h3>
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 shell 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>
\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 <code>.cgi</code> 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
<code>.exe</code> to <code>.cgi</code>.
<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>Go to 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>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
<a href="installdox_usage.html">installdox</a> script to correct
the links in the documentation.
</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>Go to the html directory of the Qt-distribution:
<pre>cd \$QTDIR/html</pre>
<li>Generate the search index by typing:
<pre>doxytag -s search.idx</pre>
in the directory where the HTML files are located.
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 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.
<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>
*/
|
