diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 7 | ||||
| -rw-r--r-- | doc/commands.doc | 11 | ||||
| -rw-r--r-- | doc/htmlcmds.doc | 2 | ||||
| -rw-r--r-- | doc/language.tpl | 130 | ||||
| -rw-r--r-- | doc/translator.bat | 4 | ||||
| -rw-r--r-- | doc/translator.pl | 752 |
6 files changed, 904 insertions, 2 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in index b3186ac..1c7a664 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: FORCE +all: language.doc FORCE DOXYGEN_DOCDIR=$(DOXYDOCS); \ export DOXYGEN_DOCDIR; \ VERSION=$(VERSION) ; \ @@ -26,6 +26,9 @@ all: FORCE @cp doxygen_logo.eps ../latex clean: - rm -rf ../html ../latex + rm -rf ../html ../latex language.doc + +language.doc: language.tpl FORCE + $(PERL) translator.pl FORCE: diff --git a/doc/commands.doc b/doc/commands.doc index bdbbbae..a3b89e7 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -86,6 +86,7 @@ documentation: <li> \refitem cmdingroup \ingroup <li> \refitem cmdinternal \internal <li> \refitem cmdinvariant \invariant +<li> \refitem cmdinterface \interface <li> \refitem cmdlatexonly \latexonly <li> \refitem cmdli \li <li> \refitem cmdline \line @@ -350,6 +351,16 @@ Doxygen. Unrecognized commands are treated as normal text. \sa section \ref cmddefgroup "\\defgroup". <hr> +\subsection cmdinterface \interface + + \addindex \interface + Indicates that a comment block contains documentation for an + interface with name \<name\>. The arguments are equal to the \\class + command. + + \sa section \ref cmdclass "\\class". + +<hr> \subsection cmdinternal \internal \addindex \internal diff --git a/doc/htmlcmds.doc b/doc/htmlcmds.doc index 7e7f4b6..0429139 100644 --- a/doc/htmlcmds.doc +++ b/doc/htmlcmds.doc @@ -83,6 +83,8 @@ documentation. Note that all attributes of a HTML tag are ignored <li>\c </TR> Does not generate any output. <li>\c <TT> Starts a piece of text displayed in a typewriter font. <li>\c </TT> Ends a \c <TT> section. +<li>\c <KBD> Starts a piece of text displayed in a typewriter font. +<li>\c </KBD> Ends a \c <KBD> section. <li>\c <UL> Starts an unnumbered item list. <li>\c </UL> Ends an unnumbered item list. <li>\c <VAR> Starts a piece of text displayed in an italic font. diff --git a/doc/language.tpl b/doc/language.tpl new file mode 100644 index 0000000..f7eb542 --- /dev/null +++ b/doc/language.tpl @@ -0,0 +1,130 @@ +/****************************************************************************** + * <notice>This is the template for generating language.doc. Edit this file, + * not the language.doc.</notice> + * + * + * Copyright (C) 1997-2001 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 langhowto Internationalization + +<h3>Support for multiple languages</h3> + +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): +$languages. + +The table of information related to the supported languages follows. +It is sorted by language alphabetically. The <B>Status</B> column +was generated from sources and shows approximately the last version +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 +doing other things, so if you want to help to speed things up please +let them (or me) know. + +If you want to add support for a language that is not yet listed +please see the next section. + +<h3>Adding a new language to doxygen</h3> + +This short HOWTO explains how to add support for a new language to Doxygen: + +Just follow these steps: +<ol> +<li>Tell me for which language you want to add support. If no one else + is already working on support for that language, you will be + assigned as the maintainer for the language. +<li>Create a copy of translator_en.h and name it + translator_<your_2_letter_counter_code>.h + I'll use xx in the rest of this document. +<li>Edit language.cpp: + Add a +\verbatim +#include<translator_xx.h> +\endverbatim + in <code>setTranslator()</code> add +\verbatim + else if (L_EQUAL("your_language_name")) + { + theTranslator = new TranslatorYourLanguage; + } +\endverbatim + after the <code>if { ... }</code> +<li>Edit libdoxygen.pro.in and add \c translator_xx.h to + the \c HEADERS line in the file doxygen.pro. +<li>Edit <code>translator_xx.h</code>: + <ul> + <li>Rename <code>TRANSLATOR_EN_H</code> to <code>TRANSLATOR_XX_H</code> twice. + <li>Rename TranslatorEnglish to TranslatorYourLanguage + <li>In the member <code>idLanguage()</code> change "english" into the + name of the your language (use lower case characters only). Depending + on the language you may also wish to change the member functions + latexLanguageSupportCommand() and idLanguageCharset(). + <li>Edit all the strings that are returned by the member functions that + start with tr. + Try to match punctuation and capitals! + To enter special characters (with accents) you can: + <ul> + <li> Enter them directly if your keyboard supports that and you are + using a Latin-1 font. + Doxygen will translate the characters to proper Latex and + leave the Html and man output for what it is (which is fine, if + idLanguageCharset() is set correctly). + <li> Use html codes like \ä for an a with an umlaut (i.e. ä). + See the HTML specification for the codes. + </ul> + </ul> +<li>Run configure and make again from the root of the distribution, + in order to regenerated the Makefiles. +<li>Now you can use <code>OUTPUT_LANGUAGE = your_language_name</code> + in the config file to generate output in your language. +<li>Send <code>translator_xx.h</code> to me so I can add it to doxygen. +</ol> + +<h3>Maintaining a language</h3> + +As new versions of doxygen appear, new sentences will be +added to the Translator interface class. Of course these need to be translated +as well (otherwise doxygen wouldn't even compile!). + +Waiting until all language maintainers have translated these new sentences +and sent the results would not be very practical for me. + +Instead, a new class TranslatorAdapter_x_y_z will be added to +translator_adapter.h (here x,y, and z correspond to the current +version of doxygen). And all translators that previous derived from +Translator will now derive from this adapter class. + +The Adapter class contains the new sentences with +default translations using the English translator (which is always up to date). +Instead of deriving your TranslatorXX class directly from Translator it will +derive from the intermediate class TranslatorAdapter_x_y_z. + +Thus, if a translator class inherits from a adapter class +maintenance is needed. By looking at the adapter class itself (and its base +classes) you can easily see which methods need to be updated. + +To update a language simply make your translator class derive from +the abstract class Translator and provide translations for the methods that +were previously provided by the adapter class (and its base classes). + +*/ + diff --git a/doc/translator.bat b/doc/translator.bat new file mode 100644 index 0000000..fc12581 --- /dev/null +++ b/doc/translator.bat @@ -0,0 +1,4 @@ +:start +call perl -w translator.pl +pause +goto start
\ No newline at end of file diff --git a/doc/translator.pl b/doc/translator.pl new file mode 100644 index 0000000..f5b889e --- /dev/null +++ b/doc/translator.pl @@ -0,0 +1,752 @@ +#! /usr/bin/perl -w +# -*- mode: perl; mode: fold -*- + +# This is a Perl script for Doxygen developers. +# Its main purpose is to extract the information from sources +# related to internationalization (the translator classes). +# +# Petr Prikryl (prikrylp@skil.cz) +# History: +# -------- +# 2001/04/27 +# - First version of the script. +# +# 2002/05/02 +# - Update to accept updateNeededMessage() in the Translator class. +# - First version that generates doc/language.doc. +# +################################################################ + +require 5.005; +use strict; +use Carp; + +# Global variables +# +my $doxygenrootdir = ".."; +my $srcdir = "$doxygenrootdir/src"; +my $docdir = "$doxygenrootdir/doc"; + +# Names of the output files. +# +my $ftxt = "translator_report.txt"; +my $fdoc = "language.doc"; + + +################################################################ +# GetPureVirtual returns a hash of pure virtual method prototypes +# in a hash where the key is the method prototype, and the value +# is 1. The input argument is the full name of the source file. +# +sub GetPureVirtualFrom ##{{{ +{ + my $fin = shift; # Get the file name. + + # Let's open the file and read it into a single string. + # + open(FIN, "< $fin") or die "\nError when open < $fin: $!"; + my @content = <FIN>; + close FIN; + my $cont = join("", @content); + + # Remove comments and empty lines. + # + $cont =~ s{\s*//.*$}{}mg; # remove one-line comments + while ($cont =~ s{/\*.+?\*/}{}sg ) {} # remove C comments + $cont =~ s{\n\s*\n}{\n}sg; # remove empty lines + + # Remove the beginning up to the first virtual method. + # Remove also the text behind the class. + # + $cont =~ s/^.*?virtual/virtual/s; + $cont =~ s/\n\};.*$//s; + + # Erase anything between "=0;" and "virtual". Only the pure + # virtual methods will remain. Remove also the text behind + # the last "= 0;" + # + $cont =~ s{(=\s*0\s*;).*?(virtual)}{$1 $2}sg; + $cont =~ s{^(.+=\s*0\s*;).*?$}{$1}s; + + # Remove the empty implementation of the updateNeededMessage() + # method which is to be implemented by adapters only, not by + # translators. + # + $cont =~ s{\s*virtual + \s+QCString + \s+updateNeededMessage\(\) + \s+\{\s*return\s+"";\s*\} + } + {}xs; + + # Replace all consequent white spaces (including \n) by a single + # space. Trim also the leading and the trailing space. + # + $cont =~ s{\s+}{ }sg; + $cont =~ s{^\s+}{}s; + $cont =~ s{\s+$}{}s; + + # Split the result to the lines again. Remove the "= 0;". + # + $cont =~ s{\s*=\s*0\s*;\s*}{\n}sg; + + # Remove the keyword "virtual" because the derived classes + # may not use it. + # + $cont =~ s{^virtual\s+}{}mg; + + # Split the string into array of lines and fill the output hash. + # + my %result = (); + + foreach (split(/\n/, $cont)) { + $result{$_} = 1; + } + + return %result; +} +##}}} + + +################################################################ +# GetInfoFrom returns the list of information related to the +# parsed source file. The input argument is the name of the +# translator_xx.h file including path. +# +# The output list contains the following items: +# - class identifier +# - base class identifier +# - method prototypes (each in a separate item) +# +sub GetInfoFrom ##{{{ +{ + # Get the file name. + # + my $fin = shift; + + # Let's open the file and read it into a single string. + # + open(FIN, "< $fin") or die "\nError when open < $fin: $!"; + my @content = <FIN>; + close FIN; + my $cont = join("", @content); + + # 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 + + # Extract the class and base class identifiers. Remove the + # opening curly brace. Remove also the first "public:" + # Put the class and the base class into the output list. + # + $cont =~ s{^.*class\s+(Translator\w+)[^:]*: + \s*public\s+(\w+)\b.*?\{\s* + (public\s*:\s+)? + } + {}sx; + + @content = ($1, $2); + + # Cut the things after the class. + # + $cont =~ s{\}\s*;\s*#endif\s*$}{}s; + + # Remove the "virtual" keyword, because some the derived class + # is not forced to use it. + # + $cont =~ s{^\s*virtual\s+}{}mg; + + # Remove all strings from lines. + # + $cont =~ s{".*?"}{}mg; + + # Remove all bodies of methods; + # + while ($cont =~ s/{[^{}]+?}//sg) {} + + # Remove all private methods, i.e. from "private:" to "public:" + # included. Later, remove also all from "private:" to the end. + # + $cont =~ s{private\s*:.*?public\s*:}{}sg; + $cont =~ s{private\s*:.*$}{}s; + + # Some of the translators use conditional compilation where + # the branches define the body of the method twice. Remove + # the ifdef/endif block content. + # + $cont =~ s{#ifdef.*?#endif}{}sg; + + # Now the string should containt only method prototypes. + # Let's unify their format by removing all spaces that + # are not necessary. Then let's put all of them on separate + # lines (one protototype -- one line; no empty lines). + # + $cont =~ s{\s+}{ }sg; + $cont =~ s{^\s+}{}s; + $cont =~ s{\s+$}{}s; + + $cont =~ s{\)\s*}{)\n}g; + + # Split the string and add it to the ouptut list. + # + @content = (@content, split(/\n/, $cont)); + return @content; +} +##}}} + + +################################################################ +# GenerateLanguageDoc takes document templates and code sources +# generates the content as expected in the language.doc file (the +# part of the Doxygen documentation), and returns the result as a +# string. +# +sub GenerateLanguageDoc ##{{{ +{ + # Get the references to the hash of class/base class. + # + my $rcb = shift; + + # Define templates for HTML table parts of the documentation. #{{{ + # + my $htmlTableHead = <<'xxxTABLE_HEADxxx'; +\htmlonly +<TABLE ALIGN=center CELLSPACING=0 CELLPADDING=0 BORDER=0> +<TR BGCOLOR="#000000"> +<TD> + <TABLE CELLSPACING=1 CELLPADDING=2 BORDER=0> + <TR BGCOLOR="#4040c0"> + <TD ><b><font size=+1 color="#ffffff"> Language </font></b></TD> + <TD ><b><font size=+1 color="#ffffff"> Maintainer </font></b></TD> + <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} & {Contact address} & {Status} \\ +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/language.tpl"; + 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/maintainers.txt"; + 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 information of 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 contatenation 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{ř}{ř}sg; + + $tableLATEX =~ s/ř/\\v{r}/sg; + $tableLATEX =~ s/á/\\'{a}/sg; + $tableLATEX =~ s/ä/\\"{a}/sg; + $tableLATEX =~ s/ö/\\"{o}/sg; + $tableLATEX =~ s/_/\\_/sg; + + $output =~ s{\$information_table}{$tableHTML$tableLATEX}; + ##}}} + + # 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; + ##}}} + + # Return the content of the generated output file. + # + return $output; +} +##}}} + + +################################################################ +# Body +# +{ + # The translator base class must be present. Exit otherwise. #{{{ + # + if (!-f "$srcdir/translator.h") + { + print STDERR "\n\nThe translator.h not found in $srcdir.\n\n\a"; + exit 1; + } + ##}}} + + # Find all translator_xx.h files. #{{{ + # + my @entries = (); # init + + opendir DIR, $srcdir or confess "opendir error for $srcdir: $!"; + foreach (readdir(DIR)) { if (!/^\./) { push @entries, $_; } } + closedir DIR; # ignore names with dot at the beginning + + my @files = sort + grep { -f "$srcdir/$_" && m{^translator_..\.h$}i } + @entries; + ##}}} + + # Get only the pure virtual methods from the Translator class + # into a hash structure for later testing present/not present. + # + my %required = GetPureVirtualFrom("$srcdir/translator.h"); + + # Collect base classes of translators the hash. + # + my %cb = (); + + # The details for translators will be collected into the output + # string. + # + my $output = ''; + + # Loop through all translator files. Extract the implemented + # virtual methods and compare it with the requirements. Prepare + # the output. + # + foreach (@files) { + + # Get the information from the sources. Remember the base + # class for each of the classes. #{{{ + # + my @info = GetInfoFrom("$srcdir/$_"); + + my $class = shift @info; + my $base = shift @info; + + $cb{$class} = $base; + ##}}} + + # Set the value of the required methods to 1 (true). Let + # this indicate that the method was not defined in the + # translator class. + # + foreach (keys %required) { $required{$_} = 1; } + + # Loop through all items and compare the prototypes. Mark + # the implemented method and collect the old ones. #{{{ + # + my @old_methods = (); + + foreach my $method (@info) { + if (defined $required{$method}) { $required{$method} = 0; } + else {push(@old_methods, $method); } + } + ##}}} + + # Loop through the required hash and collect the missing + # (new) methods. Do this only when it derives from + # Translator or TranslatorAdapter classes. #{{{ + # + my @missing_methods = (); + + if ($base =~ m/^Translator(Adapter.*)?$/) { + foreach (keys %required) { + if ($required{$_}) { push(@missing_methods, $_); } + } + } + ##}}} + + # The detailed output will be produced only when it is + # needed. #{{{ + # + if (@old_methods || @missing_methods + || $base !~ m/^Translator(Adapter.*)?$/) { + + $output .= "\n\n\n"; + $output .= $class . " ($base)\n" . '-' x length($class) . "\n"; + + if ($base !~ m/^Translator(Adapter.*)?$/) { + $output .= "\nThis is the unusual implementation of the " + . "translator. Its class is derived\n" + . "from the $base base class. The usual translator" + . "class derives\n" + . "or from the Translator class or from some " + . "TranslatorAdapter_x_x_x classes.\n" + . "Because of that, nothing can be guessed about " + . "missing methods.\n"; + } + + if (@missing_methods) { + $output .= "\nMissing methods (should be implemented):\n\n"; + foreach (@missing_methods) { $output .= " $_\n"; } + } + + if (@old_methods) { + $output .= "\nObsolete methods (should be removed):\n\n"; + foreach (sort @old_methods) { $output .= " $_\n"; } + } + } + ##}}} + } + + + # Generate the textual output file. + # + my $fout = "$docdir/$ftxt"; + + # Open it first. + # + open(FOUT, "> $fout") or die "\nError when open > $fout: $!"; + + # List the supported languages. #{{{ + # + my @all_translators = keys %cb; + + print FOUT "Doxygen supports the following (" . @all_translators + . ") languages (sorted alphabetically):\n\n"; + + foreach (sort grep { s/^Translator(\w+)\b.*$/$1/ } @all_translators) { + print FOUT " $_\n"; + } + ##}}} + + # If there are up-to-date translators, list them. #{{{ + # + my @list = sort grep { $cb{$_} =~ m/^Translator$/ } 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"; + + foreach (@list) { print FOUT " $_\n"; } + } + ##}}} + + # If there are obsolete translators, list them. #{{{ + # + @list = sort grep { $cb{$_} =~ m/^TranslatorAdapter/ } keys %cb; + + if (@list) { + print FOUT "\n" .'-' x 70 . "\n"; + print FOUT "The following translator classes are obsolete " + . "(sorted alphabetically).\n" + . "This means that they derive from some of " + . "the adapter classes.\n\n"; + + foreach (@list) { print FOUT " $_\t($cb{$_})\n"; } + } + ##}}} + + # If there are other translators, list them. #{{{ + # + @list = sort + grep { $cb{$_} !~ m/^Translator$/ } + grep { $cb{$_} !~ m/^TranslatorAdapter/ } + keys %cb; + + if (@list) { + print FOUT "\n" .'-' x 70 . "\n"; + print FOUT "The following translator classes are somehow different\n" + . "(sorted alphabetically). This means that they " + . "do not derive from\n" + . "the Translator class, nor from some of the adapter classes.\n\n"; + + foreach (@list) { print FOUT " $_\t($cb{$_})\n"; } + } + ##}}} + + # List the methods that are expected to be implemented. #{{{ + print FOUT "\n\n" .'-' x 70 . "\n"; + print FOUT "Localized translators are expected to implement " + . "the following methods\n" + . "(prototypes sorted aplhabetically):\n\n"; + + foreach (sort keys(%required)) { + print FOUT "$_\n"; + } + ##}}} + + # If there are some details for the translators, show them. #{{{ + # + if ($output !~ m/^\s*$/) { + print FOUT "\n\n" .'-' x 70 . "\n"; + print FOUT "Details related to specific translator classes follows.\n" + . "Notice that the prototypes are recognized only when they\n" + . "are the same as in the Translator class."; + + print FOUT $output . "\n"; + } + ##}}} + + # Close the output file + # + close FOUT; + + # Generate the language.doc file. + # + $fout = "$docdir/$fdoc"; + + # Open it first for the output. + # + open(FOUT, "> $fout") or die "\nError when open > $fout: $!"; + + print FOUT GenerateLanguageDoc(\%cb); + + # Close the output file + # + close FOUT; + + + exit 0; +} +# end of body +################################################################ + |