1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
/******************************************************************************
*
*
*
* Copyright (C) 1997-2002 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.
</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 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
*/
|
