diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/external.doc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Orb/Doxygen/doc/external.doc Thu Jan 21 17:29:01 2010 +0000 @@ -0,0 +1,138 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2008 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: + +
+
Disk space:
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. +
Compilation speed:
External projects typically have a different update + frequency from 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. +
Memory:
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. +
Availability:
For some projects that are documented with doxygen, + the sources may just not be available. +
Copyright issues:
If the external + package and its documentation are copyright someone else, it may be + better - or even necessary - to reference it rather than include a + copy of it with your project's documentation. When the author forbids + redistribution, this is necessary. If the author requires compliance + with some license condition as a precondition of redistribution, and + you do not want to be bound by those conditions, referring to their + copy of their documentation is preferable to including a copy. + +
+ +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 your 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 an 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: +
+
At configuration time:
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. +
After compile time:
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. +
+ +\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 + + +- 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 the relevant 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. Another case where you should use doxytag is +if you want to create a tag file for the Qt documentation. + +The tool \c doxytag 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 you only use this approach if there is no alternative. The +doxytag tool may even become obsolete in the future. + +\htmlonly +Go to the next section or return to the + index. +\endhtmlonly + +*/