Doxygen-1.2.13-20020122

7 files changed, 249 insertions, 21 deletions

diff --git a/doc/Makefile.win_make.in b/doc/Makefile.win_make.in
index 7951ed8..3161b31 100644
--- a/doc/Makefile.win_make.in
+++ b/doc/Makefile.win_make.in
@@ -13,7 +13,7 @@
 # input used in their production; they are not affected by this license.
 
 all: language FORCE
-	@xcopy /y /s /q /i ..\examples ..\html\examples
+	@xcopy /s /q /i ..\examples ..\html\examples
 	set DOXYGEN_DOCDIR=. & \
 	set VERSION=$(VERSION) & \
 	$(DOXYGEN)\bin\doxygen
diff --git a/doc/Makefile.win_nmake.in b/doc/Makefile.win_nmake.in
index bef074a..05820b0 100644
--- a/doc/Makefile.win_nmake.in
+++ b/doc/Makefile.win_nmake.in
@@ -13,7 +13,7 @@
 # input used in their production; they are not affected by this license.
 
 all: language FORCE
-	@xcopy /y /s /q /i ..\examples ..\html\examples
+	@xcopy /s /q /i ..\examples ..\html\examples
 	set DOXYGEN_DOCDIR=.
 	set VERSION=$(VERSION)
 	$(DOXYGEN)\bin\doxygen
diff --git a/doc/config.doc b/doc/config.doc
index 44c51b7..64facc2 100644
--- a/doc/config.doc
+++ b/doc/config.doc
@@ -93,9 +93,11 @@ followed by the descriptions of the tags grouped by category.
 <li> \refitem cfg_example_recursive EXAMPLE_RECURSIVE
 <li> \refitem cfg_exclude EXCLUDE
 <li> \refitem cfg_exclude_patterns EXCLUDE_PATTERNS
+<li> \refitem cfg_exclude_symlinks EXCLUDE_SYMLINKS
 <li> \refitem cfg_expand_as_defined EXPAND_AS_DEFINED
 <li> \refitem cfg_expand_only_predef EXPAND_ONLY_PREDEF
 <li> \refitem cfg_ext_doc_paths EXT_DOC_PATHS
+<li> \refitem cfg_external_groups EXTERNAL_GROUPS
 <li> \refitem cfg_extra_packages EXTRA_PACKAGES
 <li> \refitem cfg_extract_all EXTRACT_ALL
 <li> \refitem cfg_extract_local_classes EXTRACT_LOCAL_CLASSES
@@ -567,8 +569,11 @@ followed by the descriptions of the tags grouped by category.
  If the value of the \c INPUT tag contains directories, you can use the 
  \c FILE_PATTERNS tag to specify one or more wildcard patterns 
  (like \c *.cpp and \c *.h ) to filter out the source-files 
- in the directories. If left blank all files are included 
- (i.e. wildcard <tt>*</tt>).
+ in the directories. If left blank the following patterns are tested:
+ <code>
+ *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp 
+ *.h++ *.idl *.odl
+ </code>
 
 \anchor cfg_recursive
 <dt>\c RECURSIVE <dd>
@@ -584,6 +589,12 @@ followed by the descriptions of the tags grouped by category.
  excluded from the \c INPUT source files. This way you can easily exclude a
  subdirectory from a directory tree whose root is specified with the \c INPUT tag.
 
+\anchor cfg_exclude_symlinks
+<dt>\c EXCLUDE_SYMLINKS <dd>
+ \addindex EXCLUDE_SYMLINKS
+ The \c EXCLUDE_SYMLINKS tag can be used select whether or not files or directories 
+ that are symbolic links (a Unix filesystem feature) are excluded from the input.
+
 \anchor cfg_exclude_patterns
 <dt>\c EXCLUDE_PATTERNS <dd>
  \addindex EXCLUDE_PATTERNS
@@ -1168,6 +1179,13 @@ TAGFILES = file1=loc1 "file2 = loc2" ... </pre>
  in the class index. If set to \c NO only the inherited external classes
  will be listed.
 
+\anchor cfg_external_groups
+<dt>\c EXTERNAL_GROUPS <dd>
+ \addindex EXTERNAL_GROUPS
+ If the \c EXTERNAL_GROUPS tag is set to \c YES all external groups will be listed
+ in the modules index. If set to \c NO, only the current project's groups will
+ be listed.
+ 
 \anchor cfg_perl_path
 <dt>\c PERL_PATH <dd>
  \addindex PERL_PATH
diff --git a/doc/install.doc b/doc/install.doc
index f565ab1..49b3d9c 100644
--- a/doc/install.doc
+++ b/doc/install.doc
@@ -66,6 +66,9 @@ tools should be installed.
     \latexonly(see {\tt http://www.research.att.com/sw/tools/graphviz/})\endlatexonly.
     Needed for the include dependency graphs, 
     the graphical inheritance graphs, and the collaboration graphs.
+    \note If you compile graphviz yourself, make sure you do include
+    freetype support (which requires the freetype library and header files), 
+    otherwise dot will produce a warning that it cannot find doxfont!
 <li>The ghostscript interpreter.
 </ul>
 
diff --git a/doc/language.doc b/doc/language.doc
index 0815eea..2e9f518 100644
--- a/doc/language.doc
+++ b/doc/language.doc
@@ -60,7 +60,7 @@ when the translator was updated.
       <TD>Chinese</TD>  
       <TD>Wei Liu<br>Wang Weihan</TD>
       <TD>liuwei@NOSPAM.asiainfo.com<br>wangweihan@NOSPAM.capinfo.com.cn</TD>
-      <TD>1.2.11</TD>
+      <TD>up-to-date</TD>
   </TR>
   <TR BGCOLOR="#ffffff">
       <TD>Croatian</TD>  
@@ -213,7 +213,7 @@ when the translator was updated.
   \hline
   Brazilian & Fabio "FJTC" Jun Takada Chino & {\tt chino@icmc.sc.usp.br} & up-to-date \\
   \hline
-  Chinese & Wei Liu & {\tt liuwei@asiainfo.com} & 1.2.11 \\
+  Chinese & Wei Liu & {\tt liuwei@asiainfo.com} & up-to-date \\
    & Wang Weihan & {\tt wangweihan@capinfo.com.cn} &  \\
   \hline
   Croatian & Boris Bralo & {\tt boris.bralo@zg.tel.hr} & up-to-date \\
@@ -527,10 +527,24 @@ translator adapter, that is used as your base class. When there is
 not such a method in your translator adapter base class, you probably
 can change the translator adapter base to the newer one.
 
-Do not blindly implement all methods that are implemented by your
-translator adapter base class.  The reason is that the adapter
+Probably the easiest approach of the gradual update is to look at
+the translator report to the part where the list of the implemented
+translator adapters is shown. Then:
+ - Look how many required methods each adapter implements and guess
+   how many methods you are willing to update (to spend the time
+   with).  
+ - Choose the related oldest translator adapters to be removed (i.e.
+   not used by your translator).
+ - Change the base class of your translator class to the translator
+   adapter that you want to use.
+ - Implement the methods that were implemented by the older translator
+   adapters.
+
+Notice: Do not blindly implement all methods that are implemented by
+your translator adapter base class.  The reason is that the adapter
 classes implement also obsolete methods.  Another reason is that
-some of the methods could become obsolete from some newer adapter on.
+some of the methods could become obsolete from some newer adapter
+on.  Focus on the methods listed as \e required.
 
 <b>The really obsolete language translators</b> may lead to too much
 complicated adapters.  Because of that, doxygen developers may decide
diff --git a/doc/language.tpl b/doc/language.tpl
index d000bb6..bc14fd5 100644
--- a/doc/language.tpl
+++ b/doc/language.tpl
@@ -291,10 +291,24 @@ translator adapter, that is used as your base class. When there is
 not such a method in your translator adapter base class, you probably
 can change the translator adapter base to the newer one.
 
-Do not blindly implement all methods that are implemented by your
-translator adapter base class.  The reason is that the adapter
+Probably the easiest approach of the gradual update is to look at
+the translator report to the part where the list of the implemented
+translator adapters is shown. Then:
+ - Look how many required methods each adapter implements and guess
+   how many methods you are willing to update (to spend the time
+   with).  
+ - Choose the related oldest translator adapters to be removed (i.e.
+   not used by your translator).
+ - Change the base class of your translator class to the translator
+   adapter that you want to use.
+ - Implement the methods that were implemented by the older translator
+   adapters.
+
+Notice: Do not blindly implement all methods that are implemented by
+your translator adapter base class.  The reason is that the adapter
 classes implement also obsolete methods.  Another reason is that
-some of the methods could become obsolete from some newer adapter on.
+some of the methods could become obsolete from some newer adapter
+on.  Focus on the methods listed as \e required.
 
 <b>The really obsolete language translators</b> may lead to too much
 complicated adapters.  Because of that, doxygen developers may decide
diff --git a/doc/translator.pl b/doc/translator.pl
index 1bba346..5efecc0 100644
--- a/doc/translator.pl
+++ b/doc/translator.pl
@@ -95,6 +95,21 @@
 #    as "obsolete" in the status (i.e. no guessing when it was last updated).
 #    The translator report include the notice about that situation.
 #
+# 2002/01/03
+#  - Minor correction of regexp to obtain the list of translator_xx.h files.
+#  - Translator report ASCII file now lists the implemented translator
+#    adapter classes; so you can check how many steps behind the up-to-date
+#    status your translator is.
+#
+# 2002/01/07
+#  - The list of the implemented translator-adapter classes now shows
+#    how many and what required methods the translator adapter implements.
+#
+# 2002/01/08
+#  - The mistake in comments inside the translator report corrected.
+#    The older translator adapters are derived from newer ones.
+#    The mistaken comment said the opposite.
+#
 ################################################################
 
 use 5.005;
@@ -193,7 +208,7 @@ sub GetPureVirtualFrom  ##{{{
 ################################################################
 # StripArgIdentifiers takes a method prototype (one line string),
 # removes the argument identifiers, and returns only the necessary
-# form of the prototype.
+# form of the prototype as the function result.
 #
 sub StripArgIdentifiers  ##{{{
 {
@@ -234,7 +249,7 @@ sub StripArgIdentifiers  ##{{{
         # Whitespaces are not only spaces. Moreover, the difference
         # may be in number of them in a sequence or in the type 
         # of a whitespace. This is the reason to replace each sequence
-        # of whitespace by a single, real space.
+        # of whitespaces by a single, real space.
         #
         $arg =~ s{\s+}{ }g;
         
@@ -346,6 +361,149 @@ sub GetInfoFrom  ##{{{
 
 
 ################################################################
+# GetAdapterClassesInfo returns the list of strings with information
+# related to the adapter classes.  Each one-line string contains the
+# identifier of the adapter class and the number of required methods
+# that are implemented by the adapter.
+#
+# The function takes one agument -- the reference to the hash with
+# stripped prototypes of the required methods.
+#
+sub GetAdapterClassesInfo ##{{{
+{
+    # Get the reference to the hash with required prototypes.
+    #
+    my $reqref = shift; 
+    
+    # Let's open the file with the translator adapter classes.
+    #
+    my $fin = "$srcdir/translator_adapter.h";
+    open(FIN, "< $fin") or die "\nError when open < $fin: $!";
+    my @content = <FIN>;
+    close FIN;
+    my $cont = join("", @content);
+
+    # Prepare the list that will be returned as result.
+    #
+    my @result = ();
+    
+    # Remove the preprocessor directives.
+    #
+    $cont =~ s{^\s*#\w+.+$}{}mg;
+    
+    # Remove comments and empty lines.
+    #
+    $cont =~ s{\s*//.*$}{}mg;    # remove one-line comments
+    $cont =~ s{/\*.+?\*/}{}sg;   # remove C comments
+    $cont =~ s{\n\s*\n}{\n}sg;   # remove empty lines    
+
+    # Place delimiters to separate the classes, and remove 
+    # the TranslatorAdapterBase class.
+    #
+    $cont =~ s{\};\s*class\s+}{<class>}sg;
+    $cont =~ s{class\s+TranslatorAdapterBase\s+.+?<class>}{<class>}s;
+    $cont =~ s{\};}{}sg;
+    
+    # Remove the base classes and the beginning of the the class
+    # definitions.
+    #
+    $cont =~ s{(TranslatorAdapter[_0-9]+)\s*:.+?\{\s*(public\s*:)?}{$1}sg;
+    
+    # Remove all bodies of methods;
+    #
+    while ($cont =~ s/{[^{}]+?}//sg) {}
+    
+    # Remove the "virtual" keywords.
+    #
+    $cont =~ s{^\s*virtual\s+}{}mg;
+
+    # Remove the empty lines.
+    #
+    $cont =~ s{\n\s*\n}{\n}sg;
+
+    # Split the string into the lines again.
+    #
+    @content = split(/\n/, $cont);
+    
+    # Now the list contains only two kinds of lines.  The first
+    # kind of lines starts with the <class> tag and contains the
+    # identifier of the class.  The following lines list the
+    # non-stripped prototypes of implemented methods without the
+    # "virtual" keyword.
+    #
+    # Now we will produce the result by looping through all the
+    # lines and counting the prototypes of the required methods
+    # that are implemented by the adapter class.
+    #
+    my $info = '';
+    my $cnt = 0;
+    my $methods = '';
+    
+    foreach my $line (@content)
+    {
+        if ($line =~ m{^<class>(\w+)\s*$}i )
+        {
+            # Another adapter class found. 
+            #
+            my $adapter_class = $1;
+            
+            # If the $info is not empty then it contains partial
+            # information about the previously processed adapter. 
+            #
+            if ($info ne '')
+            {
+                # Complete the $info and push it into the @result.
+                #
+                $info .= sprintf("\timplements %2d required method%s...\n",
+                                 $cnt, (($cnt != 1) ? 's' : ''));
+                $methods .= "\n";
+                push(@result, "$info$methods");
+            }
+            
+            # Initialize the counter and store the adapter class identifier
+            # in the $info.
+            #
+            $info = $adapter_class;
+            $cnt = 0;
+            $methods = '';
+        }
+        else
+        {
+            # The line contains the prototype of the implemented method.
+            # If it is the required method, count it, and add it to the 
+            # string of methods.
+            #
+            my $stripped_prototype = StripArgIdentifiers($line);
+            
+            if (defined $$reqref{$stripped_prototype}) 
+            {
+                ++$cnt;
+                $methods .= "    $line\n";
+            }
+        }
+    }
+    
+    # If the $info is not empty then it contains partial
+    # information about the last processed adapter. 
+    #
+    if ($info ne '')
+    {
+        # Complete the $info and push it into the @result.
+        #
+        $info .= sprintf("\timplements %2d required method%s...\n",
+                         $cnt, (($cnt != 1) ? 's' : ''));
+        $methods .= "\n";
+        push(@result, "$info$methods");
+    }
+    
+    # Return the result list.
+    #
+    # push @result, $cont; # ???
+    return @result;
+}
+##}}}  
+
+################################################################
 # GenerateLanguageDoc takes document templates and code sources
 # generates the content as expected in the $flangdoc file (the
 # part of the Doxygen documentation), and returns the result as a
@@ -684,6 +842,7 @@ xxxTABLE_FOOTxxx
 }
 ##}}}
 
+
 ################################################################
 # CopyTemplateToLanguageDoc takes the $flangtpl template and 
 # generates $flangdoc without using information from other
@@ -816,7 +975,8 @@ print STDERR "\n\n";
     closedir DIR;          # ignore names with dot at the beginning
 
     my @files = sort 
-                grep { -f "$srcdir/$_" && m{^translator_..\.h$}i } 
+                grep { ! m{^translator_adapter\.h$}i }
+                grep { -f "$srcdir/$_" && m{^translator_\w+\.h$}i } 
                 @entries;
     ##}}}
     
@@ -832,13 +992,15 @@ print STDERR "\n\n";
     #
     my $output = '';
     my %details = ();
+    
+    # Initialize the list of the required methods.
+    #
+    my %required = ();
 
     # Remove the argument identifiers from the method prototypes
     # to get only the required form of the prototype. Fill the
     # hash with them. #{{{
     #
-    my %required = ();
-    
     foreach (@expected) {
         my $prototype = StripArgIdentifiers($_);
         $required{$prototype} = 1;
@@ -1110,17 +1272,34 @@ print STDERR "\n\n";
     }
     ##}}}
 
+    # List all the translator adapter classes to show for which versions
+    # the adapters had to be created.  Show, how many and what new methods
+    # are implemented by the adapters. #{{{
+    #
+    print FOUT "\n" .'-' x 70 . "\n";
+    print FOUT <<'xxxENDxxx';
+The following translator adapter classes are implemented -- the older (with
+lower number) are always derived from the newer. They implement the
+listed required methods. Notice that some versions of doxygen did not
+introduce any changes related to the language translators.  From here you may
+guess how much work should be done to update your translator:
+      
+xxxENDxxx
+  
+    my @adapter_info = GetAdapterClassesInfo(\%required);
+    
+    foreach (@adapter_info) { print FOUT "  $_"; }
+    
+    ##}}}
 
     # List the methods that are expected to be implemented.  #{{{
     #
-    print FOUT "\n\n" .'-' x 70 . "\n";
+    print FOUT "\n" .'-' x 70 . "\n";
     print FOUT "Localized translators are expected to implement "
              . "the following methods\n"
              . "(prototypes sorted aplhabetically):\n\n";
 
-    foreach (sort @expected) {
-        print FOUT "$_\n";
-    }
+    foreach (sort @expected) { print FOUT "$_\n";  }
     ##}}}
 
     # If there are some details for the translators, show them.  #{{{