diff options
Diffstat (limited to 'doc/external.doc')
| -rw-r--r-- | doc/external.doc | 138 |
1 files changed, 0 insertions, 138 deletions
diff --git a/doc/external.doc b/doc/external.doc deleted file mode 100644 index 9e156d1..0000000 --- a/doc/external.doc +++ /dev/null @@ -1,138 +0,0 @@ -/****************************************************************************** - * - * - * - * Copyright (C) 1997-2005 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 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. -<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. -<dt>Copyright issues:<dd>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. - -</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 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: -<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 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 <a href="faq.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -*/ |