1 /******************************************************************************
5 * Copyright (C) 1997-2012 by Dimitri van Heesch.
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.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
17 /*! \page searching Searching
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.
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
28 Doxygen has 6 different ways to add searching to the HTML output, each of which
29 has its own advantages and disadvantages:
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.
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
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.
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).
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.
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
59 Advantages over the client side search engine are that it provides full
60 text search and it scales well to large projects.
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.
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.
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".
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.
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).
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
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.
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
107 Disadvantage is that it only works in combination with Xcode on MacOSX.
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).
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>
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.
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.
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.
139 To enable the help plugin set
140 \ref cfg_generate_eclipsehelp "GENERATE_ECLIPSEHELP" to \c YES,
141 and define a unique identifier for your project via
142 \ref cfg_eclipse_doc_id "ECLIPSE_DOC_ID", i.e.:
144 GENERATE_ECLIPSEHELP = YES
145 ECLIPSE_DOC_ID = com.yourcompany.yourproject
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.
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.