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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Searching</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('searching.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Searching </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Doxygen indexes your source code in various ways to make it easier to navigate and find what you are looking for. There are also situations however where you want to search for something by keyword rather than browse for it.</p>
<p>HTML browsers by default have no search capabilities that work across multiple pages, so either doxygen or external tools need to help to facilitate this feature.</p>
<p>Doxygen has 7 different ways to add searching to the HTML output, each of which has its own advantages and disadvantages:</p>
<h2>1. Client side searching</h2>
<p>The easiest way to enable searching is to enable the built-in client side search engine. This engine is implemented using Javascript and DHTML only and runs entirely on the clients browser. So no additional tooling is required to make it work.</p>
<p>To enable it set <a class="el" href="config.html#cfg_searchengine">SEARCHENGINE</a> to <code>YES</code> in the config file and make sure <a class="el" href="config.html#cfg_server_based_search">SERVER_BASED_SEARCH</a> is set to <code>NO</code>.</p>
<p>An additional advantage of this method is that it provides live searching, i.e. the search results are presented and adapted as you type.</p>
<p>This method also has its drawbacks: it is limited to searching for symbols only. It does not provide full text search capabilities, and it does not scale well to very large projects (then searching becomes very slow).</p>
<h2>2. Server side searching</h2>
<p>If you plan to put the HTML documentation on a web server, and that web server has the capability to process PHP code, then you can also use doxygen's built-in server side search engine.</p>
<p>To enable this set both <a class="el" href="config.html#cfg_searchengine">SEARCHENGINE</a> and <a class="el" href="config.html#cfg_server_based_search">SERVER_BASED_SEARCH</a> to <code>YES</code> in the config file and set <a class="el" href="config.html#cfg_external_search">EXTERNAL_SEARCH</a> to <code>NO</code>.</p>
<p>Advantages over the client side search engine are that it provides full text search and it scales well to medium side projects.</p>
<p>Disadvantages are that it does not work locally (i.e. using a "file://" URL) and that it does not provide live search capabilities.</p>
<dl class="section note"><dt>Note</dt><dd>In the future this option will probably be replaced by the next search option.</dd></dl>
<h2>3. Server side searching with external indexing</h2>
<p>With release 1.8.3 of doxygen, another server based search option has been added. With this option doxygen generates the raw data that can be searched and leaves it up to external tools to do the indexing and searching, meaning that you could use your own indexer and search engine of choice. To make life easier doxygen ships with an example indexer (doxyindexer) and search engine (doxysearch.cgi) based on the <a href="http://xapian.org/">Xapian</a> open source search engine library.</p>
<p>To enable this search method set <a class="el" href="config.html#cfg_searchengine">SEARCHENGINE</a>, <a class="el" href="config.html#cfg_server_based_search">SERVER_BASED_SEARCH</a> and <a class="el" href="config.html#cfg_external_search">EXTERNAL_SEARCH</a> all to <code>YES</code>.</p>
<p>See <a class="el" href="extsearch.html">External Indexing and Searching</a> for configuration details.</p>
<p>Advantages over option 2 are that this method (potentially) scales to very large projects. It is also possible to combine multiple doxygen projects and external data into one search index. The way the interaction with the search engine is done, makes it possible to search from local HTML pages. Also the search results have better ranking and show context information (if available).</p>
<p>Disadvantages are that is requires a web server that can execute a CGI binary, and an additional indexing step after running doxygen.</p>
<h2>4. Windows Compiled HTML Help</h2>
<p>If you are running doxygen on Windows, then you can make a compiled HTML Help file (.chm) out of the HTML files produced by doxygen. This is a single file containing all HTML files and it also includes a search index. There are viewers for this format on many platforms, and Windows even supports it natively.</p>
<p>To enable this set <a class="el" href="config.html#cfg_generate_htmlhelp">GENERATE_HTMLHELP</a> to <code>YES</code> in the config file. To let doxygen compile the HTML Help file for you, you also need to specify the path to the HTML compiler (hhc.exe) using the <a class="el" href="config.html#cfg_hhc_location">HHC_LOCATION</a> config option and the name of the resulting CHM file using <a class="el" href="config.html#cfg_chm_file">CHM_FILE</a>.</p>
<p>An advantage of this method is that the result is a single file that can easily be distributed. It also provides full text search.</p>
<p>Disadvantages are that compiling the CHM file only works on Windows and requires Microsoft's HTML compiler, which is not very actively supported by Microsoft. Although the tool works fine for most people, it can sometimes crash for no apparent reason (how typical).</p>
<h2>5. Mac OS X Doc Sets</h2>
<p>If you are running doxygen on Mac OS X 10.5 or higher, then you can make a "doc set" out of the HTML files produced by doxygen. A doc set consists of a single directory with a special structure containing the HTML files along with a precompiled search index. A doc set can be embedded in Xcode (the integrated development environment provided by Apple).</p>
<p>To enable the creation of doc sets set <a class="el" href="config.html#cfg_generate_docset">GENERATE_DOCSET</a> to <code>YES</code> in the config file. There are a couple of other doc set related options you may want to set. After doxygen has finished you will find a Makefile in the HTML output directory. Running "make install" on this Makefile will compile and install the doc set. See <a href="https://developer.apple.com/library/mac/#featuredarticles/DoxygenXcode/_index.html">this article</a> for more info.</p>
<p>Advantage of this method is that it nicely integrates with the Xcode development environment, allowing for instance to click on an identifier in the editor and jump to the corresponding section in the doxygen documentation.</p>
<p>Disadvantage is that it only works in combination with Xcode on MacOSX.</p>
<h2>6. Qt Compressed Help</h2>
<p>If you develop for or want to install the Qt application framework, you will get an application called <a href="http://qt-project.org/doc/qt-4.8/assistant-manual.html">Qt assistant</a>. This is a help viewer for Qt Compressed Help files (<code>.qch</code>).</p>
<p>To enable this feature set <a class="el" href="config.html#cfg_generate_qhp">GENERATE_QHP</a> to <code>YES</code>. You also need to fill in the other Qt help related options, such as <a class="el" href="config.html#cfg_qhp_namespace">QHP_NAMESPACE</a>, <a class="el" href="config.html#cfg_qhg_location">QHG_LOCATION</a>, <a class="el" href="config.html#cfg_qhp_virtual_folder">QHP_VIRTUAL_FOLDER</a>. See <a href="http://doc.qt.digia.com/qq/qq28-qthelp.html#htmlfilesandhelpprojects">this article</a> for more info.</p>
<p>Feature wise the Qt compressed help feature is comparable with the CHM output, with the additional advantage that compiling the QCH file is not limited to Windows.</p>
<p>Disadvantage is that it requires setting up a Qt 4.5 (or better) for each user, or distributing the Qt help assistant along with the documentation, which is complicated by the fact that it is not available as a separate package at this moment.</p>
<h2>7. Eclipse Help Plugin</h2>
<p>If you use eclipse, you can embed the documentation generated by doxygen as a help plugin. It will then appear as a topic in the help browser that can be started from "Help contents" in the Help menu. Eclipse will generate a search index for the documentation when you first search for a keyword.</p>
<p>To enable the help plugin set <a class="el" href="config.html#cfg_generate_eclipsehelp">GENERATE_ECLIPSEHELP</a> to <code>YES</code>, and define a unique identifier for your project via <a class="el" href="config.html#cfg_eclipse_doc_id">ECLIPSE_DOC_ID</a>, i.e.: </p><pre class="fragment"> GENERATE_ECLIPSEHELP = YES
ECLIPSE_DOC_ID = com.yourcompany.yourproject
</pre><p> then create the <code>com.yourcompany.yourproject</code> directory (so with the same name as the value of <code>ECLIPSE_DOC_ID</code>) in the <code>plugin</code> directory of eclipse and after doxygen completes copy to contents of the help output directory to the <code>com.yourcompany.yourproject</code> directory. Then restart eclipse to make let it find the new plugin.</p>
<p>The eclipse help plugin provides similar functionality as the Qt compressed help or CHM output, but it does require that Eclipse is installed and running.</p>
<p>
Go to the <a href="customize.html">next</a> section or return to the
<a href="index.html">index</a>.
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
</ul>
</div>
</body>
</html>
|
