diff options
Diffstat (limited to 'doc/config.doc')
| -rw-r--r-- | doc/config.doc | 553 |
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. + +*/ + |