summaryrefslogtreecommitdiffstats
path: root/doc/searching.doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/searching.doc')
-rw-r--r--doc/searching.doc44
1 files changed, 37 insertions, 7 deletions
diff --git a/doc/searching.doc b/doc/searching.doc
index b3e4fd9..f80e9f6 100644
--- a/doc/searching.doc
+++ b/doc/searching.doc
@@ -25,7 +25,7 @@ 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 6 different ways to add searching to the HTML output, each of which
+Doxygen has 7 different ways to add searching to the HTML output, each of which
has its own advantages and disadvantages:
<h2>1. Client side searching</h2>
@@ -54,15 +54,45 @@ has its own advantages and disadvantages:
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.
+ file and set \ref cfg_external_search "EXTERNAL_SEARCH" to \c NO.
Advantages over the client side search engine are that it provides full
- text search and it scales well to large projects.
+ text search and it scales well to medium side 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>
+ @note In the future this option will probably be replaced by the next
+ search option.
+
+<h2>3. Server side searching with external indexing</h2>
+ 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.
+
+ To enable this search method set
+ \ref cfg_searchengine "SEARCHENGINE",
+ \ref cfg_server_based_search "SERVER_BASED_SEARCH" and
+ \ref cfg_external_search "EXTERNAL_SEARCH" all to \c YES.
+
+ See \ref extsearch for configuration details.
+
+ 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).
+
+ Disadvantages are that is requires a web server that can execute a CGI
+ binary, and an additional indexing step after running doxygen.
+
+<h2>4. 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
@@ -83,7 +113,7 @@ has its own advantages and disadvantages:
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>
+<h2>5. 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
@@ -106,7 +136,7 @@ has its own advantages and disadvantages:
Disadvantage is that it only works in combination with Xcode on MacOSX.
-<h2>5. Qt Compressed Help</h2>
+<h2>6. 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>.
@@ -129,7 +159,7 @@ has its own advantages and disadvantages:
the documentation, which is complicated by the fact that it is not
available as a separate package at this moment.
-<h2>6. Eclipse Help Plugin</h2>
+<h2>7. Eclipse Help Plugin</h2>
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.