Release-1.2.10-20010923

1 files changed, 138 insertions, 10 deletions

diff --git a/doc/translator.pl b/doc/translator.pl
index 207f191..e031674 100644
--- a/doc/translator.pl
+++ b/doc/translator.pl
@@ -55,6 +55,28 @@
 #    equal prototypes from the base class and from the derived
 #    classes (if they should be considered equal).
 #
+# 2001/08/28
+#  - "see details" added to the up-to-date translator list 
+#    (in translator report) to translators for which some details
+#    are listed below in the report.  This is usually the case
+#    when the up-to-date translator still implements a obsolete
+#    method that will never be called (i.e. the code should be removed).
+#
+# 2001/09/10
+#  - The script now always exits with 0.  If the sources are not
+#    found, translator report is not generated.  If the $flangdoc
+#    is not also found and no sources are available, the simplified
+#    result with remarks inside is generated from the template.
+#    The consequences, translator.pl should never break the "make",
+#    and the language.doc should always be present after running
+#    this script -- no problem should occur when generating doxygen
+#    documentation.
+#
+# 2001/09/11
+#  - Minor (say cosmetic) enhancement.  The code for generating
+#    the simplified language.doc from the template was moved to 
+#    the separate function CopyTemplateToLanguageDoc().
+#
 ################################################################
 
 use 5.005;
@@ -642,6 +664,64 @@ xxxTABLE_FOOTxxx
 }
 ##}}}
 
+################################################################
+# CopyTemplateToLanguageDoc takes the $flangtpl template and 
+# generates $flangdoc without using information from other
+# sources.  This function is called when source files were not found.
+# The marks inside the template are replaced by warning-like
+# explanations that something could not be done because sources
+# were not available.  Writes directly to the file, returns nothing.
+#
+sub CopyTemplateToLanguageDoc ##{{{
+{
+    # The template file will be the source.
+    #
+    my $fin = "$docdir/$flangtpl"; 
+            
+    # Let's open the template and read it all into one string.
+    #
+    open(FIN, "< $fin") or die "\nError when open < $fin: $!";
+    my @content = <FIN>;
+    close FIN;
+    my $cont = join("", @content);
+    
+    # Replace the template marks by some notices.
+    #
+    $cont =~ s{<notice>.+?</notice>}
+{Warning: this file was generated from the $flangtpl template 
+ *          by the $0 script.  As doxygen sources were not available 
+ *          in that time, some information could not be extracted 
+ *          and inserted into this file.
+ *
+ *          Do not edit this file.  Edit the above mentioned files!}sx;
+            
+    $cont =~ s{\$version}{$doxversion};
+            
+    $cont =~ s{\$numlang}
+  {<b>[number of supported languages could not be extracted -- no sources]</b>};
+            
+    $cont =~ s{\$languages}
+        {<b>[names of languages could not be extracted -- no sources]</b>};
+            
+    $cont =~ s{\$information_table}
+        {<b>[Information table could not be extracted -- no sources.]</b>};
+            
+    $cont =~ s{\$translator_report_file_name}
+        {$ftranslatortxt <b>[translator report could not be 
+         generated -- no sources]</b>}x;
+            
+    $cont =~ s{\$translator_report_link}{<b>[no sources, no link]</b>};
+            
+    # Let's open the output file and copy the template content there.
+    #
+    my $fout = "$docdir/$flangdoc";
+            
+    open(FOUT, "> $fout") or die "\nError when open > $fout: $!";
+    print FOUT $cont;
+    close FOUT;
+}
+##}}}
+
 
 ################################################################
 # Body
@@ -672,16 +752,42 @@ print STDERR "\n\n";
 
     ##}}}
     
-    # The translator base class must be present.  Exit otherwise. #{{{
+    # The translator base class must be present.  Exit otherwise,
+    # but be kind to those who already have the documentation
+    # generated by this script ready, but who do not have sources. 
+    # If no $flangdoc is present, copy the template to it. #{{{
     #
-    if (!-f "$srcdir/translator.h")
-    {
-        print STDERR "\n\nThe translator.h not found in $srcdir.\n\n\a";
-        exit 1;
+    if (!-f "$srcdir/translator.h") {
+        print STDERR "\nThe $0 warning:\n"
+                     . "\tThe translator.h not found in $srcdir.\n"
+                     . "\tThe $ftranslatortxt will not be "
+                     . "generated (you don't need it).\n";
+
+        # $flangdoc is present, copy the template to it.
+        #
+        if (!-f "$docdir/$flangdoc") {
+
+            # Copy the template document to $flandoc with simplified
+            # replacement of the markers inside the template.
+            #
+            CopyTemplateToLanguageDoc();
+            
+            # Generate the warning about $flangdoc content.
+            #
+            print STDERR "\nThe $0 warning:\n"
+                . "\tThe $flangdoc not found in the '$docdir' directory.\n"
+                . "\tThe $flangtpl template content copied into it.\n"
+                . "\tAs the sources are not available, some information\n"
+                . "\tcould not be extracted and inserted into $flangdoc.\n";
+        }
+        
+        # Exit as if nothing happened.
+        #
+        exit 0;
     }
     ##}}}
 
-    # Find all translator_xx.h files. #{{{
+    # Find all translator_xx.h file names. #{{{
     #
     my @entries = ();  # init
 
@@ -700,9 +806,12 @@ print STDERR "\n\n";
     my @expected = GetPureVirtualFrom("$srcdir/translator.h");
 
     # The details for translators will be collected into the output
-    # string.
+    # string. If some details are listed for a translator, the flag
+    # will be set to produce possible warning to the list of
+    # up-to-date translators.
     #
     my $output = '';
+    my %details = ();
 
     # Remove the argument identifiers from the method prototypes
     # to get only the required form of the prototype. Fill the
@@ -728,7 +837,8 @@ print STDERR "\n\n";
     foreach (@files) {                               
 
         # Get the information from the sources.  Remember the base
-        # class for each of the classes. #{{{
+        # class for each of the classes.  Clear the flag for
+        # details for the class. #{{{
         #
         my @info = GetInfoFrom("$srcdir/$_");
         
@@ -736,6 +846,8 @@ print STDERR "\n\n";
         my $base = shift @info;
 
         $cb{$class} = $base;
+        $details{$class} = 0;
+        
         ##}}}
         
         # Set the value of the required methods to 1 (true).  Let
@@ -821,7 +933,12 @@ print STDERR "\n\n";
             if (@old_methods) {
                 $output .= "\nObsolete methods (should be removed):\n\n";
                 foreach (sort @old_methods) { $output .= "  $_\n"; }
-            }    
+            }
+                
+            # Some details were listed, set the details flag for
+            # the class.
+            #
+            $details{$class} = 1;
         }
         ##}}}
     }
@@ -863,15 +980,26 @@ print STDERR "\n\n";
                  . "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";
+                 . "Please, check the text below if the translator "
+                 . "is marked so.\n\n";
         
         foreach (@list) { 
+            
+            # Print the class name.
+            #
             print FOUT "  $_";
             
             # For almost up-to-date translators, show also the base class.
             #
             if ($cb{$_} ne 'Translator') { print FOUT "\t($cb{$_})"; }
             
+            # If some details were listed for the translator class,
+            # add a notice.
+            #
+            if ($details{$_}) {
+                print FOUT "\t-- see details below in the report"; 
+            }
+            
             print FOUT "\n"; 
         }
     }