Release-1.1.5-20000716

1 files changed, 126 insertions, 0 deletions

diff --git a/doc/external.doc b/doc/external.doc
new file mode 100644
index 0000000..01c275f
--- /dev/null
+++ b/doc/external.doc
@@ -0,0 +1,126 @@
+/******************************************************************************
+ *
+ * 
+ *
+ * Copyright (C) 1997-2000 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.
+ *
+ * Documents produced by Doxygen are derivative works derived from the
+ * input used in their production; they are not affected by this license.
+ *
+ */
+/*! \page external Linking to external documentation
+
+If your project depends on external libraries or tools, there are several 
+reasons to not include all sources for these with every run of doxygen:
+
+<dl>
+<dt>Disk space:<dd> Some documentation may be available outside of the output 
+    directory of doxygen already, for instance somewhere on the web. 
+    You may want to link to these pages instead of generating the documentation 
+    in your local output directory.
+<dt>Compilation speed:<dd> External projects typically have a different update 
+    frequency form your own project. It does not make much sense to let doxygen 
+    parse the sources for these external project over and over again, even if 
+    nothing has changed.
+<dt>Memory:<dd> For very large source trees, letting doxygen parse all sources 
+    may simply take too much of your system's memory. By dividing the sources 
+    into several "packages", the sources of one package can be parsed by 
+    doxygen, while all other packages that this package depends on, are 
+    linked in externally. This saves a lot of memory.
+<dt>Availability:<dd> For some projects that are documented with doxygen,
+    the sources may just not be available.
+</dl>
+
+If any of the above apply, you can use doxygen's tag file mechanism.
+A tag file is basically a compact representation of the entities found in the
+external sources. Doxygen can both generate and read tag files.
+
+To generate a tag file for your project, simply put the name of the
+tag file after the \ref cfg_generate_tagfile "GENERATE_TAGFILE" option in 
+the configuration file. 
+
+To combine the output of one or more external projects with you own project 
+you should specify the name of the tag files after 
+the \ref cfg_tagfiles "TAGFILES" option in the configuration file.
+
+A tag file does not contain information about where the external documentation
+is located. This could be a directory or URL. So when you include a tag 
+file you have to specify where the external documentation is located. 
+There are two ways to do this:
+<dl>
+<dt>At configuration time:<dd> just assign the location of the output to the
+    tag files specified after the \ref cfg_tagfiles "TAGFILES" configuration
+    option. If you use a relative path it should be relative with respect to 
+    the directory where the html output of your project is generated.
+<dt>After compile time:<dd> if you do not assign a location to a tag file,
+    doxygen will generate dummy links for all external HTML references. It will
+    also generate a perl script called \ref installdox_usage "installdox" in 
+    the HTML output directory. This script should be run to replace the 
+    dummy links with real links for all generated HTML files.
+</dl>
+
+\par Example: 
+Suppose you have a project \c proj that uses two external 
+projects called \c ext1 and \c ext2.
+The directory structure looks as follows:
+
+\par
+\verbatim
+<root>
+  +- proj
+  |   +- html               HTML output directory for proj
+  |   +- src                sources for proj
+  |   |- proj.cpp
+  +- ext1
+  |   +- html               HTML output directory for ext1
+  |   |- ext1.tag           tag file for ext1
+  +- ext2
+  |   +- html               HTML output directory for ext2
+  |   |- ext2.tag           tag file for ext2
+  |- proj.cfg               doxygen configuration file for proj
+  |- ext1.cfg               doxygen configuration file for ext1
+  |- ext2.cfg               doxygen configuration file for ext2
+\endverbatim
+
+\par
+Then relevate parts of the configuration files look as follows:
+\par
+proj.cfg:
+\verbatim
+OUTPUT_DIRECTORY  = proj
+INPUT             = proj/src
+TAGFILES          = ext1/ext1.tag=../../ext1/html \
+                    ext2/ext2.tag=../../ext2/html 
+\endverbatim 
+ext1.cfg:
+\verbatim
+OUTPUT_DIRECTORY  = ext1
+GENERATE_TAGFILE  = ext1/ext1.tag 
+\endverbatim 
+ext2.cfg:
+\verbatim
+OUTPUT_DIRECTORY  = ext2
+GENERATE_TAGFILE  = ext2/ext2.tag
+\endverbatim
+
+In some (hopefully exceptional) cases you may have the documentation
+generated by doxygen, but not the sources nor a tag file. In this case you
+can use the \ref doxytag_usage "doxytag" tool to extract a tag file from 
+the generated HTML sources. This tool depends on the particular structure
+of the generated output and on some special markers that are generated by
+doxygen. Since this type of extraction is brittle and error prone I
+suggest to only use this approach if there is no alternative. The
+doxytag tool may even become obsolete in the future.
+
+\htmlonly
+Go to the <a href="faq.html">next</a> section or return to the
+ <a href="index.html">index</a>.
+\endhtmlonly
+
+*/