|
1 /****************************************************************************** |
|
2 * |
|
3 * |
|
4 * |
|
5 * Copyright (C) 1997-2009 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 searching Searching |
|
18 |
|
19 Doxygen indexes your source code in various ways to make it easier |
|
20 to navigate and find what you are looking for. |
|
21 There are also situations however where you want to |
|
22 search for something by keyword rather than browse for it. |
|
23 |
|
24 HTML browsers by default have no search capabilities that work across multiple |
|
25 pages, so either doxygen or external tools need to help to facilitate |
|
26 this feature. |
|
27 |
|
28 Doxygen has 6 different ways to add searching to the HTML output, each of which |
|
29 has its own advantages and disadvantages: |
|
30 |
|
31 <h2>1. Client side searching</h2> |
|
32 The easiest way to enable searching is to enable the built-in client |
|
33 side search engine. This engine is implemented using Javascript and DHTML |
|
34 only and runs entirely on the clients browser. So no additional tooling is |
|
35 required to make it work. |
|
36 |
|
37 To enable it set |
|
38 \ref cfg_searchengine "SEARCHENGINE" to \c YES in the config file |
|
39 and make sure \ref cfg_server_based_search "SERVER_BASED_SEARCH" is set |
|
40 to \c NO. |
|
41 |
|
42 An additional advantage of this method is that it provides live |
|
43 searching, i.e. the search results are presented and adapted as you type. |
|
44 |
|
45 This method also has its drawbacks: it is limited to searching for symbols |
|
46 only. It does not provide full text search capabilities, and it does not |
|
47 scale well to very large projects (then searching becomes very slow). |
|
48 |
|
49 <h2>2. Server side searching</h2> |
|
50 If you plan to put the HTML documentation on a web server, and that |
|
51 web server has the capability to process PHP code, then you can also use |
|
52 doxygen's built-in server side search engine. |
|
53 |
|
54 To enable this set both |
|
55 \ref cfg_searchengine "SEARCHENGINE" and |
|
56 \ref cfg_server_based_search "SERVER_BASED_SEARCH" to \c YES in the config |
|
57 file. |
|
58 |
|
59 Advantages over the client side search engine are that it provides full |
|
60 text search and it scales well to large projects. |
|
61 |
|
62 Disadvantages are that it does not work locally (i.e. using a file:// URL) |
|
63 and that it does not provide live search capabilities. |
|
64 |
|
65 <h2>3. Windows Compiled HTML Help</h2> |
|
66 If you are running doxygen on Windows, then you can make a |
|
67 compiled HTML Help file (.chm) out of the HTML files produced by doxygen. |
|
68 This is a single file containing all HTML files and it also includes a |
|
69 search index. There are viewers for this format on many platforms, |
|
70 and Windows even supports it natively. |
|
71 |
|
72 To enable this set \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP" to \c YES |
|
73 in the config file. To let doxygen compile the HTML Help file for you, |
|
74 you also need to specify the path to the HTML compiler (hhc.exe) using the |
|
75 \ref cfg_hhc_location "HHC_LOCATION" config option and the name of the |
|
76 resulting CHM file using \ref cfg_chm_file "CHM_FILE". |
|
77 |
|
78 An advantage of this method is that the result is a single file that can |
|
79 easily be distributed. It also provides full text search. |
|
80 |
|
81 Disadvantages are that compiling the CHM file only works on Windows |
|
82 and requires Microsoft's HTML compiler, which is not very actively supported |
|
83 by Microsoft. Although the tool works fine for most people, it can |
|
84 sometimes crash for no apparent reason (how typical). |
|
85 |
|
86 <h2>4. Mac OS X Doc Sets</h2> |
|
87 If you are running doxygen on Mac OS X 10.5 or higher, |
|
88 then you can make a "doc set" out of the HTML files produced by doxygen. |
|
89 A doc set consists of a single directory with a special structure |
|
90 containing the HTML files along with a precompiled search index. |
|
91 A doc set can be embedded in Xcode (the integrated development environment |
|
92 provided by Apple). |
|
93 |
|
94 To enable the creation of doc sets set \ref cfg_generate_docset "GENERATE_DOCSET" |
|
95 to \c YES in the config file. There are a couple of other doc set related |
|
96 options you may want to set. After doxygen has finished you will find |
|
97 a Makefile in the HTML output directory. Running "make install" on this |
|
98 Makefile will compile and install the doc set. |
|
99 See <a href="http://developer.apple.com/tools/creatingdocsetswithdoxygen.html">this |
|
100 article</a> for more info. |
|
101 |
|
102 Advantage of this method is that it nicely integrates with the Xcode |
|
103 development environment, allowing for instance to click on an identifier |
|
104 in the editor and jump to the corresponding section in the doxygen |
|
105 documentation. |
|
106 |
|
107 Disadvantage is that it only works in combination with Xcode on MacOSX. |
|
108 |
|
109 <h2>5. Qt Compressed Help</h2> |
|
110 If you develop for or want to install the Qt application framework, |
|
111 you will get an application |
|
112 called <a href="http://doc.trolltech.com/4.6/assistant-manual.html">Qt assistant</a>. |
|
113 This is a help viewer for Qt Compressed Help files (.qch). |
|
114 |
|
115 To enable this feature set \ref cfg_generate_qhp "GENERATE_QHP" to \c YES. |
|
116 You also need to fill in the other Qt help related options, such as |
|
117 \ref cfg_qhp_namespace "QHP_NAMESPACE", |
|
118 \ref cfg_qhg_location "QHG_LOCATION", |
|
119 \ref cfg_qhp_virtual_folder "QHP_VIRTUAL_FOLDER". |
|
120 See <a href="http://doc.trolltech.com/qq/qq28-qthelp.html#htmlfilesandhelpprojects">this article</a> |
|
121 for more info. |
|
122 |
|
123 Feature wise the Qt compressed help feature is comparable with the CHM |
|
124 output, with the additional advantage that compiling the QCH file is |
|
125 not limited to Windows. |
|
126 |
|
127 Disadvantage is that it requires setting up a Qt 4.5 (or better) for |
|
128 each user, or distributing the Qt help assistant along with |
|
129 the documentation, which is complicated by the fact that it is not |
|
130 available as a separate package at this moment. |
|
131 |
|
132 <h2>6. Eclipse Help Plugin</h2> |
|
133 If you use eclipse, you can embed the documentation generated by |
|
134 doxygen as a help plugin. It will then appear as a topic in the help |
|
135 browser that can be started from "Help contents" in the Help menu. |
|
136 Eclipse will generate a search index for the documentation when you |
|
137 first search for an keyword. |
|
138 |
|
139 To enable the help plugin set |
|
140 \ref cfg_generate_eclipsehelp "GENERATE_ECLIPSE_HELP" to \c YES, |
|
141 and define a unique identifier for your project via |
|
142 \ref cfg_eclipse_doc_id "ECLIPSE_DOC_ID", i.e: |
|
143 \verbatim |
|
144 GENERATE_ECLIPSE_HELP = YES |
|
145 ECLIPSE_DOC_ID = com.yourcompany.yourproject |
|
146 \endverbatim |
|
147 then create the \c com.yourcompany.yourproject directory (so with |
|
148 the same name as the value of \c ECLIPSE_DOC_ID) in the |
|
149 \c plugin directory of eclipse and after doxygen completes copy |
|
150 to contents of the help output directory to |
|
151 the \c com.yourcompany.yourproject directory. |
|
152 Then restart eclipse to make let it find the new plugin. |
|
153 |
|
154 The eclipse help plugin provides similar functionality as the |
|
155 Qt compressed help or CHM output, but it does require that Eclipse is |
|
156 installed and running. |
|
157 |
|
158 */ |