diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 4 | ||||
| -rw-r--r-- | doc/commands.doc | 4 | ||||
| -rw-r--r-- | doc/config.doc | 18 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 2 | ||||
| -rw-r--r-- | doc/doxysearch_usage.doc | 15 | ||||
| -rw-r--r-- | doc/faq.doc | 49 | ||||
| -rw-r--r-- | doc/index.doc | 26 | ||||
| -rw-r--r-- | doc/language.doc | 264 | ||||
| -rw-r--r-- | doc/starting.doc | 118 |
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 \ä for an a with an umlaut (i.e. ä). + 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 */ |