doc/searching.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   6  *
   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.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page searching Searching
  18
  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.
  23
  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
  26 this feature.
  27
  28 Doxygen has 7 different ways to add searching to the HTML output, each of which
  29 has its own advantages and disadvantages:
  30
  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.
  36
  37    To enable it set
  38    \ref cfg_searchengine "SEARCHENGINE" to \c YES in the configuration file
  39    and make sure \ref cfg_server_based_search "SERVER_BASED_SEARCH" is set
  40    to \c NO.
  41
  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.
  44
  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).
  48
  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.
  53
  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 configuration
  57    file and set \ref cfg_external_search "EXTERNAL_SEARCH" to \c NO.
  58
  59    Advantages over the client side search engine are that it provides full
  60    text search and it scales well to medium side projects.
  61
  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.
  64
  65    @note In the future this option will probably be replaced by the next
  66    search option.
  67
  68 <h2>3. Server side searching with external indexing</h2>
  69    With release 1.8.3 of doxygen, another server based search option has
  70    been added. With this option doxygen generates the raw data that can be
  71    searched and leaves it up to external tools to do the indexing and
  72    searching, meaning that you could use your own indexer and search engine
  73    of choice. To make life easier doxygen ships with an example indexer
  74    (doxyindexer) and search engine (doxysearch.cgi) based on
  75    the <a href="https://xapian.org/">Xapian</a> open source search engine
  76    library.
  77
  78    To enable this search method set
  79    \ref cfg_searchengine "SEARCHENGINE",
  80    \ref cfg_server_based_search "SERVER_BASED_SEARCH" and
  81    \ref cfg_external_search "EXTERNAL_SEARCH" all to \c YES.
  82
  83    See \subpage extsearch for configuration details.
  84
  85    Advantages over option 2 are that this method (potentially) scales to
  86    very large projects. It is also possible to combine multiple doxygen
  87    projects and external data into one search index.
  88    The way the interaction with the search engine is done, makes it
  89    possible to search from local HTML pages. Also the search results have
  90    better ranking and show context information (if available).
  91
  92    Disadvantages are that is requires a web server that can execute a CGI
  93    binary, and an additional indexing step after running doxygen.
  94
  95 <h2>4. Windows Compiled HTML Help</h2>
  96    If you are running doxygen on Windows, then you can make a
  97    compiled HTML Help file (.chm) out of the HTML files produced by doxygen.
  98    This is a single file containing all HTML files and it also includes a
  99    search index. There are viewers for this format on many platforms,
 100    and Windows even supports it natively.
 101
 102    To enable this set \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP" to \c YES
 103    in the configuration file. To let doxygen compile the HTML Help file for you,
 104    you also need to specify the path to the HTML compiler (hhc.exe) using the
 105    \ref cfg_hhc_location "HHC_LOCATION" configuration option and the name of the
 106    resulting CHM file using \ref cfg_chm_file "CHM_FILE".
 107
 108    An advantage of this method is that the result is a single file that can
 109    easily be distributed. It also provides full text search.
 110
 111    Disadvantages are that compiling the CHM file only works on Windows
 112    and requires Microsoft's HTML compiler, which is not very actively supported
 113    by Microsoft. Although the tool works fine for most people, it can
 114    sometimes crash for no apparent reason (how typical).
 115
 116 <h2>5. Mac OS X Doc Sets</h2>
 117    If you are running doxygen on Mac OS X 10.5 or higher,
 118    then you can make a "doc set" out of the HTML files produced by doxygen.
 119    A doc set consists of a single directory with a special structure
 120    containing the HTML files along with a precompiled search index.
 121    A doc set can be embedded in Xcode (the integrated development environment
 122    provided by Apple).
 123
 124    To enable the creation of doc sets set \ref cfg_generate_docset "GENERATE_DOCSET"
 125    to \c YES in the configuration file. There are a couple of other doc set related
 126    options you may want to set. After doxygen has finished you will find
 127    a Makefile in the HTML output directory. Running "make install" on this
 128    Makefile will compile and install the doc set.
 129    See <a href="https://developer.apple.com/library/archive/featuredarticles/DoxygenXcode/_index.html">this
 130    article</a> for more info.
 131
 132    Advantage of this method is that it nicely integrates with the Xcode
 133    development environment, allowing for instance to click on an identifier
 134    in the editor and jump to the corresponding section in the doxygen
 135    documentation.
 136
 137    Disadvantage is that it only works in combination with Xcode on MacOSX.
 138
 139 <h2>6. Qt Compressed Help</h2>
 140    If you develop for or want to install the Qt application framework,
 141    you will get an application
 142    called <a href="http://doc.qt.io/archives/qt-4.8/assistant-manual.html">Qt assistant</a>.
 143    This is a help viewer for Qt Compressed Help files (<code>.qch</code>).
 144
 145    To enable this feature set \ref cfg_generate_qhp "GENERATE_QHP" to \c YES.
 146    You also need to fill in the other Qt help related options, such as
 147    \ref cfg_qhp_namespace "QHP_NAMESPACE",
 148    \ref cfg_qhg_location "QHG_LOCATION",
 149    \ref cfg_qhp_virtual_folder "QHP_VIRTUAL_FOLDER".
 150    See <a href="http://doc.qt.io/archives/qq/qq28-qthelp.html#htmlfilesandhelpprojects">this article</a>
 151    for more info.
 152
 153    Feature wise the Qt compressed help feature is comparable with the CHM
 154    output, with the additional advantage that compiling the QCH file is
 155    not limited to Windows.
 156
 157    Disadvantage is that it requires setting up a Qt 4.5 (or better) for
 158    each user, or distributing the Qt help assistant along with
 159    the documentation, which is complicated by the fact that it is not
 160    available as a separate package at this moment.
 161
 162 <h2>7. Eclipse Help Plugin</h2>
 163    If you use eclipse, you can embed the documentation generated by
 164    doxygen as a help plugin. It will then appear as a topic in the help
 165    browser that can be started from "Help contents" in the Help menu.
 166    Eclipse will generate a search index for the documentation when you
 167    first search for a keyword.
 168
 169    To enable the help plugin set
 170    \ref cfg_generate_eclipsehelp "GENERATE_ECLIPSEHELP" to \c YES,
 171    and define a unique identifier for your project via
 172    \ref cfg_eclipse_doc_id "ECLIPSE_DOC_ID", i.e.:
 173 \verbatim
 174    GENERATE_ECLIPSEHELP = YES
 175    ECLIPSE_DOC_ID       = com.yourcompany.yourproject
 176 \endverbatim
 177    then create the \c com.yourcompany.yourproject directory (so with
 178    the same name as the value of \c ECLIPSE_DOC_ID) in the
 179    \c plugin directory of eclipse and after doxygen completes copy
 180    to contents of the help output directory to
 181    the \c com.yourcompany.yourproject directory.
 182    Then restart eclipse to make let it find the new plugin.
 183
 184    The eclipse help plugin provides similar functionality as the
 185    Qt compressed help or CHM output, but it does require that Eclipse is
 186    installed and running.
 187
 188 \htmlonly
 189 Go to the <a href="customize.html">next</a> section or return to the
 190  <a href="index.html">index</a>.
 191 \endhtmlonly
 192
 193 */