summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.win_make.in2
-rw-r--r--doc/Makefile.win_nmake.in2
-rw-r--r--doc/config.doc22
-rw-r--r--doc/install.doc3
-rw-r--r--doc/language.doc24
-rw-r--r--doc/language.tpl20
-rw-r--r--doc/translator.pl197
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. #{{{