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