initial version

1 files changed, 553 insertions, 0 deletions

diff --git a/doc/config.doc b/doc/config.doc
new file mode 100644
index 0000000..0412634
--- /dev/null
+++ b/doc/config.doc
@@ -0,0 +1,553 @@
+/******************************************************************************
+ *
+ * $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 config
+
+\section config Configuration
+
+\subsection config_format Format
+
+A configuration file is a free-form ASCII text file with a structure that
+is similar to that of a Makefile. It is parsed by a 
+recursive-descent parser that is built into \c doxygen.
+The file may contain tabs and newlines for formatting purposes.
+The statements in the file are case-sensitive.
+Comments may be placed anywhere within the file (except within quotes).
+Comments begin with the \c # character and end at the end of the 
+line.
+
+The file essentially consists of a list of assignment statements.
+Each statement consists of a \c TAG_NAME written in capitals,
+followed by the \c = character and one or more values.
+Values are sequences of non-blanks. If the value should contain one or more
+blanks it must be surrounded by quotes ("...").
+Multiple lines can be concatenated by inserting a backslash (\\)
+as the last character of a line.
+Environment variables can expanded using the pattern \$(ENV_VARIABLE_NAME).
+
+The configuration options can be divided into several categories.
+Below is a list of tags that are recognized for each category.
+
+\subsection config_general General options
+<dl>
+
+<dt>\c PROJECT_NAME <dd>
+ \addindex PROJECT_NAME
+ The \c PROJECT_NAME tag is a single word (or a sequence of words
+ surrounded by double-quotes) that should identify the project for which the 
+ documentation is generated. This name is used in the title of most 
+ generated pages and in a few other places.
+
+<dt>\c PROJECT_NUMBER <dd>
+ \addindex PROJECT_NUMBER
+ The \c PROJECT_NUMBER tag can be used to enter a project or revision number.
+ This could be handy for archiving the generated documentation or
+ if some version control system is used.
+
+<dt>\c OUTPUT_DIRECTORY <dd> 
+ \addindex OUTPUT_DIRECTORY
+ The \c OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
+ path into which the generated HTML and Latex documentation will be written. 
+ 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 QUIET <dd>
+ \addindex QUIET
+ The \c QUIET tag can be used to turn on/off the messages that are generated
+ to standard output by doxygen. Possible values are \c YES and \c NO, 
+ where \c YES implies that the messages are off.
+ If left blank \c NO is used.
+
+<dt>\c WARNINGS <dd>
+ \addindex WARNINGS
+ The \c WARNINGS tag can be used to turn on/off the warning messages that are
+ generated to standard error by doxygen. Possible values are \c YES and \c NO, 
+ where \c YES implies that the warnings are on. If left blank \c NO is used.
+
+ \b Tip: Turn warnings on while writing the documentation.
+
+<dt>\c DISABLE_INDEX <dd>
+ \addindex DISABLE_INDEX
+ If you want full control over the layout of the generated HTML pages it
+ might be necessary to disable the index and replace it with your own.
+ The DISABLE_INDEX tag can be used to turn on/off the condensed index at
+ top of each page. A value of NO (the default) enables the index and the
+ value YES disables it.
+
+<dt>\c EXTRACT_ALL <dd>
+ \addindex EXTRACT_ALL
+ If the \c EXTRACT_ALL tag is set to \c YES all classes and functions will be
+ included in the documentation, even if no documentation was available.
+
+ \b Notice: This will also disable the warnings about undocumented members 
+ that are normally produced when \c WARNINGS is set to \c YES
+
+<dt>\c EXTRACT_PRIVATE <dd>
+ \addindex EXTRACT_PRIVATE
+ If the \c EXTRACT_PRIVATE tag is set to \c YES all
+ documentation for private members will be extracted as well.
+
+<dt>\c HIDE_UNDOC_MEMBERS <dd>
+ \addindex HIDE_UNDOC_MEMBERS
+ If the \c HIDE_UNDOC_MEMBERS tag is set to \c YES, Doxygen will hide all
+ undocumented members inside documented classes or files. 
+ If set to \c NO (the default) these members will be included in the
+ various overviews, but no documentation section is generated.
+
+<dt>\c HIDE_UNDOC_CLASSES <dd>
+ \addindex HIDE_UNDOC_CLASSES
+ If the \c HIDE_UNDOC_CLASSESS tag is set to \c YES, Doxygen will hide all
+ undocumented classes.
+ If set to \c NO (the default) these classes will be included in the
+ various overviews.
+
+<dt>\c BRIEF_MEMBER_DESC <dd>
+ \addindex BRIEF_MEMBER_DESC
+ If the \c BRIEF_MEMBER_DESC tag is set to \c YES (the default) Doxygen will
+ include brief member descriptions after the members that are listed in
+ the file and class documentation (similar to JavaDoc).
+ Set to NO to disable this.
+
+<dt>\c INTERNAL_DOCS <dd>
+ \addindex INTERNAL_DOCS
+ The \c INTERNAL_DOCS tag determines if documentation
+ that is typed after a \\internal command is included. If the tag is set
+ to \c NO (the default) then the documentation will be excluded.
+ Set it to \c YES to include the internal documentation.
+
+<dt>\c REPEAT_BRIEF <dd>
+ \addindex REPEAT_BRIEF
+ If the \c REPEAT_BRIEF tag is set to \c YES (the default) Doxygen will 
+ prepend the brief description of a member or function before the detailed 
+ description 
+
+ \par Notice: 
+ If both \c HIDE_UNDOC_MEMBERS and \c BRIEF_MEMBER_DESC are set to \c NO, the 
+ brief descriptions will be completely suppressed.
+
+<dt>\c FULL_PATH_NAMES <dd>
+ \addindex FULL_PATH_NAMES
+ If the \c FULL_PATH_NAMES tag is set to \c YES Doxygen will prepend the full
+ path before files name in the file list and in the header files. If set
+ to NO the shortest path that makes the file name unique will be used
+
+<dt>\c STRIP_FROM_PATH <dd>
+ \addindex STRIP_FROM_PATH
+ If the \c FULL_PATH_NAMES tag is set to \c YES then the \c STRIP_FROM_PATH tag
+ can be used to strip a user defined part of the path. Stripping is
+ only done if the specified string matches the left-hand part of the 
+ path.
+
+<dt>\c CLASS_DIAGRAMS <dd>
+ \addindex CLASS_DIAGRAMS
+ If the \c CLASS_DIAGRAMS tag is set to \c YES (the default) Doxygen will
+ generate a class diagram (in Html and LaTeX) for classes with base or
+ super classes. Setting the tag to \c NO turns the diagrams off.
+
+<dt>\c CASE_SENSE_NAMES <dd>
+ \addindex CASE_SENSE_NAMES
+ If the \c CASE_SENSE_NAMES tag is set to \c NO (the default) then Doxygen
+ will only generate file names in lower case letters. If set to
+ \c YES upper case letters are also allowed. This is useful if you have
+ classes or files whose names only differ in case and if your file system
+ supports case sensitive file names.
+
+<dt>\c VERBATIM_HEADERS <dd>
+ \addindex VERBATIM_HEADERS
+  If the VERBATIM_HEADERS tag is set the YES (the default) then Doxygen\n";
+  will generate a verbatim copy of the header file for each class for\n";
+  which an include is specified. Set to NO to disable this.\n";
+  \sa Section \ref cmdclass.
+
+</dl>
+
+\subsection config_input Input related options
+<dl>
+
+<dt>\c INPUT <dd>
+ \addindex INPUT
+ The \c INPUT tag is used to specify the files and/or directories that contain 
+ documented source files. You may enter file names like 
+ \c myfile.cpp or directories like \c /usr/src/myproject. 
+ Separate the files or directories with spaces.<br>
+
+ \b Notice: This tag (and only this tag) is \e required.
+
+<dt>\c FILE_PATTERNS <dd>
+ \addindex FILE_PATTERNS
+ 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>).
+
+<dt>\c RECURSIVE <dd>
+ \addindex RECURSIVE
+ The \c RECURSIVE tag can be used to specify whether or not subdirectories
+ should be searched for input files as well. Possible values are \c YES 
+ and \c NO.  If left blank \c NO is used.
+
+<dt>\c EXCLUDE <dd>
+ \addindex EXCLUDE
+ The \c EXCLUDE tag can be used to specify files and/or directories that should
+ 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.
+
+<dt>\c EXCLUDE_PATTERNS <dd>
+ \addindex EXCLUDE_PATTERNS
+ If the value of the INPUT tag contains directories, you can use the
+ \c EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+ certain files from those directories.
+
+
+<dt>\c EXAMPLE_PATH <dd>
+ \addindex EXAMPLE_PATH
+ The \c EXAMPLE_PATH tag can be used to specify one or more files or
+ directories that contain example code fragments that are included (see
+ the \\include command in section \ref cmdinclude).
+
+<dt>\c INCLUDE_PATH <dd>
+ \addindex INCLUDE_PATH
+ The INCLUDE_PATH tag can be used to specify one or more directories that
+ contain include files that are not input files but should be processed by
+ the preprocessor.
+ 
+<dt>\c INPUT_FILTER <dd>
+ \addindex INPUT_FILTER
+ The \c INPUT_FILTER tag can be used to specify a program that doxygen should
+ invoke to filter for each input file. Doxygen will invoke the filter program
+ by executing (via popen()) the command:
+\verbatim <filter> <input-file>
+\endverbatim
+ 
+ where \<filter\>
+ is the value of the \c INPUT_FILTER tag, and \<input-file\> is the name of an
+ input file. Doxygen will then use the output that the filter program writes
+ to standard output.
+
+</dl>
+
+\subsection html_output HTML related options
+<dl>
+
+<dt>\c GENERATE_HTML <dd>
+ \addindex GENERATE_HTML
+ If the \c GENERATE_HTML tag is set to \c YES (the default) Doxygen will
+ generate HTML output
+
+<dt>\c HTML_OUTPUT <dd>
+ \addindex HTML_OUTPUT
+ The \c HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+ If a relative path is entered the value of \c OUTPUT_DIRECTORY will be
+ put in front of it. If left blank `html' will be used as the default path.
+
+<dt>\c HTML_HEADER <dd>      
+ \addindex HTML_HEADER
+ The \c HTML_HEADER tag can be used to specify a user defined HTML 
+ header file for each generated HTML page. To get valid HTML the header file
+ should contain at least a \c <HTML> and a \c <BODY> tag. Example:
+\verbatim
+  <HTML>
+    <HEAD>
+      <TITLE>My title</TITLE>
+    </HEAD>
+    <BODY BGCOLOR="#FFFFFF">
+\endverbatim
+ If the tag is left blank doxygen will generate a 
+ standard header. 
+   
+<dt>\c HTML_FOOTER <dd>
+ \addindex HTML_FOOTER
+ The \c HTML_FOOTER tag can be used to specify a user defined HTML footer for 
+ each generated HTML page. To get valid HTML the header file should contain
+ at least a \c </BODY> and a \c </HTML> tag.  Example:
+\verbatim
+    </BODY>
+  </HTML>
+\endverbatim
+ If the tag is left blank doxygen will generate a standard footer.
+
+</dl>
+
+\subsection latex_output LaTeX related options
+<dl>
+
+<dt>\c GENERATE_LATEX <dd>
+ \addindex GENERATE_LATEX
+ If the \c GENERATE_LATEX tag is set to \c YES (the default) Doxygen will
+ generate Latex output.
+
+<dt>\c LATEX_OUTPUT <dd>
+ \addindex LATEX_OUTPUT
+ The \c LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+ If a relative path is entered the value of \c OUTPUT_DIRECTORY will be
+ put in front of it. If left blank `latex' will be used as the default path.
+
+<dt>\c COMPACT_LATEX <dd>
+ \addindex COMPACT_LATEX
+ If the \c COMPACT_LATEX tag is set to \c YES Doxygen generates more compact
+ LaTeX documents. This may be useful for small projects and may help to
+ save some trees in general.
+
+<dt>\c PAPER_TYPE <dd>
+ \addindex PAPER_TYPE
+ The PAPER_TYPE tag can be used to set the paper type that is used
+ by the printer. Possible values are: 
+ <ul>
+ <li><code>a4</code> (210 x 297 mm).
+ <li><code>a4wide</code> (same as a4, but including the a4wide package).
+ <li><code>letter</code> (8.5 x 11 inches).
+ <li><code>legal</code> (8.5 x 14 inches).
+ <li><code>executive</code> (7.25 x 10.5 inches)
+ </ul> 
+ If left blank a4wide will be used.
+
+<dt>\c EXTRA_PACKAGES <dd>
+ \addindex EXTRA_PACKAGES
+ The EXTRA_PACKAGES tag can be used to specify one or more LaTeX 
+ package names that should be included in the LaTeX output.
+ To get the times font for instance you can specify 
+\verbatim
+EXTRA_PACKAGES = times
+\endverbatim
+ If left blank no extra packages will be included.
+</dl>
+
+\subsection man_output Man page related options
+<dl>
+
+<dt>\c GENERATE_MAN <dd>
+ \addindex GENERATE_MAN
+ If the \c GENERATE_MAN tag is set to \c YES (the default) Doxygen will
+ generate man pages for classes and files.
+
+<dt>\c MAN_OUTPUT <dd>
+ \addindex MAN_OUTPUT
+ The \c MAN_OUTPUT tag is used to specify where the man pages will be put.
+ If a relative path is entered the value of \c OUTPUT_DIRECTORY will be
+ put in front of it. If left blank `man' will be used as the default path.
+ A directory man3 will be created inside the directory specified by 
+ \c MAN_OUTPUT.
+
+</dl>
+
+\subsection config_prepro Preprocessor related options
+<dl>
+
+<dt>\c ENABLE_PREPROCESSING <dd>
+ \addindex ENABLE_PREPROCESSING
+ If the \c ENABLE_PREPROCESSING tag is set to \c YES (the default) Doxygen will
+ evaluate all C-preprocessor directives found in the sources and include
+ files. 
+
+<dt>\c MACRO_EXPANSION <dd>
+ \addindex MACRO_EXPANSION
+ If the \c MACRO_EXPANSION tag is set to \c YES Doxygen will expand all macro
+ names in the source code. If set to \c NO (the default) only conditional 
+ compilation will be performed.
+
+<dt>\c SEARCH_INCLUDES <dd>
+ \addindex SEARCH_INCLUDES 
+ If the \c SEARCH_INCLUDES tag is set to \c YES (the default) the includes files
+ in the \c INCLUDE_PATH (see below) will be search if a \#include is found.
+
+<dt>\c INCLUDE_PATH <dd>
+ \addindex INCLUDE_PATH
+ The \c INCLUDE_PATH tag can be used to specify one or more directories that
+ contain include files that are not input files but should be processed by
+ the preprocessor.
+
+<dt>\c PREDEFINED <dd>
+ \addindex PREDEFINED
+ The \c PREDEFINED tag can be used to specify one or more macro names that
+ are defined before the preprocessor is started (similar to the -D option of
+ gcc). The argument of the tag is a list of macros of the form:
+ <code>name</code> or <code>name=definition</code> (no spaces). 
+ If the definition and the = are omitted =1 is assumed.
+
+<dt>\c EXPAND_ONLY_PREDEF <dd>
+ \addindex EXPAND_ONLY_PREDEF
+ If the \c EXPAND_ONLY_PREDEF and \c MACRO_EXPANSION tags are both set to YES
+ then the macro expansion is limited to the macros specified with the
+ \c PREDEFINED tag.
+
+</dl>
+
+\subsection config_extref External reference options
+<dl>
+
+<dt>\c TAGFILES <dd> 
+ \addindex TAGFILES
+ The \c TAGFILES tag can be used to specify one or more tagfiles. 
+ See section \ref doxytag_usage for more information about the usage of 
+ tag files.
+ 
+ \par Notice:
+  Each tag file most have a unique name and if a tag file is not located
+  in the directory in which doxygen is run, you must also specify the
+  path to the tagfile here.
+
+<dt>\c GENERATE_TAGFILE <dd>
+ \addindex GENERATE_TAGFILE
+ When a file name is specified after \c GENERATE_TAGFILE, doxygen will create
+ a tag file that is based on the input files it reads.
+ See section \ref doxytag_usage for more information about the usage of 
+ tag files.
+
+<dt>\c ALLEXTERNALS <dd>
+ \addindex ALLEXTERNALS
+ if the \c ALLEXTERNALS tag is set to \c YES all external class will be listed
+ in the class index. If set to \c NO only the inherited external classes
+ will be listed.
+
+<dt>\c PERL_PATH <dd>
+ \addindex PERL_PATH
+ The \c PERL_PATH should be the absolute path and name of the perl script
+ interpreter (i.e. the result of `<tt>which perl</tt>').
+
+</dl>
+\subsection config_search Search engine options
+<dl>
+
+<dt>\c SEARCHENGINE <dd>
+ \addindex SEARCHENGINE
+ The \c SEARCHENGINE tag specifies whether or not a 
+ search should be used. Possible values are \c YES and \c NO. 
+ If set to \c NO or left blank, the values of all other tags in this section 
+ will be ignored.
+
+<dt>\c CGI_NAME <dd>
+ \addindex CGI_NAME
+ The \c CGI_NAME tag should be the name of the CGI script that
+ starts the search engine (<tt>doxysearch</tt>) with the correct parameters.
+ A script with this name will be generated by doxygen.
+
+<dt>\c CGI_URL <dd>
+ \addindex CGI_URL
+ The \c CGI_URL tag should be the absolute URL to the directory where the
+ cgi binaries are located. See the documentation of your http daemon for 
+ details.
+
+<dt>\c DOC_URL <dd>
+ \addindex DOC_URL
+ The \c DOC_URL tag should be the absolute URL to the directory where the
+ documentation is located. If left blank the absolute path to the 
+ documentation, with <tt>file://</tt> prepended to it, will be used. 
+ This is correct for local viewing only.
+
+<dt>\c DOC_ABSPATH <dd>
+ \addindex DOC_ABSPATH
+ The \c DOC_ABSPATH tag should be the absolute path to the directory where the
+ documentation is located. If left blank the directory on the local machine
+ will be used.
+
+<dt>\c BIN_ABSPATH <dd>     
+ \addindex BIN_ABSPATH
+ The \c BIN_ABSPATH tag must point to the directory where the doxysearch binary
+ is installed.
+
+<dt>\c EXT_DOC_PATHS <dd>  
+ \addindex EXT_DOC_PATHS
+ The \c EXT_DOC_PATHS tag can be used to specify one or more paths to 
+ documentation generated for other projects. This allows doxysearch to search
+ the documentation for these projects as well. All paths must be absolute.
+
+</dl>
+<h2>Examples</h2>
+
+Suppose you have a simple project consisting of two files: a source file 
+\c example.cc and a header file \c example.h.
+Then a minimal configuration file is as simple as:
+\verbatim
+INPUT            = example.cc example.h
+\endverbatim
+
+Assuming the example makes use of Qt classes and perl is located 
+in <code>/usr/bin</code>, a more realistic configuration file would be:
+\verbatim
+PROJECT_NAME     = Example
+INPUT            = example.cc example.h
+WARNINGS         = YES
+TAGFILES         = qt.tag
+PERL_PATH        = /usr/bin/perl
+SEARCHENGINE     = NO
+\endverbatim
+
+To generate the documentation for the 
+<a href="http://www.stack.nl/~dimitri/qdbttabular/index.html">QdbtTabular</a> package
+I have used the following configuration file:
+\verbatim
+PROJECT_NAME     = QdbtTabular
+OUTPUT_DIRECTORY = html
+WARNINGS         = YES
+INPUT            = examples/examples.doc src
+FILE_PATTERNS    = *.cc *.h
+INCLUDE_PATH     = examples
+TAGFILES         = qt.tag
+PERL_PATH        = /usr/local/bin/perl
+SEARCHENGINE     = YES
+CGI_NAME         = search.cgi
+CGI_URL          = http://www.stack.nl/~dimitri/cgi-bin
+DOC_URL          = http://www.stack.nl/~dimitri/qdbttabular
+DOC_ABSPATH      = /home/dimitri/.html/qdbttabular
+BIN_ABSPATH      = /home/dimitri/bin
+\endverbatim
+
+To regenerate the Qt documentation from the sources, you could use the
+following config file:
+\verbatim
+PROJECT_NAME         = Qt
+OUTPUT_DIRECTORY     = qt_docs
+HIDE_UNDOC_MEMBERS   = YES
+HIDE_UNDOC_CLASSES   = YES
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION      = YES
+EXPAND_ONLY_PREDEF   = YES
+SEARCH_INCLUDES      = YES
+FULL_PATH_NAMES      = YES
+STRIP_FROM_PATH      = $(QTDIR)/
+PREDEFINED           = USE_TEMPLATECLASS Q_EXPORT= \
+                       QArrayT=QArray \
+                       QListT=QList \
+                       QDictT=QDict \
+                       QQueueT=QQueue \
+                       QVectorT=QVector \
+                       QPtrDictT=QPtrDict \
+                       QIntDictT=QIntDict \
+                       QStackT=QStack \
+                       QDictIteratorT=QDictIterator \
+                       QListIteratorT=QListIterator \
+                       QCacheT=QCache \
+                       QCacheIteratorT=QCacheIterator \
+                       QIntCacheT=QIntCache \
+                       QIntCacheIteratorT=QIntCacheIterator \
+                       QIntDictIteratorT=QIntDictIterator \
+                       QPtrDictIteratorT=QPtrDictIterator
+INPUT                = $(QTDIR)/doc \
+                       $(QTDIR)/src/widgets \
+                       $(QTDIR)/src/kernel \
+                       $(QTDIR)/src/dialogs \
+                       $(QTDIR)/src/tools
+FILE_PATTERNS        = *.cpp *.h q*.doc
+INCLUDE_PATH         = $(QTDIR)/include 
+RECURSIVE            = YES
+\endverbatim
+
+Here Doxygen's preprocessor is used to substitute some
+macro names that are normally substituted by the C preprocessor,
+but without doing full macro expansion.
+
+*/
+