Orb/Doxygen/doc/searching.doc
changeset 0 42188c7ea2d9
equal deleted inserted replaced
-1:000000000000 0:42188c7ea2d9
       
     1 /******************************************************************************
       
     2  *
       
     3  * 
       
     4  *
       
     5  * Copyright (C) 1997-2009 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 6 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 config 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 config
       
    57    file.
       
    58 
       
    59    Advantages over the client side search engine are that it provides full
       
    60    text search and it scales well to large 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 <h2>3. Windows Compiled HTML Help</h2>
       
    66    If you are running doxygen on Windows, then you can make a 
       
    67    compiled HTML Help file (.chm) out of the HTML files produced by doxygen.
       
    68    This is a single file containing all HTML files and it also includes a
       
    69    search index. There are viewers for this format on many platforms,
       
    70    and Windows even supports it natively.
       
    71 
       
    72    To enable this set \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP" to \c YES
       
    73    in the config file. To let doxygen compile the HTML Help file for you,
       
    74    you also need to specify the path to the HTML compiler (hhc.exe) using the
       
    75    \ref cfg_hhc_location "HHC_LOCATION" config option and the name of the
       
    76    resulting CHM file using \ref cfg_chm_file "CHM_FILE".
       
    77    
       
    78    An advantage of this method is that the result is a single file that can
       
    79    easily be distributed. It also provides full text search. 
       
    80    
       
    81    Disadvantages are that compiling the CHM file only works on Windows
       
    82    and requires Microsoft's HTML compiler, which is not very actively supported
       
    83    by Microsoft. Although the tool works fine for most people, it can 
       
    84    sometimes crash for no apparent reason (how typical). 
       
    85 
       
    86 <h2>4. Mac OS X Doc Sets</h2> 
       
    87    If you are running doxygen on Mac OS X 10.5 or higher, 
       
    88    then you can make a "doc set" out of the HTML files produced by doxygen.
       
    89    A doc set consists of a single directory with a special structure 
       
    90    containing the HTML files along with a precompiled search index. 
       
    91    A doc set can be embedded in Xcode (the integrated development environment 
       
    92    provided by Apple).
       
    93 
       
    94    To enable the creation of doc sets set \ref cfg_generate_docset "GENERATE_DOCSET"
       
    95    to \c YES in the config file. There are a couple of other doc set related
       
    96    options you may want to set. After doxygen has finished you will find
       
    97    a Makefile in the HTML output directory. Running "make install" on this
       
    98    Makefile will compile and install the doc set.
       
    99    See <a href="http://developer.apple.com/tools/creatingdocsetswithdoxygen.html">this 
       
   100    article</a> for more info.
       
   101 
       
   102    Advantage of this method is that it nicely integrates with the Xcode
       
   103    development environment, allowing for instance to click on an identifier 
       
   104    in the editor and jump to the corresponding section in the doxygen 
       
   105    documentation.
       
   106 
       
   107    Disadvantage is that it only works in combination with Xcode on MacOSX.
       
   108 
       
   109 <h2>5. Qt Compressed Help</h2> 
       
   110    If you develop for or want to install the Qt application framework,
       
   111    you will get an application 
       
   112    called <a href="http://doc.trolltech.com/4.6/assistant-manual.html">Qt assistant</a>. 
       
   113    This is a help viewer for Qt Compressed Help files (.qch).
       
   114 
       
   115    To enable this feature set \ref cfg_generate_qhp "GENERATE_QHP" to \c YES.
       
   116    You also need to fill in the other Qt help related options, such as
       
   117    \ref cfg_qhp_namespace "QHP_NAMESPACE", 
       
   118    \ref cfg_qhg_location "QHG_LOCATION", 
       
   119    \ref cfg_qhp_virtual_folder "QHP_VIRTUAL_FOLDER".
       
   120    See <a href="http://doc.trolltech.com/qq/qq28-qthelp.html#htmlfilesandhelpprojects">this article</a> 
       
   121    for more info.
       
   122 
       
   123    Feature wise the Qt compressed help feature is comparable with the CHM 
       
   124    output, with the additional advantage that compiling the QCH file is 
       
   125    not limited to Windows.
       
   126 
       
   127    Disadvantage is that it requires setting up a Qt 4.5 (or better) for
       
   128    each user, or distributing the Qt help assistant along with 
       
   129    the documentation, which is complicated by the fact that it is not
       
   130    available as a separate package at this moment.
       
   131 
       
   132 <h2>6. Eclipse Help Plugin</h2>
       
   133    If you use eclipse, you can embed the documentation generated by
       
   134    doxygen as a help plugin. It will then appear as a topic in the help 
       
   135    browser that can be started from "Help contents" in the Help menu.
       
   136    Eclipse will generate a search index for the documentation when you
       
   137    first search for an keyword.
       
   138 
       
   139    To enable the help plugin set 
       
   140    \ref cfg_generate_eclipsehelp "GENERATE_ECLIPSE_HELP" to \c YES,
       
   141    and define a unique identifier for your project via
       
   142    \ref cfg_eclipse_doc_id "ECLIPSE_DOC_ID", i.e:
       
   143 \verbatim
       
   144    GENERATE_ECLIPSE_HELP = YES
       
   145    ECLIPSE_DOC_ID        = com.yourcompany.yourproject
       
   146 \endverbatim
       
   147    then create the \c com.yourcompany.yourproject directory (so with
       
   148    the same name as the value of \c ECLIPSE_DOC_ID) in the 
       
   149    \c plugin directory of eclipse and after doxygen completes copy
       
   150    to contents of the help output directory to 
       
   151    the \c com.yourcompany.yourproject directory.
       
   152    Then restart eclipse to make let it find the new plugin.
       
   153 
       
   154    The eclipse help plugin provides similar functionality as the
       
   155    Qt compressed help or CHM output, but it does require that Eclipse is
       
   156    installed and running.
       
   157 
       
   158 */