summaryrefslogtreecommitdiffstats
path: root/doc/external.doc
diff options
context:
space:
mode:
authorDimitri van Heesch <dimitri@stack.nl>2000-07-16 17:27:25 (GMT)
committerDimitri van Heesch <dimitri@stack.nl>2000-07-16 17:27:25 (GMT)
commit55571c2989a42e670d62b4cb2d2bd2882b5ecd60 (patch)
tree156f3b8b79f2df8ecf0c8d3175e2788e40b4b824 /doc/external.doc
parent56bc9bda61e06b9bd6da5aa58083e93a3b55a465 (diff)
downloadDoxygen-55571c2989a42e670d62b4cb2d2bd2882b5ecd60.zip
Doxygen-55571c2989a42e670d62b4cb2d2bd2882b5ecd60.tar.gz
Doxygen-55571c2989a42e670d62b4cb2d2bd2882b5ecd60.tar.bz2
Release-1.1.5-20000716
Diffstat (limited to 'doc/external.doc')
-rw-r--r--doc/external.doc126
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
+
+*/