summaryrefslogtreecommitdiffstats
path: root/doc/searching.doc
diff options
context:
space:
mode:
authorDimitri van Heesch <dimitri@stack.nl>2009-12-22 16:03:24 (GMT)
committerDimitri van Heesch <dimitri@stack.nl>2009-12-22 16:03:24 (GMT)
commite32567534d95ff3960fa4dcad7733c18e1b39bc5 (patch)
treeed7891ebf8c1dbed877ba72eecb07d5da29b4978 /doc/searching.doc
parent6f2abee157d4310a8272ca0f748ce6b812ae7260 (diff)
downloadDoxygen-e32567534d95ff3960fa4dcad7733c18e1b39bc5.zip
Doxygen-e32567534d95ff3960fa4dcad7733c18e1b39bc5.tar.gz
Doxygen-e32567534d95ff3960fa4dcad7733c18e1b39bc5.tar.bz2
Release-1.6.1-20091222
Diffstat (limited to 'doc/searching.doc')
-rw-r--r--doc/searching.doc131
1 files changed, 131 insertions, 0 deletions
diff --git a/doc/searching.doc b/doc/searching.doc
new file mode 100644
index 0000000..62f8971
--- /dev/null
+++ b/doc/searching.doc
@@ -0,0 +1,131 @@
+/******************************************************************************
+ *
+ *
+ *
+ * Copyright (C) 1997-2009 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 searching Searching
+
+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.
+
+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.
+
+Doxygen has 5 different ways to add searching to the HTML output, each of which
+has its own advantages and disadvantages:
+
+<h2>1. Client side searching</h2>
+ 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.
+
+ To enable it set
+ \ref cfg_searchengine "SEARCHENGINE" to \c YES in the config file
+ and make sure \ref cfg_server_based_search "SERVER_BASED_SEARCH" is set
+ to \c NO.
+
+ An additional advantage of this method is that it provides live
+ searching, i.e. the search results are presented and adapted as you type.
+
+ 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).
+
+<h2>2. Server side searching</h2>
+ 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.
+
+ To enable this set both
+ \ref cfg_searchengine "SEARCHENGINE" and
+ \ref cfg_server_based_search "SERVER_BASED_SEARCH" to \c YES in the config
+ file.
+
+ Advantages over the client side search engine are that it provides full
+ text search and it scales well to large projects.
+
+ Disadvantages are that it does not work locally (i.e. using a file:// URL)
+ and that it does not provide live search capabilities.
+
+<h2>3. Windows Compiled HTML Help</h2>
+ 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.
+
+ To enable this set \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP" to \c YES
+ 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
+ \ref cfg_hhc_location "HHC_LOCATION" config option and the name of the
+ resulting CHM file using \ref cfg_chm_file "CHM_FILE".
+
+ An advantage of this method is that the result is a single file that can
+ easily be distributed. It also provides full text search.
+
+ 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).
+
+<h2>4. Mac OS X Doc Sets</h2>
+ 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).
+
+ To enable the creation of doc sets set \ref cfg_generate_docset "GENERATE_DOCSET"
+ to \c YES 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="http://developer.apple.com/tools/creatingdocsetswithdoxygen.html">this
+ article</a> for more info.
+
+ 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.
+
+ Disadvantage is that it only works in combination with Xcode on MacOSX.
+
+<h2>5. Qt Compressed Help</h2>
+ If you develop for or want to install the Qt application framework,
+ you will get an application
+ called <a href="http://doc.trolltech.com/4.6/assistant-manual.html">Qt assistant</a>.
+ This is a help viewer for Qt Compressed Help files (.qch).
+
+ To enable this feature set \ref cfg_generate_qhp "GENERATE_QHP" to \c YES.
+ You also need to fill in the other Qt help related options, such as
+ \ref cfg_qhp_namespace "QHP_NAMESPACE",
+ \ref cfg_qhg_location "QHG_LOCATION",
+ \ref cfg_qhp_virtual_folder "QHP_VIRTUAL_FOLDER".
+ See <a href="http://doc.trolltech.com/qq/qq28-qthelp.html#htmlfilesandhelpprojects">this article</a>
+ for more info.
+
+ 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.
+
+ 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.
+*/