summaryrefslogtreecommitdiffstats
path: root/doc/config.doc
diff options
context:
space:
mode:
authormueller <mueller@afe2bf4a-e733-0410-8a33-86f594647bc7>1999-12-15 19:25:10 (GMT)
committermueller <mueller@afe2bf4a-e733-0410-8a33-86f594647bc7>1999-12-15 19:25:10 (GMT)
commit719f0a35063be88eddcc4ed8fe7a940de47ef20c (patch)
treecc1cd70cf5761ddf72ff114c0b65576c3f4c1d2a /doc/config.doc
parentbd30c025c4651ddda467f1af09d4c7ccab397bde (diff)
downloadDoxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.zip
Doxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.tar.gz
Doxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.tar.bz2
initial version
Diffstat (limited to 'doc/config.doc')
-rw-r--r--doc/config.doc553
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 (&quot;...&quot;).
+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.
+
+*/
+