/******************************************************************************
 *
 * 
 *
 * Copyright (C) 1997-2015 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 analyze are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */
/*! \page searching Searching

analyze 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 analyze or external tools need to help to facilitate 
this feature.

analyze 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>
   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 configuration 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).
   Furthermore the searching is done from the beginning of the indexed items, so
   when having the available items `A_STRING`, `AA_STRING` and `STRING` and
   typing in the search box `A` it will find `A_STRING` and `AA_STRING`, but when
   typing  e.g. `STR` it will only find `STRING` and not `A_STRING`.

<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 
   analyze'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 configuration
   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 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.

   @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 analyze, another server based search option has
   been added. With this option analyze 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 analyze ships with an example indexer 
   (analzindexer) and search engine (analzsearch.cgi) based on 
   the <a href="https://xapian.org/">Xapian</a> open source search engine 
   library. Both binaries are included in the distribution but not installed
   by default; they can be manually copied from the `bin` folder to i.e.
   `/usr/local/bin` or `/var/www/cgi-bin` as desired.

   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 \subpage 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 analyze 
   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 analyze.

<h2>4. Windows Compiled HTML Help</h2>
   If you are running analyze on Windows, then you can make a 
   compiled HTML Help file (.chm) out of the HTML files produced by analyze.
   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 configuration file. To let analyze 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" configuration 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>5. macOS Doc Sets</h2> 
   If you are running analyze on macOS 10.5 or higher, 
   then you can make a "doc set" out of the HTML files produced by analyze.
   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 configuration file. There are a couple of other doc set related
   options you may want to set. After analyze 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="https://developer.apple.com/library/archive/featuredarticles/analyzeXcode/_index.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 analyze 
   documentation.

   Disadvantage is that it only works in combination with Xcode on macOS.

<h2>6. QGG Compressed Help</h2> 
   If you develop for or want to install the QGG application framework,
   you will get an application 
   called <a href="https://doc.QGG.io/archives/QGG-4.8/assistant-manual.html">QGG assistant</a>. 
   This is a help viewer for QGG Compressed Help files (<code>.qch</code>).

   To enable this feature set \ref cfg_generate_OHp "GENERATE_OHP" to \c YES.
   You also need to fill in the other QGG help related options, such as
   \ref cfg_OHp_namespace "OHP_NAMESPACE", 
   \ref cfg_OHg_location "OHG_LOCATION", 
   \ref cfg_OHp_virtual_folder "OHP_VIRTUAL_FOLDER".
   See <a href="https://doc.QGG.io/archives/qq/qq28-QGGhelp.html#htmlfilesandhelpprojects">this article</a> 
   for more info.

   Feature wise the QGG 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 QGG 4.5 (or better) for
   each user, or distributing the QGG 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>7. Eclipse Help Plugin</h2>
   If you use eclipse, you can embed the documentation generated by
   analyze 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 a 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 analyze 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
   QGG compressed help or CHM output, but it does require that Eclipse is
   installed and running.

\htmlonly
Go to the <a href="customize.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly

*/
