doc/external.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2012 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 typically only contains a relative location of the documentation from the
  62 point where doxygen was run. So when you include a tag file in other project
  63 you have to specify where the external documentation is located in relation this project.
  64 You can do this in the configuration file by assigning the (relative) location to the
  65 tag files specified after the \ref cfg_tagfiles "TAGFILES" configuration
  66 option. If you use a relative path it should be relative with respect to
  67 the directory where the HTML output of your project is generated; so a relative path
  68 from the HTML output directory of a project to the HTML output of the other project that
  69 is linked to.
  70
  71 \par Example:
  72 Suppose you have a project \c proj that uses two external
  73 projects called \c ext1 and \c ext2.
  74 The directory structure looks as follows:
  75
  76 \par
  77 \verbatim
  78 <root>
  79   +- proj
  80   |   +- html               HTML output directory for proj
  81   |   +- src                sources for proj
  82   |   |- proj.cpp
  83   +- ext1
  84   |   +- html               HTML output directory for ext1
  85   |   |- ext1.tag           tag file for ext1
  86   +- ext2
  87   |   +- html               HTML output directory for ext2
  88   |   |- ext2.tag           tag file for ext2
  89   |- proj.cfg               doxygen configuration file for proj
  90   |- ext1.cfg               doxygen configuration file for ext1
  91   |- ext2.cfg               doxygen configuration file for ext2
  92 \endverbatim
  93
  94 \par
  95 Then the relevant parts of the configuration files look as follows:
  96 \par
  97 proj.cfg:
  98 \verbatim
  99 OUTPUT_DIRECTORY  = proj
 100 INPUT             = proj/src
 101 TAGFILES          = ext1/ext1.tag=../../ext1/html \
 102                     ext2/ext2.tag=../../ext2/html
 103 \endverbatim
 104 ext1.cfg:
 105 \verbatim
 106 OUTPUT_DIRECTORY  = ext1
 107 GENERATE_TAGFILE  = ext1/ext1.tag
 108 \endverbatim
 109 ext2.cfg:
 110 \verbatim
 111 OUTPUT_DIRECTORY  = ext2
 112 GENERATE_TAGFILE  = ext2/ext2.tag
 113 \endverbatim
 114
 115 \htmlonly
 116 Go to the <a href="faq.html">next</a> section or return to the
 117  <a href="index.html">index</a>.
 118 \endhtmlonly
 119
 120 */