initial version

1 files changed, 411 insertions, 0 deletions

diff --git a/doc/starting.doc b/doc/starting.doc
new file mode 100644
index 0000000..1d3cbcd
--- /dev/null
+++ b/doc/starting.doc
@@ -0,0 +1,411 @@
+/******************************************************************************
+ *
+ * $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 starting Getting started
+
+The executable \c doxygen is the main program that parses the sources and 
+generates the documentation. See section \ref doxygen_usage for more
+detailed usage information.
+
+The executable \c doxytag is only needed if you want to generate references 
+to external documentation (i.e. documentation that was generated by Doxygen) 
+for which you do not have the sources or to create a search index for 
+the search engine. See section \ref doxytag_usage for more detailed usage 
+information.
+
+The executable \c doxysearch is only needed if you want to use the search 
+engine. See section \ref doxysearch_usage for more detailed usage information.
+
+\subsection step1 Step 1: Creating a configuration file
+
+Doxygen uses a configuration file to determine all of its settings.
+Each project should get its own configuration file. A project can consist
+of a single source file, but can also be an entire source tree that is 
+recursively scanned.
+
+To simplify the creation of a configuration file, Doxygen can create a 
+template configuration file for you. To do this call \c doxygen with the \c -g 
+option:
+
+\verbatim
+doxygen -g <config-file>
+\endverbatim
+where \<config-file\> is the name of the configuration file. If you omit
+the file name, a file named \c Doxyfile will be created. If a file with the
+name \<config-file\> already exists, Doxygen will rename it to 
+\<config-file\>.bak before generating the configuration template.
+
+The configuration file has a format that is similar to that of a (simple) 
+Makefile. It contains of a number of assignments (tags) of the form:
+
+<tt>TAGNAME = VALUE</tt> or <br>
+<tt>TAGNAME = VALUE1 VALUE2 ... </tt><br>
+
+You can probably leave the values of most tags to their default value. 
+
+The \c INPUT tag is the only tag for which you are required to provide
+a value. See section \ref config for more details about the configuration file.
+For a small project consisting of a few C and/or C++ source and header files, 
+you can add the names of the files after the \c INPUT tag. 
+If you have a larger project consisting of a source directory or tree
+this may become tiresome. In this case you should put the root directory or 
+directories after the \c INPUT tag, and add one or more file 
+patterns to the \c FILE_PATTERN tag. Only files that match one of the 
+patterns will be parsed (if the patterns are omitted all files will be parsed).
+For recursive parsing of a source tree you must set 
+the \c RECURSIVE tag to \c YES. To further finetune the list of files
+that is parsed the \c EXCLUDE and \c EXCLUDE_PATTERNS tags can be used.
+
+If you start using Doxygen for an existing project (thus without any 
+documentation that Doxygen is aware of), you can still get an idea of
+what the documented result would be. To do so, you must set the \c EXTRACT_ALL 
+tag in the configuration file to \c YES. Then, Doxygen will pretend 
+everything in your sources is documented. Please note that warnings of
+undocumented members will not be generated as long as \c EXTRACT_ALL is set
+to \c YES.
+
+\subsection step2 Step 2: Running doxygen
+
+To generate the documentation you can now enter:
+\verbatim
+doxygen <config-file>
+\endverbatim
+
+Doxygen will create a \c html, \c latex and/or \c man directory inside 
+the output directory. 
+As the names suggest the \c html directory contains the
+generated documentation in HTML format and the \c latex directory contains the
+generated documentation in \f$\mbox{\LaTeX}\f$ format. Man pages are put
+in a man3 directory inside the \c man directory.
+
+The default output directory is the directory in which \c doxygen
+is started. The directory to which the output is written can be changed 
+using the \c OUTPUT_DIRECTORY , \c HTML_OUTPUT, \c LATEX_OUTPUT, and
+\c MAN_OUTPUT tags of the configuration file. If the output directory does not 
+exist, \c doxygen will try to create it for you.
+
+\addindex browser
+The generated HTML documentation can be viewed by pointing a HTML browser
+to the \c index.html file in the \c html directory. For the best results
+a browser that supports cascading style sheets (CSS) should be used
+(I'm currently using Netscape 4.0 to test the generated output).
+\addindex LaTeX
+
+The generated \f$\mbox{\LaTeX}\f$ documentation must first be compiled by 
+a \f$\mbox{\LaTeX}\f$ compiler. (I use teTeX distribution version 0.4
+that contains \f$\mbox{\TeX}\f$ version 3.14159). To simplify the process 
+of compiling the generated
+documentation, \c doxygen writes a \c Makefile into the \c latex directory. 
+By typing \c make in the \c latex directory the dvi file \c refman.dvi
+will be generated. This file can then be viewed using \c xdvi or 
+converted into a postscript file \c refman.ps by typing <code>make ps</code> 
+(this requires \c dvips ). The Postscript file can be send to a postscript
+printer. If you do not have a postscript printer, you can try to use 
+ghostscript to convert postscript into something your printer understands.
+
+The generated man pages can be viewed using the \c man program. You do need
+to make sure the man directory is in the man path (see the MANPATH
+environment variable). Notice that there are some limitations to the 
+capabilities of the man page format, so some information 
+(like class diagrams, cross references and formulas) will be lost.
+
+\subsection step3 Step 3: Documenting the sources
+
+Although documenting the source is presented as step 3, in a new project 
+this should ofcourse be step 1. Here I assume
+you already have some code and you want Doxygen to generate a nice document 
+describing the API and maybe the internals as well.
+
+If the \c EXTRACT_ALL option is set to \c NO in the configuration file 
+(the default), then doxygen will only generate documentation for 
+\e documented members, files, classes and namespaces. So how do you document 
+these? For members, classes and namespaces there are basicly two options:
+<ol>
+<li>Place a \e special documentation block in front of the declaration or
+    definition of the member, class or namespace. For file, class and namespace
+    members it is also allowed to place the documention directly after the 
+    member. See section \ref specialblock to learn more about special 
+    documentation blocks.
+<li>Place a special documentation block somewhere else (another file or 
+    another location) \e and put a <em>structural command</em> in the 
+    documentation block. A structural command links a documentation block 
+    to a certain object that can be documented (e.g. a member, class, 
+    namespace or file). See section \ref structuralcommands to learn more 
+    about structural commands.
+</ol>
+Files can only be documented using the second option.
+The text inside a special documentation block is parsed
+before it is written to the HTML and/or \f$\mbox{\LaTeX}\f$ output files.
+
+\addindex parsing
+During parsing the following steps take place:
+<ul>
+<li> The special commands inside the documentation are executed. See
+     section \ref commands for an overview of all commands.
+<li> If a line starts with some whitespace followed by one or more asterixes 
+     (<tt>*</tt>) then the whitespace and asterixes are removed.
+<li> All resulting blank lines are treated as a paragraph separators.
+     This saves you from placing new-paragraph commands yourself, 
+     in order to make the generated documentation readable.
+<li> Links are created for words corresponding to documented classes. 
+<li> Links to members are created when certain patterns are found in the
+     text. See section \ref autolink
+     for more information on how the automatic link generation works.
+<li> HTML tags that are in the documentation are interpreted and converted 
+     to \f$\mbox{\LaTeX}\f$ equivalents for the \f$\mbox{\LaTeX}\f$ output. 
+     See section \ref htmlcmds for an overview of all supported HTML tags.
+</ul>
+
+\subsection specialblock Special documentation blocks
+
+The following types of special documentation blocks are supported by Doxygen:
+<ul>
+<li>The Qt style, where special documentation blocks look like:
+\verbatim
+/*!
+  ... text ...
+*/
+\endverbatim and the one line version:
+\verbatim
+//! ... one line of text ...
+\endverbatim
+<li>The JavaDoc style, where special documentation blocks look like:
+\verbatim
+/**
+ * ... text ...
+ */
+\endverbatim and the one line version:
+\verbatim
+/// ... one line of text ...
+\endverbatim
+</ul>
+
+Here is an example of a documented piece of C++ code using the Qt style:
+\verbinclude qtstyle.cpp
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/qtstyle/html/class_test.html">here</a>
+ for the corresponding HTML documentation that is generated by Doxygen.
+ \endhtmlonly
+
+The one-line comments should contain a brief description, 
+whereas the multi-line comment blocks contain a more detailed description.
+The brief descriptions are included in the member overview of a class, 
+namespace or file and are printed using a small italic font 
+(this description can be omitted by setting \c BRIEF_MEMBER_DESC to \c NO in 
+the config file). By default the brief descriptions are also the first 
+sentence of the detailed description 
+(this can be changed by setting the \c REPEAT_BRIEF tag to \c NO). 
+Both the brief and the detailed descriptions are optional 
+for the Qt style. 
+
+Here is the same piece of code, this time documented using the JavaDoc 
+style:
+\verbinclude jdstyle.cpp
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/jdstyle/html/class_test.html">here</a>
+ for the corresponding HTML documentation that is generated by Doxygen.
+ \endhtmlonly
+
+Notice that the first sentence of the documentation (until the <tt>.</tt>) 
+is treated as a brief description, whereas the documentation block as a whole 
+forms the detailed description. The brief description is required for the 
+JavaDoc style.
+
+Unlike most other documentation systems, Doxygen also allows you to put
+the documentation of members (including global functions) in front of 
+the \e definition. This way the documentation can be placed in the source 
+file instead of the header file. This keeps the header file compact, and allows the 
+implementer of the members more direct access to the documentation.
+As a compromise the brief description could be placed before the
+declaration and the detailed description before the member definition
+(assuming you use the Qt style comments).
+
+\subsection structuralcommands Structural commands
+
+So far we have assumed that the documentation blocks are always located in 
+front of the declaration or definition of a file, class or namespace or in
+front of one of its members. 
+Although this is often comfortable, it may sometimes be better to put the 
+documentation somewhere else. For some types of documentation blocks (like file
+documentation) this is even required. Doxygen allows you to put your
+documentation blocks practically anywhere (the exception is inside the body 
+of a function or inside a normal C style comment block), as long as you put a 
+structural command inside the documentation block.
+
+Structural commands (like all other commands) start with a backslash 
+(<tt>\\</tt>) followed by a command name and one or more parameters.
+For instance, if you want to document the class \c Test in the example
+above, you could have also put the following documentation block somewhere
+in the input that is read by Doxygen:
+\verbatim
+/*! \class Test
+    \brief A test class.
+
+    A more detailed class description.
+*/
+\endverbatim
+
+Here the special command \c \class is used to indicated that the
+comment block contains documentation for the class \c Test.
+Other structural commands are:
+<ul>
+<li>\c \struct to document a C-struct.
+<li>\c \union to document a union.
+<li>\c \enum to document an enumeration type.
+<li>\c \fn to document a function.
+<li>\c \var to document a variable or typedef or enum value.
+<li>\c \def to document a \#define.
+<li>\c \file to document a file.
+<li>\c \namespace to document a namespace.
+</ul>
+See section \ref commands for detailed information about these and other 
+commands. Notice that the documentation block belonging to a file 
+should always contain a structural command.
+
+To document a member of a C++ class, you must also document the class 
+itself. The same holds for namespaces. To document a C function, typedef, 
+enum or preprocessor definition you must first document the file that 
+contains it (usually this will be a header file, because that file contains 
+the information that is exported to other source files).
+
+Here is an example of a C header named \c structcmd.h that is documented 
+using structural commands:
+\verbinclude structcmd.h
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/structcmd/html/structcmd.h.html">here</a>
+ for the corresponding HTML documentation that is generated by Doxygen.
+ \endhtmlonly
+
+\par Notice:
+  Because each comment block in the example above contains a structural command, all
+  the comment blocks could be moved to another location or input file 
+  (the source file for instance), without affecting the generated 
+  documentation. The disadvantage of this approach is that prototypes are
+  duplicated, so all changes have to be made twice!
+
+\subsection memberdoc Documenting compound members.
+
+If you want to document the members of a file, struct, union, class, or enum 
+and you want to put the documentation for these members inside the compound,
+it is sometimes desired to place the documentation block after the member 
+instead of before. For this purpose Doxygen has the following 
+additional comment blocks:
+\verbatim
+/*!< ... */
+\endverbatim
+This block can be used to put a qt style documentation blocks after a member.
+The one line version look as follows:
+\verbatim
+//!< ...
+\endverbatim
+There are also JavaDoc versions:
+\verbatim
+/**< ... */
+\endverbatim
+and
+\verbatim
+///< ... 
+\endverbatim
+Notice that these blocks have the same structure and meaning as the 
+special comment blocks above only the \< indicates that the member is 
+located in front of the block instead of after the block.
+
+Here is an example of a the use of these comment blocks:
+\verbinclude afterdoc.h
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/afterdoc/html/class_test.html">here</a>
+ for the corresponding HTML documentation that is generated by Doxygen.
+ \endhtmlonly
+
+\warning These blocks can only be used to document \e members.
+         They cannot be used to document file classes, unions, structs and 
+         enums. Furthermore, the structural commands mentioned in the 
+         previous section are ignored inside these comment blocks.
+
+\subsection formulas Including formulas in the documentation
+
+Doxygen allows you to put \f$\mbox{\LaTeX}\f$ formulas in the
+output (this works only for the HTML and \f$\mbox{\LaTeX}\f$ formats, 
+not for the man page output). To be able to include formulas (as images)
+in the HTML documentation, you will also need to have the following tools
+installed
+<ul>
+<li>\c latex: the \f$\mbox{\LaTeX}\f$ compiler, needed to parse the formulas. 
+    To test I have used the teTeX 0.4 distribution.
+<li>\c dvips: a tool to convert dvi files to postscript files 
+    I have used version 5.58f from Radical Eye software for testing.
+<li>\c gs: the ghostscript interpreter for converting postscript files 
+    to bitmaps. I have used Aladdin Ghostscript 5.01 for testing.
+</ul>
+
+There are two ways to include formulas in the documentation.
+<ol>
+<li>Using in-text formulas that appear in the running text. 
+    These formulas should be put between a pair of \\f\$ 
+    commands, so
+\verbatim
+  The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is 
+  \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.
+\endverbatim results in:
+
+  The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is 
+  \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.
+<br>
+<li>Unnumbered displayed formulas that are centered on a separate line.
+    These formulas should be put between \\f\[ and \\f\] commands.
+    An example:
+\verbatim
+  \f[
+    |I_2|=\left| \int_{0}^T \psi(t) 
+             \left\{ 
+                u(a,t)-
+                \int_{\gamma(t)}^a 
+                \frac{d\theta}{k(\theta,t)}
+                \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
+             \right\} dt
+          \right|
+  \f]
+\endverbatim
+  results in:
+  \f[
+    |I_2|=\left| \int_{0}^T \psi(t) 
+             \left\{ 
+                u(a,t)-
+                \int_{\gamma(t)}^a 
+                \frac{d\theta}{k(\theta,t)}
+                \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
+             \right\} dt
+          \right|
+  \f]
+</ol>
+Formulas should be valid commands in \f$\mbox{\LaTeX}\f$'s math-mode.
+
+\warning Currently, Doxygen is not very fault tolerant in recovering 
+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 moreinfo More information
+
+\addindex QdbtTabular
+For a more elaborate example see <a href="http://www.stack.nl/~dimitri/qdbttabular/html/index.html">
+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. 
+\endhtmlonly
+
+*/