|
1 /****************************************************************************** |
|
2 * |
|
3 * |
|
4 * |
|
5 * Copyright (C) 1997-2008 by Dimitri van Heesch. |
|
6 * |
|
7 * Permission to use, copy, modify, and distribute this software and its |
|
8 * documentation under the terms of the GNU General Public License is hereby |
|
9 * granted. No representations are made about the suitability of this software |
|
10 * for any purpose. It is provided "as is" without express or implied warranty. |
|
11 * See the GNU General Public License for more details. |
|
12 * |
|
13 * Documents produced by Doxygen are derivative works derived from the |
|
14 * input used in their production; they are not affected by this license. |
|
15 * |
|
16 */ |
|
17 /*! \page external Linking to external documentation |
|
18 |
|
19 If your project depends on external libraries or tools, there are several |
|
20 reasons to not include all sources for these with every run of doxygen: |
|
21 |
|
22 <dl> |
|
23 <dt>Disk space:<dd> Some documentation may be available outside of the output |
|
24 directory of doxygen already, for instance somewhere on the web. |
|
25 You may want to link to these pages instead of generating the documentation |
|
26 in your local output directory. |
|
27 <dt>Compilation speed:<dd> External projects typically have a different update |
|
28 frequency from your own project. It does not make much sense to let doxygen |
|
29 parse the sources for these external project over and over again, even if |
|
30 nothing has changed. |
|
31 <dt>Memory:<dd> For very large source trees, letting doxygen parse all sources |
|
32 may simply take too much of your system's memory. By dividing the sources |
|
33 into several "packages", the sources of one package can be parsed by |
|
34 doxygen, while all other packages that this package depends on, are |
|
35 linked in externally. This saves a lot of memory. |
|
36 <dt>Availability:<dd> For some projects that are documented with doxygen, |
|
37 the sources may just not be available. |
|
38 <dt>Copyright issues:<dd>If the external |
|
39 package and its documentation are copyright someone else, it may be |
|
40 better - or even necessary - to reference it rather than include a |
|
41 copy of it with your project's documentation. When the author forbids |
|
42 redistribution, this is necessary. If the author requires compliance |
|
43 with some license condition as a precondition of redistribution, and |
|
44 you do not want to be bound by those conditions, referring to their |
|
45 copy of their documentation is preferable to including a copy. |
|
46 |
|
47 </dl> |
|
48 |
|
49 If any of the above apply, you can use doxygen's tag file mechanism. |
|
50 A tag file is basically a compact representation of the entities found in the |
|
51 external sources. Doxygen can both generate and read tag files. |
|
52 |
|
53 To generate a tag file for your project, simply put the name of the |
|
54 tag file after the \ref cfg_generate_tagfile "GENERATE_TAGFILE" option in |
|
55 the configuration file. |
|
56 |
|
57 To combine the output of one or more external projects with your own project |
|
58 you should specify the name of the tag files after |
|
59 the \ref cfg_tagfiles "TAGFILES" option in the configuration file. |
|
60 |
|
61 A tag file does not contain information about where the external documentation |
|
62 is located. This could be a directory or an URL. So when you include a tag |
|
63 file you have to specify where the external documentation is located. |
|
64 There are two ways to do this: |
|
65 <dl> |
|
66 <dt>At configuration time:<dd> just assign the location of the output to the |
|
67 tag files specified after the \ref cfg_tagfiles "TAGFILES" configuration |
|
68 option. If you use a relative path it should be relative with respect to |
|
69 the directory where the HTML output of your project is generated. |
|
70 <dt>After compile time:<dd> if you do not assign a location to a tag file, |
|
71 doxygen will generate dummy links for all external HTML references. It will |
|
72 also generate a perl script called \ref installdox_usage "installdox" in |
|
73 the HTML output directory. This script should be run to replace the |
|
74 dummy links with real links for all generated HTML files. |
|
75 </dl> |
|
76 |
|
77 \par Example: |
|
78 Suppose you have a project \c proj that uses two external |
|
79 projects called \c ext1 and \c ext2. |
|
80 The directory structure looks as follows: |
|
81 |
|
82 \par |
|
83 \verbatim |
|
84 <root> |
|
85 +- proj |
|
86 | +- html HTML output directory for proj |
|
87 | +- src sources for proj |
|
88 | |- proj.cpp |
|
89 +- ext1 |
|
90 | +- html HTML output directory for ext1 |
|
91 | |- ext1.tag tag file for ext1 |
|
92 +- ext2 |
|
93 | +- html HTML output directory for ext2 |
|
94 | |- ext2.tag tag file for ext2 |
|
95 |- proj.cfg doxygen configuration file for proj |
|
96 |- ext1.cfg doxygen configuration file for ext1 |
|
97 |- ext2.cfg doxygen configuration file for ext2 |
|
98 \endverbatim |
|
99 |
|
100 \par |
|
101 Then the relevant parts of the configuration files look as follows: |
|
102 \par |
|
103 proj.cfg: |
|
104 \verbatim |
|
105 OUTPUT_DIRECTORY = proj |
|
106 INPUT = proj/src |
|
107 TAGFILES = ext1/ext1.tag=../../ext1/html \ |
|
108 ext2/ext2.tag=../../ext2/html |
|
109 \endverbatim |
|
110 ext1.cfg: |
|
111 \verbatim |
|
112 OUTPUT_DIRECTORY = ext1 |
|
113 GENERATE_TAGFILE = ext1/ext1.tag |
|
114 \endverbatim |
|
115 ext2.cfg: |
|
116 \verbatim |
|
117 OUTPUT_DIRECTORY = ext2 |
|
118 GENERATE_TAGFILE = ext2/ext2.tag |
|
119 \endverbatim |
|
120 |
|
121 In some (hopefully exceptional) cases you may have the documentation |
|
122 generated by doxygen, but not the sources nor a tag file. In this case you |
|
123 can use the \ref doxytag_usage "doxytag" tool to extract a tag file from |
|
124 the generated HTML sources. Another case where you should use doxytag is |
|
125 if you want to create a tag file for the Qt documentation. |
|
126 |
|
127 The tool \c doxytag depends on the particular structure |
|
128 of the generated output and on some special markers that are generated by |
|
129 doxygen. Since this type of extraction is brittle and error-prone I |
|
130 suggest you only use this approach if there is no alternative. The |
|
131 doxytag tool may even become obsolete in the future. |
|
132 |
|
133 \htmlonly |
|
134 Go to the <a href="faq.html">next</a> section or return to the |
|
135 <a href="index.html">index</a>. |
|
136 \endhtmlonly |
|
137 |
|
138 */ |