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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Linking to external documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('external.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Linking to external documentation </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>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:</p>
<dl>
<dt>Disk space:</dt>
<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. </dd>
<dt>Compilation speed:</dt>
<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. </dd>
<dt>Memory:</dt>
<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. </dd>
<dt>Availability:</dt>
<dd>For some projects that are documented with doxygen, the sources may just not be available. </dd>
<dt>Copyright issues:</dt>
<dd><p class="startdd">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.</p>
<p class="enddd"></p>
</dd>
</dl>
<p>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.</p>
<p>To generate a tag file for your project, simply put the name of the tag file after the <a class="el" href="config.html#cfg_generate_tagfile">GENERATE_TAGFILE</a> option in the configuration file.</p>
<p>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 <a class="el" href="config.html#cfg_tagfiles">TAGFILES</a> option in the configuration file.</p>
<p>A tag file typically only contains a relative location of the documentation from the point where doxygen was run. So when you include a tag file in other project you have to specify where the external documentation is located in relation this project. You can do this in the configuration file by assigning the (relative) location to the tag files specified after the <a class="el" href="config.html#cfg_tagfiles">TAGFILES</a> 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; so a relative path from the HTML output directory of a project to the HTML output of the other project that is linked to.</p>
<dl class="section user"><dt>Example: </dt><dd>Suppose you have a project <code>proj</code> that uses two external projects called <code>ext1</code> and <code>ext2</code>. The directory structure looks as follows:</dd></dl>
<dl class="section user"><dt></dt><dd><pre class="fragment"><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
</pre></dd></dl>
<dl class="section user"><dt></dt><dd>Then the relevant parts of the configuration files look as follows: </dd></dl>
<dl class="section user"><dt></dt><dd>proj.cfg: <pre class="fragment">OUTPUT_DIRECTORY = proj
INPUT = proj/src
TAGFILES = ext1/ext1.tag=../../ext1/html \
ext2/ext2.tag=../../ext2/html
</pre> ext1.cfg: <pre class="fragment">OUTPUT_DIRECTORY = ext1
GENERATE_TAGFILE = ext1/ext1.tag
</pre> ext2.cfg: <pre class="fragment">OUTPUT_DIRECTORY = ext2
GENERATE_TAGFILE = ext2/ext2.tag
</pre></dd></dl>
<p>
Go to the <a href="faq.html">next</a> section or return to the
<a href="index.html">index</a>.
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
</ul>
</div>
</body>
</html>
|
