|
1 /****************************************************************************** |
|
2 * |
|
3 * |
|
4 * |
|
5 * Copyright (C) 1997-2003 by Dimitri van Heesch. |
|
6 * |
|
7 * Permission to use, copy, modify, and distribute this software and its |
|
8 * documentation under the terms of the GNU General Public License is hereby |
|
9 * granted. No representations are made about the suitability of this software |
|
10 * for any purpose. It is provided "as is" without express or implied warranty. |
|
11 * See the GNU General Public License for more details. |
|
12 * |
|
13 * Documents produced by Doxygen are derivative works derived from the |
|
14 * input used in their production; they are not affected by this license. |
|
15 * |
|
16 */ |
|
17 /*! \page doxysearch_usage Doxysearch usage |
|
18 |
|
19 Doxysearch is a small, fast and highly portable search engine that allows |
|
20 you to search for strings or words in the documentation generated by |
|
21 <a href="doxygen_usage.html">doxygen</a> or |
|
22 in the Qt documentation (see <a href="#searchqt">below</a>). |
|
23 Doxysearch must be run as a CGI binary. This implies the following: |
|
24 <ul> |
|
25 <li> There must be a HTTP daemon running on the system where you want to |
|
26 install the documentation (the <em>target</em>) |
|
27 <li> You must have permission to install and execute a CGI binary on the |
|
28 target. |
|
29 </ul> |
|
30 Ask your system administrator or provider if you are unsure if this is possible. |
|
31 |
|
32 In order to be able to search fast and efficient, doxysearch does not |
|
33 search the generated documentation directly. Instead, it uses an |
|
34 <em>index file</em>, that should be generated with |
|
35 <a href="doxytag_usage.html">doxytag</a>. The index file is extracted from |
|
36 the generated HTML files and contains all words and substrings of words |
|
37 present in the HTML files, in a compact form, together with their |
|
38 frequencies and links. Although I tried to store all information |
|
39 as compactly as possible, the size of the index is still quite large. |
|
40 Usually it is about the same size as the original HTML files. |
|
41 |
|
42 I have tried to make the search engine highly portable, because it |
|
43 must run on the target system. As a result doxysearch does not require the |
|
44 Qt library. All that is required to build doxysearch is a C++ compiler. |
|
45 If you are using \c g++ for example, you can build the search engine manually, |
|
46 by typing: |
|
47 \verbatim |
|
48 g++ doxysearch.cpp -o doxysearch |
|
49 \endverbatim |
|
50 |
|
51 <a name="se"></a> |
|
52 <h3>Generating the search engine</h3> |
|
53 |
|
54 To include a search engine in the documentation generated by doxygen |
|
55 follow these steps: |
|
56 <ol> |
|
57 <li>Generate a configuration file with |
|
58 <a href="doxygen_usage.html">doxygen</a> using the |
|
59 <code>-g</code> option, if you haven't done this already. |
|
60 |
|
61 <li>Edit the search engine section (see section \ref config_search of |
|
62 the configuration file). |
|
63 Make sure the \c SEARCHENGINE tag is set to \c YES |
|
64 and that all paths are correct. |
|
65 |
|
66 <li>Use <a href="doxygen_usage.html">doxygen</a> to generate the |
|
67 documentation. Apart from the documentation, Doxygen will create the |
|
68 following files: |
|
69 <ul> |
|
70 <li>A small shell script. The name of the script is determined by the |
|
71 \c CGI_NAME tag in the configuration file. |
|
72 The script is a small wrapper that calls \c doxysearch with |
|
73 the correct parameters. Using this script allows multiple |
|
74 search engines for different projects to be present in one directory. |
|
75 <li>\c search.cfg: this file is a small configuration file |
|
76 for the search engine. It contains two lines of text. The first line |
|
77 should be the absolute URL to the documentation. The second line should |
|
78 be the absolute URL to the CGI script. This information is taken from |
|
79 the configuration file. |
|
80 <li>\c search.gif: this is the image that is used for the search button. |
|
81 </ul> |
|
82 |
|
83 \par Note: |
|
84 On the Windows platform Unix shell scripts cannot be used. |
|
85 In fact the HTTP daemon that I tried (apache for Windows) only |
|
86 recognized <code>.cgi</code> files that were renamed |
|
87 executables (so DOS batch files do not seem to work either). Therefore, |
|
88 on Windows a small C program will be generated by doxygen. |
|
89 You should compile and link the program with your favourite |
|
90 compiler and change the extension of the executable from |
|
91 <code>.exe</code> to <code>.cgi</code>. |
|
92 |
|
93 <li>Copy (or move) the CGI script to the directory where the CGI binaries |
|
94 are located. |
|
95 This is usually a special directory on your system or in your |
|
96 home directory. |
|
97 Consult the manual of your HTTP daemon or your system administrator to |
|
98 find out where this directory resides on your system. |
|
99 |
|
100 <li>Go to the directory where the generated HTML files are located and run |
|
101 doxytag as follows: |
|
102 <pre>doxytag -s search.idx</pre> |
|
103 This will create a search index with the name <code>search.idx</code>. |
|
104 Currently the index file <em>must</em> be called like this. |
|
105 |
|
106 <li>If you change the location of the search engine or the documentation |
|
107 and you do not want to regenerate the HTML output, you can simply edit |
|
108 the generated search.cfg file and run the generated |
|
109 <a href="installdox_usage.html">installdox</a> script to correct |
|
110 the links in the documentation. |
|
111 |
|
112 </ol> |
|
113 |
|
114 <a name="searchqt"> |
|
115 <h3>Creating a search engine to search in the Qt documentation</h3> |
|
116 </a> |
|
117 |
|
118 Using <code>doxytag</code> and <code>doxysearch</code> it is possible to create a search engine for |
|
119 the Qt documentation, without needing the sources! |
|
120 This can be done by carefully following these steps: |
|
121 <ol> |
|
122 <li>Go to the html directory of the Qt-distribution: |
|
123 <pre>cd \$QTDIR/html</pre> |
|
124 <li>Generate the search index by typing: |
|
125 <pre>doxytag -s search.idx</pre> |
|
126 in the directory where the HTML files are located. |
|
127 This will parse all files and build a search index. |
|
128 Apart from the file <code>search.idx</code> two other files |
|
129 will be generated: <code>search.gif</code> and <code>search.cgi</code> |
|
130 |
|
131 \par Note: |
|
132 Doxytag requires quite a large amount of memory to |
|
133 generate the search index (about 30 MB on my Linux box)! |
|
134 The resulting index file requires about 3 MB of space on your disk. |
|
135 |
|
136 <li>Edit the shell script <code>search.cgi</code> with a text editor. |
|
137 |
|
138 Fill in the absolute path to the <code>doxysearch</code> binary after |
|
139 the <code>DOXYSEARCH=</code> tag. |
|
140 On my system this becomes: |
|
141 <pre>DOXYSEARCH=/usr/local/bin/doxysearch</pre> |
|
142 |
|
143 Fill in the absolute path to the qt documentation after the |
|
144 <code>DOXYPATH=</code> tag. |
|
145 On my system this becomes: |
|
146 <pre>DOXYPATH=/usr/local/qt/html</pre> |
|
147 <li> |
|
148 CGI binaries are usually located in a special directory. |
|
149 Consult the manual of your HTTP daemon or your system administrator to |
|
150 find out, where this directory resides on your system. |
|
151 Copy (or move) the <code>search.cgi</code> script to this directory. |
|
152 If needed you may change the name of the script. |
|
153 On my system, this becomes: |
|
154 <pre>cp search.cgi /usr/local/lib/httpd/cgi-bin/</pre> |
|
155 |
|
156 <li>Create a text-file with the name <code>search.cfg</code>. |
|
157 On the first line, you must put the <em>absolute</em> URL to the Qt |
|
158 documentation. |
|
159 Since, I only use the search engine on my own standalone system, I use |
|
160 the <code>file:</code> protocol. |
|
161 On the second line, you must put the <em>absolute</em> URL to the |
|
162 cgi script. |
|
163 On my system the resulting file looks like this: |
|
164 \verbatim |
|
165 file:///usr/local/qt/html |
|
166 http://blizzard/cgi-bin/search.cgi |
|
167 \endverbatim |
|
168 |
|
169 <li>Add a link to the search engine in the Qt documentation. |
|
170 On my system, I have put a line |
|
171 \verbatim |
|
172 <li><a href="http://blizzard/cgi-bin/search.cgi">Search the documentation<a> |
|
173 \endverbatim |
|
174 in the additional information section of the <code>index.html</code> file. |
|
175 <li>Start your favourite web browser and click on the link. |
|
176 If everything is OK, you should get a page where you can enter |
|
177 search terms. |
|
178 </ol> |
|
179 |
|
180 */ |