translator.pl

doxygen(一个自动从源代码生成文档的工具)的源代码

  <TD ><b><font size=+1 color="#ffffff"> Contact address </font>
          <font size=-2 color="#ffffff">(remove the NOSPAM.)</font></b></TD>
  <TD ><b><font size=+1 color="#ffffff"> Status </font></b></TD>
  </TR>
xxxTABLE_HEADxxx
  
    my $htmlTableRow = <<'xxxTABLE_ROWxxx';
  <TR BGCOLOR="#ffffff">
      <TD>$lang</TD>  
      <TD>$maintainer</TD>
      <TD>$email</TD>
      <TD>$status</TD>
  </TR>
xxxTABLE_ROWxxx

    my $htmlTableFoot = <<'xxxTABLE_FOOTxxx';
  </TABLE>
</TD>
</TR>
</TABLE>
\endhtmlonly
xxxTABLE_FOOTxxx
    ##}}}
    
    # Define templates for LaTeX table parts of the documentation. #{{{
    #
    my $latexTableHead = <<'xxxTABLE_HEADxxx';
\latexonly
\begin{tabular}{|l|l|l|l|}
  \hline 
  {\bf Language} & {\bf Maintainer} & {\bf Contact address} & {\bf Status} \\
  \hline
xxxTABLE_HEADxxx
  
    my $latexTableRow = <<'xxxTABLE_ROWxxx';
  $lang & $maintainer & {\tt $email} & $status \\
xxxTABLE_ROWxxx

    my $latexTableFoot = <<'xxxTABLE_FOOTxxx';
  \hline
\end{tabular}
\endlatexonly
xxxTABLE_FOOTxxx
    ##}}}
    
    # Read the template of the documentation, and join the content
    # to a single string. #{{{
    #
    my $fin = "$docdir/$flangtpl";
    open(FIN, "< $fin") or die "\nError when open < $fin: $!";
    my @content = <FIN>;
    close FIN;
    
    my $output = join("", @content);
    ##}}}
    
    # Make and substitute the list of supported languages and their
    # number. #{{{
    #
    my @languages = sort grep { s{^Translator}{} } keys %{$rcb};
    
    my $numlang = @languages;
    
    $output =~ s{\$numlang}{$numlang};
    
    my $languages =  join(", ", @languages);
    $languages =~ s{((\w+,\s){5})}{$1\n}g;
    $languages =~ s{Brazilian}{Brazilian Portuguese};
    $languages =~ s{(,\s+)(\w+)$}{$1and $2}s;
    
    $output =~ s{\$languages}{$languages};
    ##}}}

    # Create the hash of languages with the initial info. #{{{
    #
    my %language = ();
    
    foreach (@languages) {
        $language{$_} = $$rcb{"Translator$_"} . "<msep/>unknown: unknown";
    }
    ##}}}
    
    # Read the information related to maintainers into the
    # string using suitable separators -- one line, one language. #{{{
    #
    $fin = "$docdir/$fmaintainers";
    open(FIN, "< $fin") or die "\nError when open < $fin: $!";
    my @maintainers = <FIN>;
    close FIN;
    
    my $maintainers = join("", @maintainers);

    # Trim the spaces on the lines.  Strip the comment lines that
    # start with % sign.
    #
    $maintainers =~ s{^[ \t]+}{}mg;    
    $maintainers =~ s{[ \t]+$}{}mg;
    
    $maintainers =~ s{^%.*$}{}mg;

    # Join the information for one language into one line,
    # and remove empty lines.
    #
    $maintainers =~ s{\b\n\b}{<sep/>}sg;
    $maintainers =~ s{\n{2,}}{\n}sg;    
    $maintainers =~ s{^\n+}{}s;
    $maintainers =~ s{\n+$}{}s;
    ##}}}
    
    # Split the string back to the list, and update the information
    # in the hash with information for languages. #{{{
    #
    foreach my $line (sort split(/\n/, $maintainers)) {
        
        # Split the line for one language to separate lines for
        # the language and one or more maintainers.
        #
        my @info = split(/<sep\/>/, $line);
        
        my $lang = shift @info;
        
        # Ensure that the language starts with uppercase and 
        # continues with lowercase.
        #
        $lang =~ s{^(\w)(\w+)}{\U$1\L$2\E};

        # Add information to the %language hash.  If the language
        # was not defined in sources, add the question mark to the
        # language identifier.
        # 
        if (defined $language{$lang}) { 
            $language{$lang} = $$rcb{"Translator$lang"} . '<msep/>' 
                               . join("<sep/>", @info);
        }
        else {
            $lang .= " (?)";
            $language{$lang} = "unknown<msep/>" . join("<sep/>", @info);
        }
    }
    ##}}}

    # Now, the %language hash contains all the information needed for
    # generating the tables (HTML and LaTeX).  Define string variables
    # for each of the tables, and initialize them.  #{{{
    #
    my $tableHTML = $htmlTableHead;
    my $tableLATEX = $latexTableHead;
    ##}}}
    
    # Loop through sorted keys for the languages, parse the
    # information, and add it to the tables. #{{{
    #
    foreach my $lang (sort keys %language) {
        
        # Read the line with info for the language and separate 
        # the status. #{{{
        #
        my @list = split(/<msep\/>/, $language{$lang});
        my $status = shift @list;
        
        my $i = $status =~ s{^Translator$}{up-to-date};

        if ($i == 0) { 
            $i = $status =~ s{^TranslatorAdapter_(\d)_(\d)_(\d)}
                             {$1.$2.$3}x;
        }
        
        if ($i == 0) { $status = '?'; }
        
        ##}}}
        
        # Split the rest of the list (should be a single item) into
        # the list with one or more maintainers -- one line, one
        # maintainer. #{{{
        #
        my $rest = shift @list;
        @list = split(/<sep\/>/, $rest);
        ##}}}
        
        # In HTML table, maintainer names are placed in the same
        # cell.  Also their e-mails are placed in a single cell.
        # Extract the string with concatenated names and the string
        # with concatenated e-mails.  Add the row to the HTML
        # table. #{{{
        #
        my $name = '';
        my $email = '';

        foreach my $maintainer (@list) {
        
            if ($name ne '') { $name .= '<br>'; }
            if ($email ne '') { $email .= '<br>'; }

            $maintainer =~ m{^\s*(.+?)\s*:\s*(.+?)\s*$};
        
            $name .= $1;
            $email .= $2;
        }
        
        # Prepare the HTML row template, modify it, and add the
        # result to the HTML table.
        #
        my $item = $htmlTableRow;
        
        $item =~ s{\$lang}{$lang};
        $item =~ s{\$maintainer}{$name};
        $item =~ s{\$email}{$email};
        $item =~ s{\$status}{$status};
        
        $tableHTML .= $item;        
        
        ##}}}
        
        # For LaTeX, more maintainers for the same language are
        # placed on separate rows in the table.  The line separator
        # in the table is placed explicitly above the first
        # maintainer.  Add rows for all maintainers to the LaTeX
        # table. #{{{
        #
        # Prepare the LATEX row template, modify it, and add the
        # result to the LATEX table.
        #
        $item = $latexTableRow;

        my $first = shift @list;  # the first maintainer.
        $first =~ m{^\s*(.+?)\s*:\s*(.+?)\s*$};
        
        $name = $1;
        $email = $2;
        
        $item =~ s{\$lang}{$lang};
        $item =~ s{\$maintainer}{$name};
        $item =~ s{\$email}{$email};
        $item =~ s{\$status}{$status};
        
        $tableLATEX .= "  \\hline\n" . $item;        
        
        # List the other maintainers for the language. Do not set
        # lang and status for them.
        #
        while (@list) {
            my $next = shift @list;
            $next =~ m{^\s*(.+?)\s*:\s*(.+?)\s*$};
        
            my $name = $1;
            my $email = $2;
            my $item = $latexTableRow;
        
            $item =~ s{\$lang}{};
            $item =~ s{\$maintainer}{$name};
            $item =~ s{\$email}{$email};
            $item =~ s{\$status}{};
        
            $tableLATEX .= $item;        
        }
        ##}}}
    }
    ##}}}
    
    # Finish the tables, and substitute the mark in the doc
    # template by the concatenation of the tables.  Add NOSPAM to
    # email addresses in the HTML table.  Replace the special
    # character sequences. #{{{
    #
    $tableHTML .= $htmlTableFoot;
    $tableLATEX .= $latexTableFoot;

    $tableHTML =~ s{@}{\@NOSPAM.}sg; 
    $tableHTML =~ s{&ccaron;}{&#x010d;}sg; 
    $tableHTML =~ s{&rcaron;}{&#x0159;}sg; 
    
    $tableLATEX =~ s/&aacute;/\\'{a}/sg;
    $tableLATEX =~ s/&auml;/\\"{a}/sg;
    $tableLATEX =~ s/&ouml;/\\"{o}/sg;
    $tableLATEX =~ s/&oslash;/\\o{}/sg;
    $tableLATEX =~ s/&ccaron;/\\v{c}/sg;
    $tableLATEX =~ s/&rcaron;/\\v{r}/sg;
    $tableLATEX =~ s/_/\\_/sg;
    
    $output =~ s{\$information_table}{$tableHTML$tableLATEX};

    ##}}}

    # Replace the other symbols in the template by the expected
    # information. ##{{{
    #
    $output =~ s{\$version}{$doxversion};

    $output =~ s{\$translator_report_file_name}
                {<code>doxygen/doc/$ftranslatortxt</code>}x;

    $output =~ s{\$translator_report_link}
                {<a href=\"../doc/$ftranslatortxt\">
                 <code>doxygen/doc/$ftranslatortxt</code></a>}x;
    ##}}}

    # Replace the introduction notice in the output. #{{{
    #
    $output =~ s{<notice>.+?</notice>}
{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.
    #
    return $output;
}
##}}}

################################################################
# 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";