If your project depends on external libraries or tools there are several reasons not to include all of the source for with every run of DoxyPress.

Disk space

Some documentation may be available outside of the output directory of DoxyPress 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 DoxyPress parse the sources for these external project over and over again, even if nothing has changed.

Memory

For very large source trees, letting DoxyPress 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 DoxyPress, while all other packages that this package depends on, are linked in externally. This saves a lot of memory.

Availability

For some projects documented with DoxyPress, the sources may 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 the DoxyPress tag file mechanism. A tag file is basically a compact representation of the entities found in the external sources. DoxyPress can both generate and read tag files.

To generate a tag file for your project put the name of the tag file after the generate-tagfile option in your project file.

To combine the output of one or more external projects with your own project, specify the name of the tag files after the tag-files tag in the project file.

A tag file typically only contains a relative location of the documentation from the point where DoxyPress 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 project file by assigning the (relative) location to the tag files specified after the tag-files tag. 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.

Example:

Suppose you have a project projectA which uses two external projects called ext1 and ext2. The directory structure looks as follows:

<root>
  +- projectA
  |   +- html               HTML output directory for projectA
  |   +- src                sources for projectA
  |   |- 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
  |- projectA.json          DoxyPress project file for projectA
  |- ext1.json              DoxyPress project file for ext1
  |- ext2.json              DoxyPress project file for ext2

The relevant parts of the project files will look as follows:

projectA.json

OUTPUT-DIR        = projectA
INPUT-SOURCE      = projectA/src
TAG-FILES         = ext1/ext1.tag=../../ext1/html, ext2/ext2.tag=../../ext2/html 

ext1.json

OUTPUT-DIR        = ext1
GENERATE-TAGFILE  = ext1/ext1.tag 

ext2.json

OUTPUT-DIR        = ext2
GENERATE-TAGFILE  = ext2/ext2.tag