Release-1.2.7-20010524

11 files changed, 223 insertions, 50 deletions

diff --git a/doc/Makefile.in b/doc/Makefile.in
index 1c7a664..90c7d94 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -12,7 +12,7 @@
 # Documents produced by Doxygen are derivative works derived from the
 # input used in their production; they are not affected by this license.
 
-all: language.doc FORCE
+all: FORCE
 	DOXYGEN_DOCDIR=$(DOXYDOCS); \
 	export DOXYGEN_DOCDIR; \
         VERSION=$(VERSION) ; \
@@ -28,6 +28,8 @@ all: language.doc FORCE
 clean: 
 	rm -rf ../html ../latex language.doc
 
+language: language.doc language.tpl translator.pl
+
 language.doc: language.tpl FORCE
 	$(PERL) translator.pl
 
diff --git a/doc/Makefile.win_nmake.in b/doc/Makefile.win_nmake.in
index 07ea0d0..92829a1 100644
--- a/doc/Makefile.win_nmake.in
+++ b/doc/Makefile.win_nmake.in
@@ -26,5 +26,11 @@ all: FORCE
 
 clean: 
 	del /s /q ..\html ..\latex
+	del translator_report.txt *.bak
+
+language: language.doc language.tpl translator.pl
+
+language.doc: language.tpl FORCE
+	$(PERL) translator.pl
 
 FORCE:
diff --git a/doc/commands.doc b/doc/commands.doc
index a3b89e7..b0b9bc2 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -127,6 +127,7 @@ documentation:
 <li> \refitem cmdverbinclude \verbinclude
 <li> \refitem cmdversion \version
 <li> \refitem cmdwarning \warning
+<li> \refitem cmdweakgroup \weakgroup
 <li> \refitem cmddollar \$
 <li> \refitem cmdat \@
 <li> \refitem cmdbackslash \\
@@ -150,10 +151,14 @@ Doxygen. Unrecognized commands are treated as normal text.
     Structural indicators
     \htmlonly --- </center>\endhtmlonly</h2>
 
-\subsection cmdaddtogroup \addtogroup <name> 
+\subsection cmdaddtogroup \addtogroup <name> [(title)]
   \addindex \addtogroup
-  Add extra documentation to a group \<name\> that was previously defined 
-  using \\defgroup. This command can also be used to add a number of 
+  Defines a group just like \ref cmddefgroup "\\defgroup", but in contrast to
+  that command using the same \<name\> more than once will not result in a warning,
+  but rather one group with a merged documentation and the first title found in
+  any of the commands.
+
+  The title is optional, so this command can also be used to add a number of 
   entities to an existing group using \@{ and \@} like this:
 
 \verbatim
@@ -177,7 +182,8 @@ Doxygen. Unrecognized commands are treated as normal text.
   /*! @} */
 \endverbatim
 
-  See also \ref cmddefgroup "\\defgroup" and \ref cmdingroup "\\ingroup". 
+  \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", \ref cmdingroup "\\ingroup" and
+  \ref cmdweakgroup "\\weakgroup".
 
 \subsection cmdclass \class <name> [<header-file>] [<header-name>]
 
@@ -225,9 +231,10 @@ Doxygen. Unrecognized commands are treated as normal text.
   categories. You can also use groups as members of other groups,
   thus building a hierarchy of groups.
 
-  The \<name\> argument should an single word identifier.
+  The \<name\> argument should be a single word identifier.
   
-  \sa section \ref cmdingroup "\\ingroup"
+  \sa page \ref grouping "Grouping", sections \ref cmdingroup "\\ingroup", \ref cmdaddtogroup "\\addtogroup",
+  \ref cmdweakgroup "\\weakgroup".
 
 <hr>
 
@@ -348,7 +355,8 @@ Doxygen. Unrecognized commands are treated as normal text.
   class, file or namespace, then it will be added to the group or
   groups identified by \<groupname\>.
 
-  \sa section \ref cmddefgroup "\\defgroup".
+  \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup",
+  \ref cmdaddtogroup "\\addtogroup" and \ref cmdweakgroup "\\weakgroup"
 
 <hr>
 \subsection cmdinterface \interface 
@@ -556,6 +564,15 @@ Public/Protected/Private/... section.
   \sa section \ref cmdfn "\\fn" and \ref cmdtypedef "\\typedef".
 
 <hr>
+\subsection cmdweakgroup \weakgroup <name> [(title)]
+  \addindex \addtogroup
+  Can be used exactly like \ref cmdaddtogroup "\\addtogroup", but has
+  a lower priority when it comes to resolving conflicting grouping
+  definitions.
+
+  \sa page \ref grouping "Grouping" and \ref cmdaddtogroup "\\addtogroup".
+
+<hr>
 
 <h2>\htmlonly <center> --- \endhtmlonly 
     Section indicators
diff --git a/doc/config.doc b/doc/config.doc
index b41c9af..f5d1f1e 100644
--- a/doc/config.doc
+++ b/doc/config.doc
@@ -142,6 +142,7 @@ followed by the descriptions of the tags grouped by category.
 <li> \refitem cfg_latex_output LATEX_OUTPUT
 <li> \refitem cfg_macro_expansion MACRO_EXPANSION
 <li> \refitem cfg_man_extension MAN_EXTENSION
+<li> \refitem cfg_man_links MAN_LINKS
 <li> \refitem cfg_man_output MAN_OUTPUT
 <li> \refitem cfg_max_dot_graph_height MAX_DOT_GRAPH_HEIGHT
 <li> \refitem cfg_max_dot_graph_width MAX_DOT_GRAPH_WIDTH
@@ -997,6 +998,16 @@ EXTRA_PACKAGES = times
  \addindex MAX_EXTENSION
  The \c MAN_EXTENSION tag determines the extension that is added to
  the generated man pages (default is the subroutine's section .3)
+
+\anchor cfg_man_links
+<dt>\c MAN_LINKS <dd> 
+ \addindex MAN_LINKS
+ If the \c MAN_LINKS tag is set to \c YES and Doxygen generates man output, 
+ then it will generate one additional man file for each entity documented in 
+ the real man page(s). These additional files only source the real man page, 
+ but without them the man command would be unable to find the correct page. 
+ The default is \c NO.
+
 </dl>
 
 \subsection config_prepro Preprocessor related options
@@ -1138,22 +1149,22 @@ TAGFILES = file1=loc1 "file2 = loc2" ... </pre>
 \anchor cfg_include_graph
 <dt>\c INCLUDE_GRAPH <dd>
  \addindex INCLUDE_GRAPH 
- If the \c ENABLE_PREPROCESSING, \c INCLUDE_GRAPH, and \c HAVE_DOT tags are 
- set to \c YES then doxygen will generate a graph for each documented file 
+ If the \c ENABLE_PREPROCESSING, \c SEARCH_INCLUDES, \c INCLUDE_GRAPH, and \c HAVE_DOT
+ tags are set to \c YES then doxygen will generate a graph for each documented file
  showing the direct and indirect include dependencies of the file with other
  documented files.
 
 \anchor cfg_included_by_graph
 <dt>\c INCLUDED_BY_GRAPH <dd>
  \addindex INCLUDED_BY_GRAPH 
- If the \c ENABLE_PREPROCESSING, \c INCLUDED_BY_GRAPH, and \c HAVE_DOT tags are 
- set to \c YES then doxygen will generate a graph for each documented header
- file showing the documented files that directly or indirectly include this
- file.
+ If the \c ENABLE_PREPROCESSING, \c SEARCH_INCLUDES, \c INCLUDED_BY_GRAPH, and
+ \c HAVE_DOT tags are set to \c YES then doxygen will generate a graph for each
+ documented header file showing the documented files that directly or indirectly
+ include this file.
 
 \anchor cfg_graphical_hierarchy
 <dt>\c GRAPHICAL_HIERARCHY <dd>
- \addindex GRAPHICAL_HIERATCHY
+ \addindex GRAPHICAL_HIERARCHY
  If the \c GRAPHICAL_HIERARCHY and \c HAVE_DOT tags are set to \c YES then 
  doxygen will graphical hierarchy of all classes instead of a textual one.
 
diff --git a/doc/faq.doc b/doc/faq.doc
index 38d553a..7b4894b 100644
--- a/doc/faq.doc
+++ b/doc/faq.doc
@@ -17,7 +17,7 @@
 /*! \page faq Frequently Asked Questions
 
 <ol>
-<li><b>How do get information on the index page in HTML?</b>
+<li><b>How to get information on the index page in HTML?</b>
 <p>
 You should use the \\mainpage command inside a comment block like this:
 \verbatim
diff --git a/doc/grouping.doc b/doc/grouping.doc
index 71a8e37..ae80ae8 100644
--- a/doc/grouping.doc
+++ b/doc/grouping.doc
@@ -34,6 +34,7 @@ command in a special comment block. The first argument of the command
 is a label that should uniquely identify the group.  You can make an 
 entity a member of a specific group by putting 
 a \ref cmdingroup "\\ingroup" command inside its documentation block.
+The second argument is the title of the group.
 
 To avoid putting \ref cmdingroup "\\ingroup" commands in the documentation
 of each member you can also group members together by the 
@@ -44,11 +45,75 @@ documentation block.
 
 Groups can also be nested using these grouping markers.
 
+You will get an error message when you use the same group label more than once.
+If you don't want doxygen to enforce
+unique labels, then you can use \ref cmdaddtogroup "\\addtogroup" instead of
+\ref cmddefgroup "\\defgroup". It can be used exactly like \ref cmddefgroup "\\defgroup",
+but when the group has been defined already, then it silently merges the existing documentation
+with the new one.
+The title of the group is optional for this command, so you can use
+\verbatim
+/** \addtogroup <label> */
+/*\@{*/
+/*\@}*/
+\endverbatim
+to add members to a group that is defined in more detail elsewhere.
+
 Note that compound entities (like classes, files and namespaces) can
 be put into multiple groups, but members (like variable, functions, typedefs
 and enums) can only be a member of one group 
 (this restriction is to avoid ambiguous linking targets).
 
+Doxygen will put members into that group where the grouping definition had
+the highest priority: f.i. \ref cmdingroup "\\ingroup" overrides any automatic
+grouping definition via <code>\@{</code> <code>\@}</code>. Conflicting grouping
+definitions with the same priority trigger a warning, unless one definition
+was for a member without any explicit documentation. The following example
+puts VarInA into group A and silently resolves the conflict for IntegerVariable by
+putting it into group IntVariables, because the second instance of IntegerVariable
+is undocumented:
+
+\verbatim
+
+/**
+ * \ingroup A
+ */
+extern int VarInA;
+
+/**
+ * \defgroup IntVariables Global integer variables
+ */
+/*@{*/
+
+/** an integer variable */
+extern int IntegerVariable;
+
+/*@}*/
+
+....
+
+/**
+ * \defgroup Variables Global variables
+ */
+/*@{*/
+
+/** a variable in group A */
+int VarInA;
+
+int IntegerVariable;
+
+/*@}*/
+\endverbatim
+
+The priorities of grouping definitions are (from highest to lowest):
+\ref cmdingroup "\\ingroup", \ref cmddefgroup "\\defgroup",
+\ref cmdaddtogroup "\\addtogroup", \ref cmdweakgroup "\\weakgroup".
+The last command is exactly like \ref cmdaddtogroup "\\addtogroup"
+with a lower priority. It was added to allow "lazy" grouping
+definitions: you can use commands with a higher priority in your .h
+files to define the hierarchy and \ref cmdweakgroup "\\weakgroup"
+in .c files without having to duplicate the hierarchy exactly.
+
 \par Example:
 \verbinclude group.cpp
 
diff --git a/doc/install.doc b/doc/install.doc
index 70d625a..2a5a6e6 100644
--- a/doc/install.doc
+++ b/doc/install.doc
@@ -421,6 +421,10 @@ Here is what is required:
     to produce PDF output instead of DVI, or the PDF can be produced
     from PostScript using the utility <code>ps2pdf</code>.
 
+    If you want to use MikTeX then you need to download the
+    fancyhdr package separately. You can find it at:
+    ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/
+
 <li>If you want to generate compressed HTML help 
     (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the 
     config file, then you need the Microsoft HTML help workshop. 
diff --git a/doc/language.tpl b/doc/language.tpl
index f7eb542..18c0b40 100644
--- a/doc/language.tpl
+++ b/doc/language.tpl
@@ -1,6 +1,6 @@
 /******************************************************************************
- * <notice>This is the template for generating language.doc.  Edit this file,
- * not the language.doc.</notice>
+ * <notice>This is the template for generating language.doc.  
+ * Edit manually this file, not the language.doc!</notice>
  * 
  *
  * Copyright (C) 1997-2001 by Dimitri van Heesch.
@@ -23,7 +23,8 @@ Doxygen has support for multiple languages. This means
 that the text fragments that doxygen generates can changed into languages 
 other than English (the default) at configuration time.
 <p>
-Currently, $numlang languages are supported (sorted alphabetically): 
+Currently (version $version), $numlang languages 
+are supported (sorted alphabetically): 
 $languages.
 
 The table of information related to the supported languages follows.
@@ -33,7 +34,6 @@ when the translator was updated.
 <p>
 
 $information_table
-Have a look at <code>doxygen/doc/translator.txt</code> for more details.
 <p>
 
 Most people on the list have indicated that they were also busy
diff --git a/doc/maintainers.txt b/doc/maintainers.txt
index 16b9e46..bddd9d4 100644
--- a/doc/maintainers.txt
+++ b/doc/maintainers.txt
@@ -15,7 +15,7 @@ Petr P&rcaron;ikryl: prikrylp@skil.cz
 Vlastimil Havran: havran@fel.cvut.cz
 
 Danish
-Erik Søe Sørensen: erik@mail.nu
+Erik S&oslash;e S&oslash;rensen: erik@mail.nu
 
 Dutch 
 Dimitri van Heesch: dimitri@stack.nl
diff --git a/doc/translator.bat b/doc/translator.bat
index fc12581..3dccb13 100644
--- a/doc/translator.bat
+++ b/doc/translator.bat
@@ -1,4 +1 @@
-:start
-call perl -w translator.pl
-pause
-goto start
\ No newline at end of file
+@call perl -w translator.pl
diff --git a/doc/translator.pl b/doc/translator.pl
index f5b889e..375fe2b 100644
--- a/doc/translator.pl
+++ b/doc/translator.pl
@@ -4,6 +4,8 @@
 # This is a Perl script for Doxygen developers.  
 # Its main purpose is to extract the information from sources
 # related to internationalization (the translator classes).
+# It uses the information to generate documentation (language.doc,
+# translator_report.txt) from templates (language.tpl, maintainers.txt).
 #
 #                              Petr Prikryl (prikrylp@skil.cz)
 # History:
@@ -11,10 +13,26 @@
 # 2001/04/27
 #  - First version of the script.
 #
-# 2002/05/02
+# 2001/05/02
 #  - Update to accept updateNeededMessage() in the Translator class.
 #  - First version that generates doc/language.doc.
 #
+# 2001/05/07
+#  - Environment variable $doxygenrootdir now points to the
+#    Doxygen's root directory.
+#
+# 2001/05/11
+#  - Updated to reflect using TranslatorAdapterCVS as the base
+#    class for "almost up-to-date" translators.
+#  - $doxygenrootdir and other global variables for storing 
+#    directories determined from DOXYGEN_DOCDIR environment 
+#    variable. The change was done because the DOXYGEN_DOCDIR 
+#    was already used before.
+#  - $version mark can be used in the language.tpl template.
+#
+# 2001/05/18
+#  - Character entity &oslash; recognized in maintainers.txt.
+#
 ################################################################
 
 require 5.005;
@@ -23,14 +41,21 @@ use Carp;
 
 # Global variables
 #
-my $doxygenrootdir = "..";
-my $srcdir = "$doxygenrootdir/src";  
-my $docdir = "$doxygenrootdir/doc";  
+my $doxygenrootdir = 'directory set at the beginning of the body';
+my $srcdir =         'directory set at the beginning of the body';
+my $docdir =         'directory set at the beginning of the body';
+
+my $doxversion =     'set at the beginning of the body';
 
 # Names of the output files.
 #
-my $ftxt = "translator_report.txt";
-my $fdoc = "language.doc";
+my $ftranslatortxt = "translator_report.txt";
+my $flangdoc = "language.doc";
+
+# Names of the template files and other intput files.
+#
+my $flangtpl = "language.tpl";         # template for language.doc
+my $fmaintainers = "maintainers.txt";  # database of local lang. maintainers
 
 
 ################################################################
@@ -199,7 +224,7 @@ sub GetInfoFrom  ##{{{
 
 ################################################################
 # GenerateLanguageDoc takes document templates and code sources
-# generates the content as expected in the language.doc file (the
+# generates the content as expected in the $flangdoc file (the
 # part of the Doxygen documentation), and returns the result as a
 # string.
 #
@@ -250,7 +275,8 @@ xxxTABLE_FOOTxxx
 \latexonly
 \begin{tabular}{|l|l|l|l|}
   \hline 
-  {\bf Language} & {\bf Maintainer} & {Contact address} & {Status} \\
+  {\bf Language} & {\bf Maintainer} & {\bf Contact address} & {\bf Status} \\
+  \hline
 xxxTABLE_HEADxxx
   
     my $latexTableRow = <<'xxxTABLE_ROWxxx';
@@ -267,7 +293,7 @@ xxxTABLE_FOOTxxx
     # Read the template of the documentation, and join the content
     # to a single string. #{{{
     #
-    my $fin = "$docdir/language.tpl";
+    my $fin = "$docdir/$flangtpl";
     open(FIN, "< $fin") or die "\nError when open < $fin: $!";
     my @content = <FIN>;
     close FIN;
@@ -304,7 +330,7 @@ xxxTABLE_FOOTxxx
     # Read the information related to maintainers into the
     # string using suitable separators -- one line, one language. #{{{
     #
-    $fin = "$docdir/maintainers.txt";
+    $fin = "$docdir/$fmaintainers";
     open(FIN, "< $fin") or die "\nError when open < $fin: $!";
     my @maintainers = <FIN>;
     close FIN;
@@ -374,7 +400,7 @@ xxxTABLE_FOOTxxx
     foreach my $lang (sort keys %language) {
         
         # Read the line with info for the language and separate 
-        # the information of status. #{{{
+        # the status. #{{{
         #
         my @list = split(/<msep\/>/, $language{$lang});
         my $status = shift @list;
@@ -382,6 +408,10 @@ xxxTABLE_FOOTxxx
         my $i = $status =~ s{^Translator$}{up-to-date};
         
         if ($i == 0) { 
+            $i = $status =~ s{^TranslatorAdapterCVS}{almost up-to-date};
+        }
+        
+        if ($i == 0) { 
             $i = $status =~ s{^TranslatorAdapter_(\d)_(\d)_(\d)}
                              {$1.$2.$3}x;
         }
@@ -479,9 +509,9 @@ xxxTABLE_FOOTxxx
     ##}}}
     
     # Finish the tables, and substitute the mark in the doc
-    # template by the contatenation of the tables. Add NOSPAM to
-    # email addresses in the HTML table.  Replace the special
-    # character sequences. #{{{
+    # template by the contatenation of the tables and the notice
+    # about $ftranslatortxt.  Add NOSPAM to email addresses in the
+    # HTML table.  Replace the special character sequences. #{{{
     #
     $tableHTML .= $htmlTableFoot;
     $tableLATEX .= $latexTableFoot;
@@ -493,16 +523,26 @@ xxxTABLE_FOOTxxx
     $tableLATEX =~ s/&aacute;/\\'{a}/sg;
     $tableLATEX =~ s/&auml;/\\"{a}/sg;
     $tableLATEX =~ s/&ouml;/\\"{o}/sg;
+    $tableLATEX =~ s/&oslash;/\\o{}/sg;
     $tableLATEX =~ s/_/\\_/sg;
     
-    $output =~ s{\$information_table}{$tableHTML$tableLATEX};    
+    my $notice = "\nHave a look at <a href=\"../doc/$ftranslatortxt\"\n>"
+               . "<code>doxygen/doc/$ftranslatortxt</code></a> "
+               . "for more details.";
+
+    $output =~ s{\$information_table}{$tableHTML$tableLATEX$notice};
+
+    $output =~ s{\$version}{$doxversion};
+
     ##}}}
 
     # Replace the introduction notice in the output. #{{{
     #
     $output =~ s{<notice>.+?</notice>}
-{Warning: this file was generated from the language.tpl template
- *          Do not edit this file.  Edit the template!}sx;
+{Warning: this file was generated from the $flangtpl template
+ *          and the $fmaintainers files by the $0 script.  
+ *
+ *          Do not edit this file.  Edit the above mentioned files!}sx;
     ##}}}
 
     # Return the content of the generated output file.
@@ -516,6 +556,24 @@ xxxTABLE_FOOTxxx
 # Body
 #
 {
+    # Set the content of global variables using the environment
+    # variables. #{{{
+    #
+    $docdir = (defined $ENV{'DOXYGEN_DOCDIR'}) 
+                ? $ENV{'DOXYGEN_DOCDIR'} : '.';
+    
+    $docdir =~ s{\\}{/}g;
+    $docdir =~ s{/$}{};
+    
+    $doxygenrootdir = ($docdir eq '.') ? '..' : $docdir;
+    $doxygenrootdir =~ s{/doc$}{};
+
+    $srcdir = "$doxygenrootdir/src";
+
+    $doxversion = (defined $ENV{'VERSION'}) ? $ENV{'VERSION'} : 'unknown';
+
+    ##}}}
+    
     # The translator base class must be present.  Exit otherwise. #{{{
     #
     if (!-f "$srcdir/translator.h")
@@ -635,7 +693,7 @@ xxxTABLE_FOOTxxx
     
     # Generate the textual output file.
     #
-    my $fout = "$docdir/$ftxt";
+    my $fout = "$docdir/$ftranslatortxt";
     
     # Open it first.
     #
@@ -655,24 +713,37 @@ xxxTABLE_FOOTxxx
 
     # If there are up-to-date translators, list them.  #{{{
     #
-    my @list = sort grep { $cb{$_} =~ m/^Translator$/ } keys %cb;
+    my @list = sort grep { $cb{$_} =~ m/^Translator(AdapterCVS)?$/ } keys %cb;
     
     if (@list) {
         print FOUT "\n" .'-' x 70 . "\n";
         print FOUT "The following translator classes are up-to-date " 
                  . "(sorted alphabetically).\n"
                  . "This means that they derive from the Translator class.  "
-                 . "However, there still\n" 
-                 . "may be some details listed below "
-                 . "for them.  Please, check it.\n\n";
+                 . "If the translator\n"
+                 . "derives from TranslatorAdapterCVS, it is considered "
+                 . "to be almost up-to-date.\n"
+                 . "In other words, it is newer than the last official "
+                 . "release.  Anyway, there\n"
+                 . "still may be some details listed even for "
+                 . "the up-to-date translators.\n"
+                 . "Please, check the text below.\n\n";
         
-        foreach (@list) { print FOUT "  $_\n"; }
+        foreach (@list) { 
+            print FOUT "  $_";
+            
+            # For almost up-to-date translators, show also the base class.
+            #
+            if ($cb{$_} ne 'Translator') { print FOUT "\t($cb{$_})"; }
+            
+            print FOUT "\n"; 
+        }
     }
     ##}}}
 
     # If there are obsolete translators, list them.  #{{{
     #
-    @list = sort grep { $cb{$_} =~ m/^TranslatorAdapter/ } keys %cb;
+    @list = sort grep { $cb{$_} =~ m/^TranslatorAdapter_/ } keys %cb;
 
     if (@list) {
         print FOUT "\n" .'-' x 70 . "\n";
@@ -732,7 +803,7 @@ xxxTABLE_FOOTxxx
 
     # Generate the language.doc file.  
     #
-    $fout = "$docdir/$fdoc";
+    $fout = "$docdir/$flangdoc";
     
     # Open it first for the output.
     #