summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.in4
-rw-r--r--doc/Makefile.win_nmake.in6
-rw-r--r--doc/commands.doc31
-rw-r--r--doc/config.doc25
-rw-r--r--doc/faq.doc2
-rw-r--r--doc/grouping.doc65
-rw-r--r--doc/install.doc4
-rw-r--r--doc/language.tpl8
-rw-r--r--doc/maintainers.txt2
-rw-r--r--doc/translator.bat5
-rw-r--r--doc/translator.pl121
11 files changed, 223 insertions, 50 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 1c7a664..90c7d94 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: language.doc FORCE
+all: FORCE
DOXYGEN_DOCDIR=$(DOXYDOCS); \
export DOXYGEN_DOCDIR; \
VERSION=$(VERSION) ; \
@@ -28,6 +28,8 @@ all: language.doc FORCE
clean:
rm -rf ../html ../latex language.doc
+language: language.doc language.tpl translator.pl
+
language.doc: language.tpl FORCE
$(PERL) translator.pl
diff --git a/doc/Makefile.win_nmake.in b/doc/Makefile.win_nmake.in
index 07ea0d0..92829a1 100644
--- a/doc/Makefile.win_nmake.in
+++ b/doc/Makefile.win_nmake.in
@@ -26,5 +26,11 @@ all: FORCE
clean:
del /s /q ..\html ..\latex
+ del translator_report.txt *.bak
+
+language: language.doc language.tpl translator.pl
+
+language.doc: language.tpl FORCE
+ $(PERL) translator.pl
FORCE:
diff --git a/doc/commands.doc b/doc/commands.doc
index a3b89e7..b0b9bc2 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -127,6 +127,7 @@ documentation:
<li> \refitem cmdverbinclude \verbinclude
<li> \refitem cmdversion \version
<li> \refitem cmdwarning \warning
+<li> \refitem cmdweakgroup \weakgroup
<li> \refitem cmddollar \$
<li> \refitem cmdat \@
<li> \refitem cmdbackslash \\
@@ -150,10 +151,14 @@ Doxygen. Unrecognized commands are treated as normal text.
Structural indicators
\htmlonly --- </center>\endhtmlonly</h2>
-\subsection cmdaddtogroup \addtogroup <name>
+\subsection cmdaddtogroup \addtogroup <name> [(title)]
\addindex \addtogroup
- Add extra documentation to a group \<name\> that was previously defined
- using \\defgroup. This command can also be used to add a number of
+ Defines a group just like \ref cmddefgroup "\\defgroup", but in contrast to
+ that command using the same \<name\> more than once will not result in a warning,
+ but rather one group with a merged documentation and the first title found in
+ any of the commands.
+
+ The title is optional, so this command can also be used to add a number of
entities to an existing group using \@{ and \@} like this:
\verbatim
@@ -177,7 +182,8 @@ Doxygen. Unrecognized commands are treated as normal text.
/*! @} */
\endverbatim
- See also \ref cmddefgroup "\\defgroup" and \ref cmdingroup "\\ingroup".
+ \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", \ref cmdingroup "\\ingroup" and
+ \ref cmdweakgroup "\\weakgroup".
\subsection cmdclass \class <name> [<header-file>] [<header-name>]
@@ -225,9 +231,10 @@ Doxygen. Unrecognized commands are treated as normal text.
categories. You can also use groups as members of other groups,
thus building a hierarchy of groups.
- The \<name\> argument should an single word identifier.
+ The \<name\> argument should be a single word identifier.
- \sa section \ref cmdingroup "\\ingroup"
+ \sa page \ref grouping "Grouping", sections \ref cmdingroup "\\ingroup", \ref cmdaddtogroup "\\addtogroup",
+ \ref cmdweakgroup "\\weakgroup".
<hr>
@@ -348,7 +355,8 @@ Doxygen. Unrecognized commands are treated as normal text.
class, file or namespace, then it will be added to the group or
groups identified by \<groupname\>.
- \sa section \ref cmddefgroup "\\defgroup".
+ \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup",
+ \ref cmdaddtogroup "\\addtogroup" and \ref cmdweakgroup "\\weakgroup"
<hr>
\subsection cmdinterface \interface
@@ -556,6 +564,15 @@ Public/Protected/Private/... section.
\sa section \ref cmdfn "\\fn" and \ref cmdtypedef "\\typedef".
<hr>
+\subsection cmdweakgroup \weakgroup <name> [(title)]
+ \addindex \addtogroup
+ Can be used exactly like \ref cmdaddtogroup "\\addtogroup", but has
+ a lower priority when it comes to resolving conflicting grouping
+ definitions.
+
+ \sa page \ref grouping "Grouping" and \ref cmdaddtogroup "\\addtogroup".
+
+<hr>
<h2>\htmlonly <center> --- \endhtmlonly
Section indicators
diff --git a/doc/config.doc b/doc/config.doc
index b41c9af..f5d1f1e 100644
--- a/doc/config.doc
+++ b/doc/config.doc
@@ -142,6 +142,7 @@ followed by the descriptions of the tags grouped by category.
<li> \refitem cfg_latex_output LATEX_OUTPUT
<li> \refitem cfg_macro_expansion MACRO_EXPANSION
<li> \refitem cfg_man_extension MAN_EXTENSION
+<li> \refitem cfg_man_links MAN_LINKS
<li> \refitem cfg_man_output MAN_OUTPUT
<li> \refitem cfg_max_dot_graph_height MAX_DOT_GRAPH_HEIGHT
<li> \refitem cfg_max_dot_graph_width MAX_DOT_GRAPH_WIDTH
@@ -997,6 +998,16 @@ EXTRA_PACKAGES = times
\addindex MAX_EXTENSION
The \c MAN_EXTENSION tag determines the extension that is added to
the generated man pages (default is the subroutine's section .3)
+
+\anchor cfg_man_links
+<dt>\c MAN_LINKS <dd>
+ \addindex MAN_LINKS
+ If the \c MAN_LINKS tag is set to \c YES and Doxygen generates man output,
+ then it will generate one additional man file for each entity documented in
+ the real man page(s). These additional files only source the real man page,
+ but without them the man command would be unable to find the correct page.
+ The default is \c NO.
+
</dl>
\subsection config_prepro Preprocessor related options
@@ -1138,22 +1149,22 @@ TAGFILES = file1=loc1 "file2 = loc2" ... </pre>
\anchor cfg_include_graph
<dt>\c INCLUDE_GRAPH <dd>
\addindex INCLUDE_GRAPH
- If the \c ENABLE_PREPROCESSING, \c INCLUDE_GRAPH, and \c HAVE_DOT tags are
- set to \c YES then doxygen will generate a graph for each documented file
+ If the \c ENABLE_PREPROCESSING, \c SEARCH_INCLUDES, \c INCLUDE_GRAPH, and \c HAVE_DOT
+ tags are set to \c YES then doxygen will generate a graph for each documented file
showing the direct and indirect include dependencies of the file with other
documented files.
\anchor cfg_included_by_graph
<dt>\c INCLUDED_BY_GRAPH <dd>
\addindex INCLUDED_BY_GRAPH
- If the \c ENABLE_PREPROCESSING, \c INCLUDED_BY_GRAPH, and \c HAVE_DOT tags are
- set to \c YES then doxygen will generate a graph for each documented header
- file showing the documented files that directly or indirectly include this
- file.
+ If the \c ENABLE_PREPROCESSING, \c SEARCH_INCLUDES, \c INCLUDED_BY_GRAPH, and
+ \c HAVE_DOT tags are set to \c YES then doxygen will generate a graph for each
+ documented header file showing the documented files that directly or indirectly
+ include this file.
\anchor cfg_graphical_hierarchy
<dt>\c GRAPHICAL_HIERARCHY <dd>
- \addindex GRAPHICAL_HIERATCHY
+ \addindex GRAPHICAL_HIERARCHY
If the \c GRAPHICAL_HIERARCHY and \c HAVE_DOT tags are set to \c YES then
doxygen will graphical hierarchy of all classes instead of a textual one.
diff --git a/doc/faq.doc b/doc/faq.doc
index 38d553a..7b4894b 100644
--- a/doc/faq.doc
+++ b/doc/faq.doc
@@ -17,7 +17,7 @@
/*! \page faq Frequently Asked Questions
<ol>
-<li><b>How do get information on the index page in HTML?</b>
+<li><b>How to get information on the index page in HTML?</b>
<p>
You should use the \\mainpage command inside a comment block like this:
\verbatim
diff --git a/doc/grouping.doc b/doc/grouping.doc
index 71a8e37..ae80ae8 100644
--- a/doc/grouping.doc
+++ b/doc/grouping.doc
@@ -34,6 +34,7 @@ command in a special comment block. The first argument of the command
is a label that should uniquely identify the group. You can make an
entity a member of a specific group by putting
a \ref cmdingroup "\\ingroup" command inside its documentation block.
+The second argument is the title of the group.
To avoid putting \ref cmdingroup "\\ingroup" commands in the documentation
of each member you can also group members together by the
@@ -44,11 +45,75 @@ documentation block.
Groups can also be nested using these grouping markers.
+You will get an error message when you use the same group label more than once.
+If you don't want doxygen to enforce
+unique labels, then you can use \ref cmdaddtogroup "\\addtogroup" instead of
+\ref cmddefgroup "\\defgroup". It can be used exactly like \ref cmddefgroup "\\defgroup",
+but when the group has been defined already, then it silently merges the existing documentation
+with the new one.
+The title of the group is optional for this command, so you can use
+\verbatim
+/** \addtogroup <label> */
+/*\@{*/
+/*\@}*/
+\endverbatim
+to add members to a group that is defined in more detail elsewhere.
+
Note that compound entities (like classes, files and namespaces) can
be put into multiple groups, but members (like variable, functions, typedefs
and enums) can only be a member of one group
(this restriction is to avoid ambiguous linking targets).
+Doxygen will put members into that group where the grouping definition had
+the highest priority: f.i. \ref cmdingroup "\\ingroup" overrides any automatic
+grouping definition via <code>\@{</code> <code>\@}</code>. Conflicting grouping
+definitions with the same priority trigger a warning, unless one definition
+was for a member without any explicit documentation. The following example
+puts VarInA into group A and silently resolves the conflict for IntegerVariable by
+putting it into group IntVariables, because the second instance of IntegerVariable
+is undocumented:
+
+\verbatim
+
+/**
+ * \ingroup A
+ */
+extern int VarInA;
+
+/**
+ * \defgroup IntVariables Global integer variables
+ */
+/*@{*/
+
+/** an integer variable */
+extern int IntegerVariable;
+
+/*@}*/
+
+....
+
+/**
+ * \defgroup Variables Global variables
+ */
+/*@{*/
+
+/** a variable in group A */
+int VarInA;
+
+int IntegerVariable;
+
+/*@}*/
+\endverbatim
+
+The priorities of grouping definitions are (from highest to lowest):
+\ref cmdingroup "\\ingroup", \ref cmddefgroup "\\defgroup",
+\ref cmdaddtogroup "\\addtogroup", \ref cmdweakgroup "\\weakgroup".
+The last command is exactly like \ref cmdaddtogroup "\\addtogroup"
+with a lower priority. It was added to allow "lazy" grouping
+definitions: you can use commands with a higher priority in your .h
+files to define the hierarchy and \ref cmdweakgroup "\\weakgroup"
+in .c files without having to duplicate the hierarchy exactly.
+
\par Example:
\verbinclude group.cpp
diff --git a/doc/install.doc b/doc/install.doc
index 70d625a..2a5a6e6 100644
--- a/doc/install.doc
+++ b/doc/install.doc
@@ -421,6 +421,10 @@ Here is what is required:
to produce PDF output instead of DVI, or the PDF can be produced
from PostScript using the utility <code>ps2pdf</code>.
+ If you want to use MikTeX then you need to download the
+ fancyhdr package separately. You can find it at:
+ ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/
+
<li>If you want to generate compressed HTML help
(see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the
config file, then you need the Microsoft HTML help workshop.
diff --git a/doc/language.tpl b/doc/language.tpl
index f7eb542..18c0b40 100644
--- a/doc/language.tpl
+++ b/doc/language.tpl
@@ -1,6 +1,6 @@
/******************************************************************************
- * <notice>This is the template for generating language.doc. Edit this file,
- * not the language.doc.</notice>
+ * <notice>This is the template for generating language.doc.
+ * Edit manually this file, not the language.doc!</notice>
*
*
* Copyright (C) 1997-2001 by Dimitri van Heesch.
@@ -23,7 +23,8 @@ 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):
+Currently (version $version), $numlang languages
+are supported (sorted alphabetically):
$languages.
The table of information related to the supported languages follows.
@@ -33,7 +34,6 @@ 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
diff --git a/doc/maintainers.txt b/doc/maintainers.txt
index 16b9e46..bddd9d4 100644
--- a/doc/maintainers.txt
+++ b/doc/maintainers.txt
@@ -15,7 +15,7 @@ Petr P&rcaron;ikryl: prikrylp@skil.cz
Vlastimil Havran: havran@fel.cvut.cz
Danish
-Erik Søe Sørensen: erik@mail.nu
+Erik S&oslash;e S&oslash;rensen: erik@mail.nu
Dutch
Dimitri van Heesch: dimitri@stack.nl
diff --git a/doc/translator.bat b/doc/translator.bat
index fc12581..3dccb13 100644
--- a/doc/translator.bat
+++ b/doc/translator.bat
@@ -1,4 +1 @@
-:start
-call perl -w translator.pl
-pause
-goto start \ No newline at end of file
+@call perl -w translator.pl
diff --git a/doc/translator.pl b/doc/translator.pl
index f5b889e..375fe2b 100644
--- a/doc/translator.pl
+++ b/doc/translator.pl
@@ -4,6 +4,8 @@
# This is a Perl script for Doxygen developers.
# Its main purpose is to extract the information from sources
# related to internationalization (the translator classes).
+# It uses the information to generate documentation (language.doc,
+# translator_report.txt) from templates (language.tpl, maintainers.txt).
#
# Petr Prikryl (prikrylp@skil.cz)
# History:
@@ -11,10 +13,26 @@
# 2001/04/27
# - First version of the script.
#
-# 2002/05/02
+# 2001/05/02
# - Update to accept updateNeededMessage() in the Translator class.
# - First version that generates doc/language.doc.
#
+# 2001/05/07
+# - Environment variable $doxygenrootdir now points to the
+# Doxygen's root directory.
+#
+# 2001/05/11
+# - Updated to reflect using TranslatorAdapterCVS as the base
+# class for "almost up-to-date" translators.
+# - $doxygenrootdir and other global variables for storing
+# directories determined from DOXYGEN_DOCDIR environment
+# variable. The change was done because the DOXYGEN_DOCDIR
+# was already used before.
+# - $version mark can be used in the language.tpl template.
+#
+# 2001/05/18
+# - Character entity &oslash; recognized in maintainers.txt.
+#
################################################################
require 5.005;
@@ -23,14 +41,21 @@ use Carp;
# Global variables
#
-my $doxygenrootdir = "..";
-my $srcdir = "$doxygenrootdir/src";
-my $docdir = "$doxygenrootdir/doc";
+my $doxygenrootdir = 'directory set at the beginning of the body';
+my $srcdir = 'directory set at the beginning of the body';
+my $docdir = 'directory set at the beginning of the body';
+
+my $doxversion = 'set at the beginning of the body';
# Names of the output files.
#
-my $ftxt = "translator_report.txt";
-my $fdoc = "language.doc";
+my $ftranslatortxt = "translator_report.txt";
+my $flangdoc = "language.doc";
+
+# Names of the template files and other intput files.
+#
+my $flangtpl = "language.tpl"; # template for language.doc
+my $fmaintainers = "maintainers.txt"; # database of local lang. maintainers
################################################################
@@ -199,7 +224,7 @@ sub GetInfoFrom ##{{{
################################################################
# GenerateLanguageDoc takes document templates and code sources
-# generates the content as expected in the language.doc file (the
+# generates the content as expected in the $flangdoc file (the
# part of the Doxygen documentation), and returns the result as a
# string.
#
@@ -250,7 +275,8 @@ xxxTABLE_FOOTxxx
\latexonly
\begin{tabular}{|l|l|l|l|}
\hline
- {\bf Language} & {\bf Maintainer} & {Contact address} & {Status} \\
+ {\bf Language} & {\bf Maintainer} & {\bf Contact address} & {\bf Status} \\
+ \hline
xxxTABLE_HEADxxx
my $latexTableRow = <<'xxxTABLE_ROWxxx';
@@ -267,7 +293,7 @@ xxxTABLE_FOOTxxx
# Read the template of the documentation, and join the content
# to a single string. #{{{
#
- my $fin = "$docdir/language.tpl";
+ my $fin = "$docdir/$flangtpl";
open(FIN, "< $fin") or die "\nError when open < $fin: $!";
my @content = <FIN>;
close FIN;
@@ -304,7 +330,7 @@ xxxTABLE_FOOTxxx
# Read the information related to maintainers into the
# string using suitable separators -- one line, one language. #{{{
#
- $fin = "$docdir/maintainers.txt";
+ $fin = "$docdir/$fmaintainers";
open(FIN, "< $fin") or die "\nError when open < $fin: $!";
my @maintainers = <FIN>;
close FIN;
@@ -374,7 +400,7 @@ xxxTABLE_FOOTxxx
foreach my $lang (sort keys %language) {
# Read the line with info for the language and separate
- # the information of status. #{{{
+ # the status. #{{{
#
my @list = split(/<msep\/>/, $language{$lang});
my $status = shift @list;
@@ -382,6 +408,10 @@ xxxTABLE_FOOTxxx
my $i = $status =~ s{^Translator$}{up-to-date};
if ($i == 0) {
+ $i = $status =~ s{^TranslatorAdapterCVS}{almost up-to-date};
+ }
+
+ if ($i == 0) {
$i = $status =~ s{^TranslatorAdapter_(\d)_(\d)_(\d)}
{$1.$2.$3}x;
}
@@ -479,9 +509,9 @@ xxxTABLE_FOOTxxx
##}}}
# 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. #{{{
+ # template by the contatenation of the tables and the notice
+ # about $ftranslatortxt. Add NOSPAM to email addresses in the
+ # HTML table. Replace the special character sequences. #{{{
#
$tableHTML .= $htmlTableFoot;
$tableLATEX .= $latexTableFoot;
@@ -493,16 +523,26 @@ xxxTABLE_FOOTxxx
$tableLATEX =~ s/&aacute;/\\'{a}/sg;
$tableLATEX =~ s/&auml;/\\"{a}/sg;
$tableLATEX =~ s/&ouml;/\\"{o}/sg;
+ $tableLATEX =~ s/&oslash;/\\o{}/sg;
$tableLATEX =~ s/_/\\_/sg;
- $output =~ s{\$information_table}{$tableHTML$tableLATEX};
+ my $notice = "\nHave a look at <a href=\"../doc/$ftranslatortxt\"\n>"
+ . "<code>doxygen/doc/$ftranslatortxt</code></a> "
+ . "for more details.";
+
+ $output =~ s{\$information_table}{$tableHTML$tableLATEX$notice};
+
+ $output =~ s{\$version}{$doxversion};
+
##}}}
# 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;
+{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.
@@ -516,6 +556,24 @@ xxxTABLE_FOOTxxx
# Body
#
{
+ # Set the content of global variables using the environment
+ # variables. #{{{
+ #
+ $docdir = (defined $ENV{'DOXYGEN_DOCDIR'})
+ ? $ENV{'DOXYGEN_DOCDIR'} : '.';
+
+ $docdir =~ s{\\}{/}g;
+ $docdir =~ s{/$}{};
+
+ $doxygenrootdir = ($docdir eq '.') ? '..' : $docdir;
+ $doxygenrootdir =~ s{/doc$}{};
+
+ $srcdir = "$doxygenrootdir/src";
+
+ $doxversion = (defined $ENV{'VERSION'}) ? $ENV{'VERSION'} : 'unknown';
+
+ ##}}}
+
# The translator base class must be present. Exit otherwise. #{{{
#
if (!-f "$srcdir/translator.h")
@@ -635,7 +693,7 @@ xxxTABLE_FOOTxxx
# Generate the textual output file.
#
- my $fout = "$docdir/$ftxt";
+ my $fout = "$docdir/$ftranslatortxt";
# Open it first.
#
@@ -655,24 +713,37 @@ xxxTABLE_FOOTxxx
# If there are up-to-date translators, list them. #{{{
#
- my @list = sort grep { $cb{$_} =~ m/^Translator$/ } keys %cb;
+ my @list = sort grep { $cb{$_} =~ m/^Translator(AdapterCVS)?$/ } 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";
+ . "If the translator\n"
+ . "derives from TranslatorAdapterCVS, it is considered "
+ . "to be almost up-to-date.\n"
+ . "In other words, it is newer than the last official "
+ . "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";
- foreach (@list) { print FOUT " $_\n"; }
+ foreach (@list) {
+ print FOUT " $_";
+
+ # For almost up-to-date translators, show also the base class.
+ #
+ if ($cb{$_} ne 'Translator') { print FOUT "\t($cb{$_})"; }
+
+ print FOUT "\n";
+ }
}
##}}}
# If there are obsolete translators, list them. #{{{
#
- @list = sort grep { $cb{$_} =~ m/^TranslatorAdapter/ } keys %cb;
+ @list = sort grep { $cb{$_} =~ m/^TranslatorAdapter_/ } keys %cb;
if (@list) {
print FOUT "\n" .'-' x 70 . "\n";
@@ -732,7 +803,7 @@ xxxTABLE_FOOTxxx
# Generate the language.doc file.
#
- $fout = "$docdir/$fdoc";
+ $fout = "$docdir/$flangdoc";
# Open it first for the output.
#
generated by cgit v0.12 at 2024-11-05 07:16:24 (GMT)