diff options
Diffstat (limited to 'trunk/doc/searching.doc')
| -rw-r--r-- | trunk/doc/searching.doc | 158 |
1 files changed, 0 insertions, 158 deletions
diff --git a/trunk/doc/searching.doc b/trunk/doc/searching.doc deleted file mode 100644 index b3e4fd9..0000000 --- a/trunk/doc/searching.doc +++ /dev/null @@ -1,158 +0,0 @@ -/****************************************************************************** - * - * - * - * Copyright (C) 1997-2012 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 6 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. - -<h2>6. 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. - Eclipse will generate a search index for the documentation when you - first search for an keyword. - - To enable the help plugin set - \ref cfg_generate_eclipsehelp "GENERATE_ECLIPSEHELP" to \c YES, - and define a unique identifier for your project via - \ref cfg_eclipse_doc_id "ECLIPSE_DOC_ID", i.e.: -\verbatim - GENERATE_ECLIPSEHELP = YES - ECLIPSE_DOC_ID = com.yourcompany.yourproject -\endverbatim - then create the \c com.yourcompany.yourproject directory (so with - the same name as the value of \c ECLIPSE_DOC_ID) in the - \c plugin directory of eclipse and after doxygen completes copy - to contents of the help output directory to - the \c com.yourcompany.yourproject directory. - Then restart eclipse to make let it find the new plugin. - - 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. - -*/ |