/******************************************************************************

 *

 * 

 *

 * Copyright (C) 1997-2015 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:

Disk space:
 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.

Compilation speed:
 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.

Memory:
 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.

Availability:
 For some projects that are documented with doxygen,

    the sources may just 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 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 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 \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; so a relative path

from the HTML output directory of a project to the HTML output of the other project that 

is linked to.

\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

\htmlonly

Go to the next section or return to the

 index.

\endhtmlonly

*/