mods for doxygen-0.49-990728

9 files changed, 490 insertions, 10 deletions

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 79cbb31..5891572 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -10,11 +10,11 @@ EXTRACT_PRIVATE  = NO
 GENERATE_LATEX   = YES
 GENERATE_HTML    = YES
 ENABLE_PREPROCESSING = NO
-INPUT            = index.doc install.doc starting.doc trouble.doc \
+INPUT            = index.doc install.doc starting.doc faq.doc trouble.doc \
 		   history.doc features.doc \
 		   doxygen_usage.doc doxytag_usage.doc doxysearch_usage.doc \
                    installdox_usage.doc autolink.doc \
-		   config.doc commands.doc htmlcmds.doc 
+		   config.doc commands.doc htmlcmds.doc language.doc
 FILE_PATTERNS    = *.cpp *.h *.doc
 EXAMPLE_PATH     = ../examples
 RECURSIVE        = NO
diff --git a/doc/commands.doc b/doc/commands.doc
index 48f5c53..5965aaf 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -183,6 +183,7 @@ Doxygen. Unrecognized commands are treated as normal text.
   \sa section \ref cmdcode "\\code"
  
 <hr>
+
 \subsection cmdenum \enum <name>
 
   \addindex \enum
@@ -664,6 +665,7 @@ Doxygen. Unrecognized commands are treated as normal text.
 
   \sa 
     Section \ref cmdpage "\\page" for an example of the \\cmdsection command.
+
 <hr>
 \subsection cmdsubsection \subsection <subsection-name> (subsection title)
 
@@ -677,6 +679,7 @@ Doxygen. Unrecognized commands are treated as normal text.
 
   \sa
    Section \ref cmdpage "\\page" for an example of the \\cmdsubsection command.
+
 <hr>
 
 <h2>\htmlonly <center> --- \endhtmlonly 
@@ -1054,7 +1057,6 @@ Doxygen. Unrecognized commands are treated as normal text.
   character has to be escaped because it has a special meaning in HTML.
 
 <hr>
-
 <h2>\htmlonly <center> --- \endhtmlonly 
     Commands included for JavaDoc compatibility
     \htmlonly --- </center>\endhtmlonly</h2>
diff --git a/doc/config.doc b/doc/config.doc
index 481925c..2bf3dc7 100644
--- a/doc/config.doc
+++ b/doc/config.doc
@@ -63,6 +63,14 @@ Below is a list of tags that are recognized for each category.
  If a relative path is entered, it will be relative to the location 
  where doxygen was started. If left blank the current directory will be used.
 
+<dt>\c OUTPUT_LANGUAGE <dd>
+ \addindex OUTPUT_LANGUAGE
+ The \c OUTPUT_LANGUAGE tag is used to specify the language in which all
+ documentation generated by doxygen is written. Doxygen will use this
+ information to generate all constant output in the proper language.
+ The default language is English, other supported languages are:
+ Dutch, French, Italian, Czech, Swedish, German and Japanese.
+
 <dt>\c QUIET <dd>
  \addindex QUIET
  The \c QUIET tag can be used to turn on/off the messages that are generated
@@ -268,6 +276,11 @@ Below is a list of tags that are recognized for each category.
 \endverbatim
  If the tag is left blank doxygen will generate a 
  standard header. 
+
+ The following commands have a special meaning inside the header:
+ <code>\$title</code>, <code>\$datetime</code>, <code>\$date</code>. 
+ Doxygen will replace them by respectively 
+ the title of the page, the current date and time, or only the current date. 
    
 <dt>\c HTML_FOOTER <dd>
  \addindex HTML_FOOTER
@@ -280,6 +293,11 @@ Below is a list of tags that are recognized for each category.
 \endverbatim
  If the tag is left blank doxygen will generate a standard footer.
 
+ The following commands have a special meaning inside the footer:
+ <code>\$title</code>, <code>\$datetime</code>, <code>\$date</code>. 
+ Doxygen will replace them by respectively 
+ the title of the page, the current date and time, or only the current date. 
+
 </dl>
 
 \subsection latex_output LaTeX related options
diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex
index 8d28a55..bb8d599 100644
--- a/doc/doxygen_manual.tex
+++ b/doc/doxygen_manual.tex
@@ -26,6 +26,7 @@ Written by Dimitri van Heesch\\[2ex]
 \part{User Manual}
 \input{install}
 \input{starting}
+\input{faq}
 \input{trouble}
 \part{Reference Manual}
 \input{features}
@@ -38,5 +39,6 @@ Written by Dimitri van Heesch\\[2ex]
 \input{config}
 \input{commands}
 \input{htmlcmds}
+\input{langhowto}
 \printindex
 \end{document}
diff --git a/doc/doxysearch_usage.doc b/doc/doxysearch_usage.doc
index a4a3e96..e3b1657 100644
--- a/doc/doxysearch_usage.doc
+++ b/doc/doxysearch_usage.doc
@@ -67,7 +67,7 @@ follow these steps:
     documentation. Apart from the documentation, Doxygen will create the 
     following files:
     <ul>
-    <li>A small CGI script. the name of the script is determined by the
+    <li>A small shell script. the name of the script is determined by the
         \c CGI_NAME tag in the configuration file.
         The script is a small wrapper that calls \c doxysearch with
         the correct parameters. Using this script allows multiple 
@@ -80,6 +80,16 @@ follow these steps:
     <li>\c search.gif: this is the image that is used for the search button.
     </ul>
 
+    \par Notice:
+      On the Windows platform Unix shell scripts cannot be used. 
+      In fact the HTTP daemon that I tried (apache for Windows) only 
+      recognized <code>.cgi</code> files that were renamed 
+      executables (so DOS batch files do not seem to work either). Therefore,
+      on Windows a small C program will generated by doxygen.
+      You should compile and link the program with your favourite
+      compiler and change the extension of the executable from 
+      <code>.exe</code> to <code>.cgi</code>.
+
 <li>Copy (or move) the CGI script to the directory where the CGI binaries
     are located.
     This is usually a special directory on your system or in your
@@ -112,7 +122,8 @@ This can be done by carefully following these steps:
 <li>Goto the html directory of the Qt-distribution:
     <pre>cd $QTDIR/html</pre>
 <li>Generate the search index by typing:
-    <pre>doxytag -s search.idx *.html</pre>
+    <pre>doxytag -s search.idx</pre>
+    in the directory where the HTML files are located.
     This will parse all files and build a search index.
     Apart from the file <code>search.idx</code> two other files
     will be generated: <code>search.gif</code> and <code>search.cgi</code>
diff --git a/doc/faq.doc b/doc/faq.doc
new file mode 100644
index 0000000..c730289
--- /dev/null
+++ b/doc/faq.doc
@@ -0,0 +1,49 @@
+/******************************************************************************
+ *
+ * $Id$
+ *
+ * Copyright (C) 1997-1999 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.
+ *
+ * All output generated with Doxygen is not covered by this license.
+ *
+ */
+/*! \page faq Frequently Asked Questions
+
+<ol>
+<li><b>How do get information on the index page in HTML?</b>
+<p>
+There is no real support for title pages at the moment. But you can
+override the default index page, by using the following comment block:
+\verbatim
+/*! \page index My Personal Index Page
+ *
+ * This is my index personal index page.
+ */
+\endverbatim
+
+<li><b>How can I avoid that some code fragment is parsed by Doxyen?</b>
+<p>
+You can use Doxygen's preprocessor for this: 
+If you put
+\verbatim
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
+ /* code that must be skipped by Doxygen */
+
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+\endverbatim
+around the blocks that should be hidden and put:
+\verbatim
+  PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
+\endverbatim
+in the config file then all blocks should be skipped by Doxygen as long
+as <code>PREPROCESSING = YES</code>.
+</ol>
+*/
+
diff --git a/doc/index.doc b/doc/index.doc
index f60eec9..7db1d27 100644
--- a/doc/index.doc
+++ b/doc/index.doc
@@ -58,10 +58,12 @@ sections.
 
 The first part forms a user manual:
 <ul>
-<li>Section \ref install discusses how to download, compile and install
+<li>Section \ref install discusses how to 
+      <a href="http://www.stack.nl/~dimitri/doxygen/download.html">download</a>, compile and install
                      doxygen for your platform.
 <li>Section \ref starting tells you how to generate your first piece of 
                      documentation quickly. 
+<li>Section \ref faq gives answers to frequently asked questions. 
 <li>Section \ref trouble tells you what to do when you have problems.
 </ul>
 
@@ -84,8 +86,23 @@ The second part forms a reference manual:
               used within the documentation.
 <li>Section \ref htmlcmds shows an overview of the HTML commands that
               can be used within the documentation.
+<li>Section \ref langhowto explains how to add support for new
+              output languages.
 </ul>
 
+
+<h2>Projects using doxygen</h2>
+
+I have compiled a small 
+\htmlonly
+<a href="http://www.stack.nl/~dimitri/doxygen/projects.html">list of projects</a> 
+that use doxygen
+\endhtmlonly
+\latexonly
+list of projects that use doxygen (see {\tt http://www.stack.nl/$\sim$dimitri/doxygen/projects.html})
+\endlatexonly
+If you know other projects, let me know and I'll add them. 
+
 <h2>Acknowledgements</h2>
 \addindex acknowledgements
 Thanks go to:
@@ -156,9 +173,10 @@ Olaf Meeuwissen,
 Feiyi Wang,
 Robert J. Clark,
 Matthias Baas,
-Walter Mueller, and
-William van Dieten
-    for suggestions, patches and bug reports.
+Walter Mueller, 
+William van Dieten, and
+Joshua Jensen and
+many others for suggestions, patches and bug reports.
 </ul>
 */
 
diff --git a/doc/language.doc b/doc/language.doc
new file mode 100644
index 0000000..f05dce3
--- /dev/null
+++ b/doc/language.doc
@@ -0,0 +1,264 @@
+/******************************************************************************
+ *
+ * $Id$
+ *
+ * Copyright (C) 1997-1999 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.
+ *
+ * All output generated with Doxygen is not covered 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, supported languages are English, French, Czech, Dutch, 
+Swedish, Italian, German and Japanese. A number
+of people have volunteered to add support for other languages as well.
+Here is a list of the languages and their current maintainers:
+<p>
+
+\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></b></TD>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+	German
+      </TD>  
+      <TD>
+        Jens Breitenstein
+      </TD>
+      <TD>
+        <a href="mailto:Jens.Breitenstein@tlc.de">
+			Jens.Breitenstein@tlc.de</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        French
+      </TD>  
+      <TD>
+        Christophe Bordeux
+      </TD>
+      <TD>
+        <a href="mailto:bordeux@lig.di.epfl.ch">
+                          bordeux@lig.di.epfl.ch</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Swedish
+      </TD> 
+      <TD>
+        Samuel Hägglund<BR>
+        XeT Erixon
+      </TD>
+      <TD>
+        <a href="mailto:sahag96@nts.mh.se">
+	          sahag96@nts.mh.se</a><br>
+        <a href="mailto:xet@hem.passagen.se">
+		  xet@hem.passagen.se</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Czech
+      </TD>   
+      <TD>
+        Vlastimil Havran
+      </TD>
+      <TD>
+        <a href="mailto:havran@fel.cvut.cz">
+                        havran@fel.cvut.cz</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Romanian
+      </TD>
+      <TD>
+        Ionutz Borcoman
+      </TD>
+      <TD>
+        <a href="mailto:borco@borco-ei.eng.hokudai.ac.jp">
+	                borco@borco-ei.eng.hokudai.ac.jp</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Polish
+      </TD>
+      <TD>
+        Piotr Piatkowski
+      </TD>
+      <TD>
+        <a href="mailto:kompas@ceti.com.pl">
+                        kompas@ceti.com.pl</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Italian
+      </TD>
+      <TD>
+        Ahmed Aldo Faisal<br>
+        Alessandro Falappa    
+      </TD>
+      <TD>
+        <a href="mailto:aaf23@cam.ac.uk">
+                        aaf23@cam.ac.uk</a><br>
+        <a href="mailto:a.falappa@flashnet.it">
+                        a.falappa@flashnet.it</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Japanese
+      </TD>
+      <TD>
+        Kenji Nagamatsu
+      </TD>
+      <TD>
+        <a href="mailto:naga@joyful.club.ne.jp">
+                        naga@joyful.club.ne.jp</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Spanish
+      </TD>
+      <TD>
+        Francisco Oltra Thennet 
+      </TD>
+      <TD>
+        <a href="mailto:foltra@puc.cl">
+                        foltra@puc.cl</a>
+      </TD>
+  </TR>
+  <TR BGCOLOR="#ffffff">
+      <TD>
+        Dutch
+      </TD>  
+      <TD>
+        Dimitri van Heesch
+      </TD>
+      <TD>
+        <a href="mailto:dimitri@stack.nl">
+	                dimitri@stack.nl</a>
+      </TD>
+  </TR>
+  </TABLE>
+</TD>
+</TR>
+</TABLE>
+\endhtmlonly
+\latexonly
+\begin{tabular}{|l|l|l|}
+  \hline
+  {\bf Language} & {\bf Maintainer} & {Contact address} \\
+  \hline
+  German  & Jens Breitenstein & {\tt Jens.Breitenstein@tlc.de} \\
+  \hline
+  French  & Christophe Bordeux & {\tt bordeux@lig.di.epfl.ch} \\
+  \hline
+  Swedish & Samuel Hägglund & {\tt sahag96@nts.mh.se} \\
+          & XeT Erixon      & {\tt xet@hem.passagen.se} \\
+  \hline
+  Czech   & Vlastimil Havran & {\tt havran@fel.cvut.cz} \\
+  \hline
+  Romanian & Ionutz Borcoman & {\tt borco@borco-ei.eng.hokudai.ac.jp} \\
+  \hline
+  Polish & Piotr Piatkowski & {\tt kompas@ceti.com.pl} \\
+  \hline
+  Italian & Ahmed Aldo Faisal & {\tt aaf23@cam.ac.uk} \\
+          & Alessandro Falappa & {\tt a.falappa@flashnet.it} \\
+  \hline
+  Japanese & Kenji Nagamatsu & {\tt naga@joyful.club.ne.jp} \\
+  \hline
+  Spanish & Francisco Oltra Thennet & {\tt foltra@puc.cl} \\
+  \hline
+  Dutch & Dimitri van Heesch & {\tt dimitri@stack.nl} \\
+  \hline
+\end{tabular}
+\endlatexonly
+<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>Language HOWTO</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_nl.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 doxygen.pro 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_NL_H</code> to <code>TRANSLATOR_XX_H</code> twice.
+   <li>Rename TranslatorDutch to TranslatorYourLanguage 
+   <li>In the member <code>latexBabelPackage()</code> change "dutch" into the name of the
+     latex package that adds support for your language. 
+   <li>Edit all the strings that are returned by the members that start
+     with tr. 
+     Look at the corresponding member in translator.h for the english text 
+     that is returned and translate that into your language. 
+     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.
+     <li>  Use html codes like \&auml; for an a with an umlaut (i.e. &auml;).
+           See the HTML specification for the codes.
+     </ul>
+   </ul>
+<li>Recompile everything (do this from the root of the distribution, 
+    because the Makefile.dox* have to be regenerated!)
+<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> or a <code>diff -u</code> of the changes 
+    to me so I can add it to doxygen.
+</ol>
+*/
+
diff --git a/doc/starting.doc b/doc/starting.doc
index 1d3cbcd..78f9309 100644
--- a/doc/starting.doc
+++ b/doc/starting.doc
@@ -397,6 +397,122 @@ from typos in formulas. It may have to be necessary to remove the
 file formula.repository that is written in the html directory to 
 a rid of an incorrect formula
 
+\subsection preprocessing Preprocessing
+
+Source files that are used as input to doxygen can be parsed by doxygen's
+build-in C-preprocessor.
+
+By default doxygen does only partial preprocessing. That is, it 
+evaluates conditional compilation statements (like \#if) and 
+evaluates macro definitions, but is does not perform macro expansion.
+
+So if you have the following code fragment
+\verbatim
+#define VERSION 200
+#define CONST_STRING const char *
+
+#if VERSION >= 200
+  static CONST_STRING version = "2.xx";
+#else
+  static CONST_STRING version = "1.xx";
+#endif
+\endverbatim
+
+Then by default doxygen will feed the following to its parser:
+
+\verbatim
+#define VERSION
+#define CONST_STRING
+
+  static CONST_STRING version = "1.xx";
+\endverbatim
+
+You can disable all preprocessing by setting \c ENABLE_PREPROCESSING to \c 
+NO in the configuation file. In the case above doxygen will then read
+both statements!
+
+In case you want to expand the \c CONST_STRING macro, you should set the
+\c MACRO_EXPANSION tag in the config file to \c YES. Then the result 
+after preprocessing becomes:
+
+\verbatim
+#define VERSION
+#define CONST_STRING
+
+  static const char * version = "1.xx";
+\endverbatim
+
+Notice that doxygen will now expand \e all macro definitions 
+(recursively if needed). This is often too much, therefore doxygen also 
+allows you to expand only those defines that you explicitly 
+specify. For this you have to set the \c EXPAND_ONLY_PREDEF tag to \c YES
+and specify the macro definitions after the \c PREDEFINED tag.  
+
+As an example, suppose you have the following obfusciated code fragment
+of an abstract base class called \c IUnknown:
+
+\verbatim
+/*! A reference to an IID */
+#ifdef __cplusplus
+#define REFIID const IID &
+#else
+#define REFIID const IID *
+#endif
+
+/*! The IUnknown interface */
+DECLARE_INTERFACE(IUnknown)
+{
+  MEMBER(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE;
+  MEMBER(ULONG,AddRef) (THIS) PURE;
+  MEMBER(ULONG,Release) (THIS) PURE;
+};
+\endverbatim
+
+without macro expansion doxygen will get confused, but we may not want to 
+expand the REFIID macro, because it is documented and the user that reads 
+the documentation should use it when implementing the interface.
+
+By setting the following in the config file:
+
+\verbatim
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION      = YES
+EXPAND_ONLY_PREDEF   = YES
+PREDEFINED           = "DECLARE_INTERFACE(name)=class name" \
+                       "MEMBER(result,name)=virtual result name" \
+                       "PURE= = 0" \
+                       THIS_= \
+                       THIS= \
+		       __cplusplus
+\endverbatim
+
+we can make sure that the proper result is fed to doxygen's parser:
+\verbatim
+/*! A reference to an IID */
+#define REFIID
+
+/*! The IUnknown interface */
+class  IUnknown
+{
+  virtual  HRESULT   QueryInterface ( REFIID iid, void **ppv) = 0;
+  virtual  ULONG   AddRef () = 0;
+  virtual  ULONG   Release () = 0;
+};
+\endverbatim
+
+Notice that the \c PREDEFINED tag accepts function like macro definitions
+(like \c DECLARE_INTERFACE), normal macro substitutions (like \c PURE
+and \c THIS) and plain defines (like \c __cplusplus).
+
+Notice also that preprocessor definitions that are normally defined 
+automatically by the preprocessor (like \c __cplusplus), have to be defined 
+by hand with doxygen's parser (this is done because these defines
+are often platform/compiler specific).
+
+As you can see doxygen's preprocessor is quite powerful, but if you want
+even more flexibility you can always write an input filter and specify it on 
+the \c INPUT_FILTER flag.
+
 \subsection moreinfo More information
 
 \addindex QdbtTabular
@@ -405,7 +521,7 @@ the documentation of QdbtTabular</a> \latexonly
 ({\tt http://www.stack.nl/$\sim$dimitri/qdbttabular/html})\endlatexonly.
 \htmlonly
 I hope that was clear. If not, please let me know, so I can improve this document. If you have problems 
-take a look at the <a href="trouble.html">troubleshooting</a> section. 
+take a look at the <a href="faq.html">faq</a> and the <a href="trouble.html">troubleshooting</a> sections. 
 \endhtmlonly
 
 */