summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Doxyfile4
-rw-r--r--doc/commands.doc4
-rw-r--r--doc/config.doc18
-rw-r--r--doc/doxygen_manual.tex2
-rw-r--r--doc/doxysearch_usage.doc15
-rw-r--r--doc/faq.doc49
-rw-r--r--doc/index.doc26
-rw-r--r--doc/language.doc264
-rw-r--r--doc/starting.doc118
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
*/