Release-1.1.5-20000716

1 files changed, 353 insertions, 54 deletions

diff --git a/doc/install.doc b/doc/install.doc
index 461e730..c03a529 100644
--- a/doc/install.doc
+++ b/doc/install.doc
@@ -20,96 +20,395 @@
 First go to the 
 <a href="http://www.stack.nl/~dimitri/doxygen/download.html">download</a> page
 \latexonly({\tt http://www.stack.nl/$\sim$dimitri/doxygen/download.html})\endlatexonly
-to get the latest distribution and unpack it.
+to get the latest distribution, if you did not have it already.
+
+\subsection install_src_unix    Compiling from source on Unix
 
 If you downloaded the source distribution, you need at least the 
 following to build the executable:
-<UL>
-<LI>Troll Tech's GUI toolkit <A HREF="http://www.trolltech.com/products/qt.html">Qt</A>
+<ul>
+<li>Troll Tech's GUI toolkit 
+    <A HREF="http://www.trolltech.com/products/qt.html">Qt</A>
     \latexonly(see {\tt http://www.trolltech.com/products/qt.html})\endlatexonly.
     \addindex Qt
-<LI>The <a href="ftp://prep.ai.mit.edu/pub/gnu">GNU</a> tools 
+    You can download either version 1.44 or version 2.1.x.
+    If want to build the GUI front-end you will need Qt 2.1.x. If you do
+    not need it, using Qt 1.44 will result in a somewhat smaller executable. 
+<li>The <a href="ftp://prep.ai.mit.edu/pub/gnu">GNU</a> tools 
     flex, bison and make
     \addindex flex
     \addindex bison
     \addindex make
-<LI>In order to generate a Makefile for your platform, you need 
+<li>In order to generate a Makefile for your platform, you need 
     <a href="http://www.perl.com>perl</a>
     \latexonly(see {\tt http://www.perl.com})\endlatexonly.
     \addindex perl
-</UL>
-For platform specific installation instructions see the \c INSTALL file
-that is included in the package.
+</ul>
+
+To take full advantage of doxygen's features the following additional
+tools should be installed.
+
+<ul>
+<li>A \f$\mbox{\LaTeX}\f$ distribution: for instance
+    <a href="http://www.tug.org">teTeX 1.0</a>.<br>
+    This is needed for generating LaTeX, Postscript, and PDF output.
+<li><a href="http://www.research.att.com/sw/tools/graphviz/">
+    the Graph visualization toolkit version 1.5</a><br>
+    Needed for the include dependency graphs, 
+    the graphical inheritance graphs,
+    and the collaboration graphs.
+<li>The ghostscript interpreter.
+</ul>
+
+Compilation is now done by performing the following steps:
+
+<ol>
+<li> Unpack the archive, unless you already have done that:
+   
+\verbatim
+    gunzip doxygen-$VERSION.src.tar.gz    # uncompress the archive
+    tar xf doxygen-$VERSION.src.tar       # unpack it
+\endverbatim
+
+<li>Run the configure script:
+ 
+\verbatim
+    sh ./configure
+\endverbatim
 
-\addindex HTTP
-\addindex CGI
-To use the search engine \c doxysearch, you will also need
-a HTTP daemon running on the target system and permission to execute a 
-CGI binary.
+    The script tries to determine the platform you use, the location
+    of the Qt library, the make tool (which \e must be GNU make) and the perl 
+    interpreter. It will report what it finds. 
+
+    To override the auto detected platform and compiler you can run
+    configure as follows:
 
-If you are running Unix, and have Qt installed correctly, you can simply enter
 \verbatim
-configure
+    configure --platform platform-type
 \endverbatim
-to set up the makefiles for your platform. For Windows this step can be
-skipped.
 
-To override the auto detected platform you can specify
+    See the <code>PLATFORMS</code> file for a list of possible platform
+    options.
+
+    If you have Qt-2.1.x installed and want to build the GUI front-end, you
+    should run the configure script with the <code>--with-doxywizard</code> 
+    option.
+
+    For an overview of other configuration options use
+
 \verbatim
-configure --platform platform-type
+    configure --help
 \endverbatim
-See the file \c PLATFORMS for a list of possible platforms. 
-For more configuration options use <code>configure --help</code>
 
-To compile and link the sources enter
+<li>Compile the program by running make:
+
 \verbatim
-make
+    make
 \endverbatim
-in the root of the distribution.
-Doxygen should compile without errors or warnings.
-If it does not, please send the compilation errors or warnings along 
-with a description of your platform to 
-<a href="mailto:dimitri@stack.nl>dimitri@stack.nl</a>.
 
-After compilation, the binaries will be located in the \c bin
-directory of the distribution.
-You may want to copy these files to a location in your path 
-(\c /usr/local/bin for instance) or add the \c bin
-directory of the distribution to your search path.
+    The program should compile without problems and three binaries 
+    (<code>doxygen</code>, <code>doxytag</code>, and <code>doxysearch</code>) 
+    should be available in the bin directory of the distribution.
 
-On Unix you can also type:
+<li>Optional: Generate the user manual.
+    
 \verbatim
-make install
+    make docs
 \endverbatim
 
-The following binaries should now be available:
-<UL>
-<LI>\c doxygen: for generating the class browser. 
-<LI>\c doxytag: for creating a tag file containing references 
-    to external documentation.
-<LI>\c doxysearch: the search engine. This binary should not be 
-    executed directly. It must be called from an CGI script that will be 
-    generated by doxygen. 
-</UL>
+    To let doxygen generate the HTML documentation.
+    
+    \note you will need the stream editor <code>sed</code> for this, 
+    but this should be available on any Unix platform.
 
-To take full advantage of doxygen's features the following additional
-tools should be installed.
+    The HTML directory of the distribution will now contain the html 
+    documentation (just point a HTML browser to the file 
+    <code>index.html</code> in the 
+    html directory).
+    
+<li>Optional: Generate a postscript and pdf version of the manual. 
+    (you will need <code>latex</code> and <code>dvips</code> and
+     the ghostscript package for this).
+
+\verbatim
+    make pdf
+\endverbatim
 
+    The postscript manual <code>doxygen_manual.ps</code> will be located 
+    in the latex directory of the distribution. Just send it to a 
+    postscript printer to print it or use <code>ghostview</code> to view it. 
+
+</ol>
+
+\subsection install_bin_unix    Installating the binaries on Unix
+
+    If you downloaded the binary distribution for Unix, you can install 
+    doxygen by typing:
+
+\verbatim
+    ./configure
+    make install
+\endverbatim   
+
+    Binaries are installed in the directory <code>\<prefix\>/bin</code>
+    Documentation and examples in the directory 
+    <code>\<prefix\>/doc/doxygen</code>
+
+    <code>\<prefix\></code> defaults to /usr but can be changed with 
+    the <code>--prefix</code> option of the configure script. 
+
+    Alternatively, you can also copy the binaries from the <code>bin</code> 
+    directory manually to some <code>bin</code> directory in your search path.
+    This is sufficient to use doxygen.
+
+    \note You need the GNU install tool for this to work. Other
+    install tools may put the binaries in the wrong directory!
+
+    If you have a RPM or DEP package, then please follow the 
+    standard installation procedure that is required for these packages. 
+
+\subsection unix_problems Known compilation problems for Unix
+
+<b>Qt problems</b>
+
+The Qt include files and libraries are not a sub directory of the
+directory pointed to by QTDIR on some systems.
+(for instance on Red Hat 6.0 includes are in /usr/include/qt and
+libs are in /usr/lib)
+  
+The solution: goto the root of the doxygen distribution and do:
+\verbatim
+   mkdir qt
+   cd qt
+   ln -s your-qt-include-dir-here include
+   ln -s your-qt-lib-dir-here lib
+   export QTDIR=$PWD
+\endverbatim 
+
+If you have a csh-like shell you should use <code>setenv QTDIR $PWD</code>
+instead of the <code>export</code> command above.
+  
+Now install doxygen as described above.  
+
+<b>Latex problems</b>
+
+the file <code>a4wide.sty</code> is not available for all distributions. If
+your distribution does not have it please select another paper type
+in the config file (see the \ref cfg_paper_type "PAPER_TYPE" tag in the 
+config file).
+
+<b>HP-UX & Digital Unix problems</b>
+
+If you are compiling for HP-UX with aCC and you get this error:
+\verbatim
+    /opt/aCC/lbin/ld: Unsatisfied symbols:
+    alloca (code)
+\endverbatim
+  then you should (according to Anke Selig) edit <code>ce_parse.cpp</code> 
+  and replace
+\verbatim
+    extern "C" {
+      void *alloca (unsigned int);
+    };
+\endverbatim
+  with
+\verbatim
+    #include <alloca.h>  
+\endverbatim
+
+If you are compiling for Digital Unix, the same problem can be solved
+(according to Barnard Schmallhof) by replacing the following in 
+ce_parse.cpp:
+   
+\verbatim
+    #else /* not GNU C.  */
+    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi)
+    #include <alloca.h>
+\endverbatim
+
+  with
+
+\verbatim
+    #else /* not GNU C.  */
+    #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) || defined (__osf__)
+    #include <alloca.h>
+\endverbatim
+
+  Alternatively, one could fix the problem at the bison side.
+  Here is patch for bison.simple (provided by Andre Johansen):
+ 
+\verbatim
+--- bison.simple~       Tue Nov 18 11:45:53 1997
++++ bison.simple        Mon Jan 26 15:10:26 1998
+@@ -27,7 +27,7 @@
+ #ifdef __GNUC__
+ #define alloca __builtin_alloca
+ #else /* not GNU C.  */
+-#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi)
++#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) || defined (__alpha)
+ #include <alloca.h>
+ #else /* not sparc */
+ #if defined (MSDOS) && !defined (__TURBOC__)
+\endverbatim
+
+  The generated scanner.cpp that comes with doxygen is build with this
+  patch applied.  
+
+<b>Sun compiler problems</b>
+
+
+
+<b>GNU 2.7.2.x compiler problems</b>
+
+Older versions of the GNU compiler have problems with constant strings
+containing characters with character codes larger than 127. Therefore 
+the compiler will fail to compile some of the translator_xx.h files. 
+A workaround, if you are planning to use the English translation only, 
+is to configure doxygen with the <code>--english-only</code> option.  
+
+\subsection install_src_windows Compiling from source on Windows
+
+Currently, I have only compiled doxygen for Windows using Microsoft's 
+Visual C++ (version 6.0). For other compilers you may need to edit the 
+perl script in <code>wintools/make.pl</code> a bit. 
+Let me know what you had to change if you got Doxygen working with another 
+compiler. 
+
+Since Windows comes without all the nice tools that Unix users are
+used to, you need to install a number of these tools before you can compile 
+doxygen for Windows.
+
+Here is what is required:
 <ul>
-<li>\f$\mbox{\LaTeX}\f$:
-    <a href="http://www.tug.org">teTeX 1.0</a> (for Unix) or 
-    <a href="ftp://ctan.tug.org/tex-archive/systems/win32/web2c/fptex-0.3/">fpTeX 0.3</a> (for Windows)<br>
-    Needed for LaTeX and PDF output.
+<li>WinZip to unpack the tar source distribution. This can be found at
+    http://www.winzip.com
+<li>Microsoft Visual C++ (I only tested with version 6.0).
+    Use the <code>vcvars32.bat</code> batch file to set the environment 
+    variables (if you did not select to do this automatically during 
+    installation).
+<li>Perl 5.0 or higher for Windows. This can be download from:
+    http://www.ActiveState.com/pw32
+<li>The GNU tools flex, bison and sed.
+    To get these working on Windows you should install the 
+    <a href="http://sourceware.cygnus.com/cygwin/">cygwin tools</a>
+    \latexonly(see {\tt http://sourceware.cygnus.com/cygwin/})\endlatexonly.
+    
+    Make sure the <code>BISONLIB</code> environment variable points to the
+    location where the files <code>bison.simple</code> and 
+    <code>bison.hairy</code> are located.
+
+    Also make sure the tools are available from a dos box, by adding 
+    the directory they are in to the search path.
+
+<li>A professional license of 
+    <A HREF="http://www.trolltech.com/products/qt.html">Qt for Windows</A><br>
+    \latexonly(see {\tt http://www.trolltech.com/products/qt.html})\endlatexonly.
+   
+    If you do not have that and you can live without the GUI front-end 
+    you can also download Qt-1.44 for X11. Doxygen only the depends on 
+    the tools section of the Qt library, which happens also to compile 
+    on Windows. (Qt version 2.1.x does not work anymore, at least not 
+    without adding some window's specific code). 
+    
+    Now create the following directories:
+
+\verbatim
+    qtools/src
+    qtools/include
+    qtools/lib
+\endverbatim
+
+    Copy the contents of the <code>src/tools</code> directory of the 
+    Qt-1.44 for X11 archive to <code>qtools/src</code>. Also copy the include 
+    files in <code>src/tools</code> to <code>qtools/include</code>. Create a 
+    static library project resulting in <code>qtools/lib/qt.lib</code> and 
+    add the files in <code>qtools/src</code> to that project. Then 
+    build the library and set the environment variable <code>QTDIR</code> 
+    to the absolute path of the qtools directory.
+
+<li>To generate LaTeX documentation or formulas in HTML you need the tools: 
+    latex, dvips and gswin32 
+    To get these working under Windows install the fpTeX distribution
+    You can download it at: 
+    ftp://ctan.tug.org/tex-archive/systems/win32/web2c/fptex-0.3/
+
+    Make sure the tools are available from a dos box, by adding the 
+    directory they are in to the search path.
+
+<li>If you want to generate compressed HTML help 
+    (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the 
+    config file, then you need the Microsoft HTML help workshop. 
+    You can download it at: 
+    http://msdn.microsoft.com/workshop/author/htmlhelp
+<li>If you used WinZip to extract the tar archive it will (apparently) not 
+    create empty folders, so you have to add the folders
+    <code>objects</code> and <code>bin</code> manually in the root of the 
+    distribution before compiling.
 <li><a href="http://www.research.att.com/sw/tools/graphviz/">
     the Graph visualization toolkit version 1.5</a><br>
     Needed for the include dependency graphs, the graphical inheritance graphs,
     and the collaboration graphs.<br>
-<li><a href="http://msdn.microsoft.com/workshop/author/htmlhelp">
-    the HTML help workshop</a> (for Windows only)<br>
-    Needed for compiling compressed HTML output (a.k.a. the new Windows help format).
 </ul>
 
-Doxygen was developed and tested under Linux using the following tools:
+Compilation is now done by performing the following steps:
+
+<ol>
+<li>Open a dos box.
+    Make sure all tools (i.e. <code>nmake</code>, <code>latex</code>, 
+    <code>gswin32</code>, <code>dvips</code>, <code>sed</code>, 
+    <code>flex</code>, <code>bison</code>, 
+    <code>cl</code>, <code>rm</code> and <code>perl</code>), are accessible from the command-line 
+    (add them to the PATH environment variable if needed).
+
+<li>goto the doxygen root dir and type:
+
+\verbatim
+    make.bat
+\endverbatim
+
+    This should build the executables 
+    <code>doxygen.exe</code>, <code>doxytag.exe</code>, and 
+    <code>doxysearch.exe</code> (The compiler should not produce any 
+    serious warnings or errors).
+
+<li>To build the examples type:
+
+\verbatim
+    nmake examples
+\endverbatim
+
+<li>To generate the HTML documentation type:
+
+\verbatim
+    nmake docs
+\endverbatim
+
+    The generated docs are located in the html directory.
+
+<li>
+    To generate the postscript and PDF manual type:
+
+\verbatim
+    nmake pdf
+\endverbatim
+
+    The manual should now be in <code>latex/doxygen_manual.pdf</code>
+
+</ol>
+
+\subsection install_bin_windows Installating the binaries on Windows
+
+There is no fancy installation procedure at the moment (If anyone wants
+to add it please let me know).
+
+To install doxygen, just copy the binaries from the <code>bin</code> directory
+to a location somewhere in the path. Alternatively, you can include 
+the <code>bin</code> directory of the distribution to the path.
+
+\subsection build_tools Tools used to develop doxygen
+
+Doxygen was developed and tested under Linux using the following 
+open-source tools:
 <ul>
 <li>EGCS version 2.91.66
 <li>GNU flex version 2.5.4