Release-1.6.1-20091222

8 files changed, 214 insertions, 59 deletions

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 0876ffa..01014fa 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -33,7 +33,8 @@ CASE_SENSE_NAMES  = NO
 IMAGE_PATH        = .
 INPUT             = index.doc install.doc starting.doc docblocks.doc lists.doc \
                     grouping.doc formulas.doc diagrams.doc preprocessing.doc \
-                    autolink.doc output.doc customize.doc custcmd.doc external.doc faq.doc trouble.doc history.doc features.doc \
+                    autolink.doc output.doc searching.doc customize.doc custcmd.doc \
+                    external.doc faq.doc trouble.doc history.doc features.doc \
 		    doxygen_usage.doc doxytag_usage.doc \
                     doxywizard_usage.doc installdox_usage.doc \
 		    config.doc commands.doc htmlcmds.doc xmlcmds.doc language.doc \
diff --git a/doc/commands.doc b/doc/commands.doc
index b56ebf3..e8cf0a6 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -466,10 +466,34 @@ Structural indicators
   The \<header-name\> argument can be used to overwrite the 
   name of the link that is used in the class documentation to something other 
   than \<header-file\>. This can be useful if the include name is not located 
-  on the default include path (like \<X11/X.h\>). With the \<header-name\>
+  on the default include path (like \<X11/X.h\>). 
+
+  With the \<header-name\>
   argument you can also specify how the include statement should look like, 
-  by adding either quotes or sharp brackets around the name. 
-  Sharp brackets are used if just the name is given.
+  by adding either double quotes or sharp brackets around the name. 
+  By default sharp brackets are used if just the name is given. 
+
+  If a pair of double quotes is given for either the header-file or 
+  header-name argument, the current file (in which the command was found) 
+  will be used but with quotes. So for a comment block with a \\headerfile
+  command inside a file test.h, the following three commands are equivalent:
+  \verbatim
+  \headerfile test.h "test.h"
+  \headerfile test.h ""
+  \headerfile "" \endverbatim
+  To get sharp brackets you do not need to specify anything,
+  but if you want to be explicit you could use any of the following:
+  \verbatim
+  \headerfile test.h <test.h>
+  \headerfile test.h <>
+  \headerfile <> \endverbatim
+
+  To globally reverse the default include representation to 
+  local includes you can set
+  \ref cfg_force_local_includes "FORCE_LOCAL_INCLUDES" to \c YES.
+
+  To disable the include information altogether set
+  \ref cfg_show_include_files "SHOW_INCLUDE_FILES" to \c NO.
 
 <hr>
 \section cmdhideinitializer \\hideinitializer
@@ -2467,12 +2491,12 @@ class Receiver
   prevent auto-linking to word that is also a documented class or struct. 
 
 <hr>
-\section cmdquot \\\"
+\section cmdquot \\"
 
   \addindex \\\"
   This command writes the \" character to the output. This 
-  character has to be escaped in some cases, because it is used to 
-  prevent auto-linking to word that is also a documented class or struct. 
+  character has to be escaped in some cases, because it is used in pairs
+  to indicate an unformated text fragment.
 
 <hr>
 \htmlonly <center> \endhtmlonly 
diff --git a/doc/config.doc b/doc/config.doc
index 9844686..b657883 100644
--- a/doc/config.doc
+++ b/doc/config.doc
@@ -115,6 +115,7 @@ followed by the descriptions of the tags grouped by category.
 \refitem cfg_file_version_filter FILE_VERSION_FILTER
 \refitem cfg_filter_patterns FILTER_PATTERNS
 \refitem cfg_filter_source_files FILTER_SOURCE_FILES
+\refitem cfg_force_local_includes FORCE_LOCAL_INCLUDES
 \refitem cfg_formula_fontsize FORMULA_FONTSIZE
 \refitem cfg_full_path_names FULL_PATH_NAMES
 \refitem cfg_generate_autogen_def GENERATE_AUTOGEN_DEF
@@ -152,6 +153,7 @@ followed by the descriptions of the tags grouped by category.
 \refitem cfg_html_header HTML_HEADER
 \refitem cfg_html_output HTML_OUTPUT
 \refitem cfg_html_stylesheet HTML_STYLESHEET
+\refitem cfg_html_timestamp HTML_TIMESTAMP
 \refitem cfg_idl_property_support IDL_PROPERTY_SUPPORT
 \refitem cfg_ignore_prefix IGNORE_PREFIX
 \refitem cfg_image_path IMAGE_PATH
@@ -217,6 +219,7 @@ followed by the descriptions of the tags grouped by category.
 \refitem cfg_search_includes SEARCH_INCLUDES
 \refitem cfg_searchengine SEARCHENGINE
 \refitem cfg_separate_member_pages SEPARATE_MEMBER_PAGES
+\refitem cfg_server_based_search SERVER_BASED_SEARCH
 \refitem cfg_short_names SHORT_NAMES
 \refitem cfg_show_dirs SHOW_DIRECTORIES
 \refitem cfg_show_files SHOW_FILES
@@ -708,10 +711,17 @@ function's detailed documentation block.
 \anchor cfg_show_include_files
 <dt>\c SHOW_INCLUDE_FILES <dd>
  \addindex SHOW_INCLUDE_FILES
- If the SHOW_INCLUDE_FILES tag is set to YES (the default) then doxygen
+ If the SHOW_INCLUDE_FILES tag is set to \c YES (the default) then doxygen
  will put a list of the files that are included by a file in the documentation 
  of that file.
 
+\anchor cfg_force_local_includes
+<dt>\c FORCE_LOCAL_INCLUDES <dd>
+ \addindex FORCE_LOCAL_INCLUDES
+ If the \c FORCE_LOCAL_INCLUDES tag is set to \c YES then Doxygen 
+ will list include files with double quotes in the documentation 
+ rather than with sharp brackets.
+
 \anchor cfg_inline_info
 <dt>\c INLINE_INFO <dd>
  \addindex INLINE_INFO 
@@ -1280,6 +1290,14 @@ FILE_VERSION_INFO = "cleartool desc -fmt \%Vn"
  See also section \ref doxygen_usage for information on how to generate
  the style sheet that doxygen normally uses.
 
+\anchor cfg_html_timestamp
+<dt>\c HTML_TIMESTAMP <dd>
+ \addindex HTML_TIMESTAMP
+ If the \c HTML_TIMESTAMP tag is set to \c YES then the footer of 
+ each generated HTML page will contain the date and time when the page 
+ was generated. Setting this to NO can help when comparing the output of 
+ multiple runs.
+
 \anchor cfg_html_align_members
 <dt>\c HTML_ALIGN_MEMBERS <dd>
  \addindex HTML_ALIGN_MEMBERS
@@ -1440,12 +1458,17 @@ FILE_VERSION_INFO = "cleartool desc -fmt \%Vn"
 \anchor cfg_searchengine
 <dt>\c SEARCHENGINE <dd>
  \addindex SEARCHENGINE
- The \c SEARCHENGINE tag specifies whether or not the HTML output should
- contain a search function. Possible values are \c YES and \c NO. 
- If set to YES, doxygen will produce a search index, and a search box at
- the top of each page (or in the side bar in case GENERATE_TREE is enabled).
- The search engine is implemented using javascript and DHTML and should
- work on any modern browser. 
+
+ When the \c SEARCHENGINE tag is enabled doxygen will generate a search box
+ for the HTML output. The underlying search engine uses javascript 
+ and DHTML and should work on any modern browser. Note that when using
+ HTML help (\ref cfg_generate_htmlhelp "GENERATE_HTMLHELP"), 
+ Qt help (\ref cfg_generate_qhp "GENERATE_QHP"), or docsets
+ (\ref cfg_generate_docset "GENERATE_DOCSET") there is already a search 
+ function so this one should typically be disabled. For large projects 
+ the javascript based search engine can be slow, then enabling 
+ \ref cfg_server_based_search "SERVER_BASED_SEARCH" may provide a 
+ better solution. 
 
  It is possible to search using the keyboard;
  to jump to the search box use access key + S (what the access key is
@@ -1457,29 +1480,17 @@ FILE_VERSION_INFO = "cleartool desc -fmt \%Vn"
  by pressing Shift+cursor down. Also here use the cursor keys to 
  select a filter and enter or escape to activate or cancel the filter option.
 
-<!--
-\anchor cfg_qthelp_file 
-<dt>\c QTHELP_FILE <dd>
- \addindex QTHELP_FILE
-  If the \c GENERATE_HTMLHELP tag is set to \c YES, the \c QTHELP_FILE tag can
-  be used to specify the file name of the resulting .(qch|qhp) file. 
-  You can add a path in front of the file if the result should not be
-  written to the html output directory.
-
-\anchor cfg_qthelp_config 
-<dt>\c QTHELP_CONFIG <dd>
- \addindex QTHELP_CONFIG
-  If \c DOXYGEN2QTHELP_LOC is set, \c QTHELP_CONFIG must specify the file name
-  of a config file to pass to doxygen2qthelp.
-
-\anchor cfg_doxygen2qthelp_loc 
-<dt>\c DOXYGEN2QTHELP_LOC <dd>
- \addindex DOXYGEN2QTHELP_LOC
-  If the \c GENERATE_HTMLHELP tag is set to \c YES, the \c DOXYGEN2QTHELP_LOC tag
-  can be used to specify the location (absolute path including file name) of 
-  the doxygen2qthelp tool. If non-empty doxygen will try to run doxygen2qthelp 
-  on the generated index.hhp.
--->
+\anchor cfg_server_based_search
+<dt>\c SERVER_BASED_SEARCH <dd>
+ \addindex SERVER_BASED_SEARCH
+
+When the SERVER_BASED_SEARCH tag is enabled the search engine will be
+implemented using a PHP enabled web server instead of at the web client
+using Javascript. Doxygen will generate the search PHP script and index 
+file to put on the web server. The advantage of the server
+based approach is that it scales better to large projects and also allows
+full text search. The disadvances is that it is more difficult to setup 
+and does not have live searching capabilities.
 
 \anchor cfg_disable_index
 <dt>\c DISABLE_INDEX <dd>
diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex
index b47569c..57865dd 100644
--- a/doc/doxygen_manual.tex
+++ b/doc/doxygen_manual.tex
@@ -60,6 +60,7 @@ Written by Dimitri van Heesch\\[2ex]
 \chapter{Preprocessing}\label{preprocessing}\hypertarget{preprocessing}{}\input{preprocessing}
 \chapter{Automatic link generation}\label{autolink}\hypertarget{autolink}{}\input{autolink}
 \chapter{Output Formats}\label{output}\hypertarget{output}{}\input{output}
+\chapter{Searching}\label{searching}\hypertarget{searching}{}\input{searching}
 \chapter{Customizing the Output}\label{customize}\hypertarget{customize}{}\input{customize}
 \chapter{Custom Commands}\label{custcmd}\hypertarget{custcmd}{}\input{custcmd}
 \chapter{Link to external documentation}\label{external}\hypertarget{external}{}\input{external}
@@ -68,10 +69,10 @@ Written by Dimitri van Heesch\\[2ex]
 \part{Reference Manual}
 \chapter{Features}\label{features}\hypertarget{features}{}\input{features}
 \chapter{Doxygen History}\label{history}\hypertarget{history}{}\input{history}
-\chapter{Doxygen usage}\label{doxygen_usage}\hypertarget{doxygen_usage}{}\input{doxygen_usage}
-\chapter{Doxytag usage}\label{doxytag_usage}\hypertarget{doxytag_usage}{}\input{doxytag_usage}
-\chapter{Doxywizard usage}\label{doxywizard_usage}\hypertarget{doxywizard_usage}{}\input{doxywizard_usage}
-\chapter{Installdox usage}\label{installdox_usage}\hypertarget{installdox_usage}{}\input{installdox_usage}
+\chapter{Doxygen usage}\label{doxygen__usage}\hypertarget{doxygen__usage}{}\input{doxygen__usage}
+\chapter{Doxytag usage}\label{doxytag__usage}\hypertarget{doxytag__usage}{}\input{doxytag__usage}
+\chapter{Doxywizard usage}\label{doxywizard__usage}\hypertarget{doxywizard__usage}{}\input{doxywizard__usage}
+\chapter{Installdox usage}\label{installdox__usage}\hypertarget{installdox__usage}{}\input{installdox__usage}
 \chapter{Configuration}\label{config}\hypertarget{config}{}\input{config}
 \chapter{Special Commands}\label{commands}\hypertarget{commands}{}\input{commands}
 \chapter{HTML commands}\label{htmlcmds}\hypertarget{htmlcmds}{}\input{htmlcmds}
diff --git a/doc/index.doc b/doc/index.doc
index ed1abbf..7996f78 100644
--- a/doc/index.doc
+++ b/doc/index.doc
@@ -74,6 +74,7 @@ The first part forms a user manual:
                  and members in the documentation.
 <li>Section \ref output shows how to generate the various output formats
                  supported by doxygen.
+<li>Section \ref searching shows various ways to search in the HTML documentation.
 <li>Section \ref customize explains how you can customize the output generated
                  by doxygen.
 <li>Section \ref custcmd show how to define and use custom commands in your comments.
diff --git a/doc/language.doc b/doc/language.doc
index 3dbd686..484f9ee 100644
--- a/doc/language.doc
+++ b/doc/language.doc
@@ -68,7 +68,7 @@ when the translator was updated.
     <td>Brazilian Portuguese</td>
     <td>Fabio "FJTC" Jun Takada Chino</td>
     <td>jun-chino at uol dot com dot br</td>
-    <td>1.6.0</td>
+    <td>up-to-date</td>
   </tr>
   <tr bgcolor="#ffffff">
     <td>Catalan</td>
@@ -311,7 +311,7 @@ when the translator was updated.
   \hline
   Arabic & Moaz Reyad & {\tt\tiny moazreyad@yahoo.com} & 1.4.6 \\
   \hline
-  Brazilian Portuguese & Fabio "FJTC" Jun Takada Chino & {\tt\tiny jun-chino@uol.com.br} & 1.6.0 \\
+  Brazilian Portuguese & Fabio "FJTC" Jun Takada Chino & {\tt\tiny jun-chino@uol.com.br} & up-to-date \\
   \hline
   Catalan & Maximiliano Pin & {\tt\tiny max.pin@bitroit.com} & 1.6.0 \\
   ~ & Albert Mora & {\tt\tiny amora@iua.upf.es} & ~ \\
diff --git a/doc/searching.doc b/doc/searching.doc
new file mode 100644
index 0000000..62f8971
--- /dev/null
+++ b/doc/searching.doc
@@ -0,0 +1,131 @@
+/******************************************************************************
+ *
+ * 
+ *
+ * Copyright (C) 1997-2009 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 5 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.
+*/
diff --git a/doc/translator_report.txt b/doc/translator_report.txt
index bca0e8e..40ad6d0 100644
--- a/doc/translator_report.txt
+++ b/doc/translator_report.txt
@@ -10,7 +10,7 @@ Persian, Polish, Portuguese, Romanian, Russian, Serbian,
 SerbianCyrilic, Slovak, Slovene, Spanish, Swedish, Turkish, Ukrainian,
 and Vietnamese.
 
-Of them, 6 translators are up-to-date, 32 translators are based on
+Of them, 7 translators are up-to-date, 31 translators are based on
 some adapter class, and 2 are English based.
 
 ----------------------------------------------------------------------
@@ -19,6 +19,7 @@ alphabetically). This means that they derive from the Translator class
 and they implement all 221 of the required methods. Anyway, there
 still may be some details listed even for them:
 
+  TranslatorBrazilian
   TranslatorCzech
   TranslatorDutch
   TranslatorEnglish
@@ -51,7 +52,6 @@ must be implemented to become up-to-date:
   TranslatorChinese               1.6.0 	 5 methods to implement (2 %)
   TranslatorChinesetraditional    1.6.0 	 5 methods to implement (2 %)
   TranslatorCatalan               1.6.0 	 5 methods to implement (2 %)
-  TranslatorBrazilian             1.6.0 	 5 methods to implement (2 %)
   TranslatorAfrikaans             1.6.0 	 5 methods to implement (2 %)
   TranslatorGreek                 1.5.4 	27 methods to implement (12 %)
   TranslatorDanish                1.5.4 	27 methods to implement (12 %)
@@ -154,20 +154,6 @@ TranslatorArabic   (TranslatorAdapter_1_4_6)  28 methods to implement (12 %)
     virtual QCString trNoDescriptionAvailable()
 
 
-TranslatorBrazilian   (TranslatorAdapter_1_6_0)  5 methods to implement (2 %)
--------------------
-
-  Implements 216 of the required methods (97 %).
-
-  Missing methods (should be implemented):
-
-    virtual QCString trSearching()
-    virtual QCString trNoMatches()
-    virtual QCString trLoading()
-    virtual QCString trGlobalNamespace()
-    virtual QCString trDirRelation(const char * name)
-
-
 TranslatorCatalan   (TranslatorAdapter_1_6_0)  5 methods to implement (2 %)
 -----------------