Updated installation section of the manual

2 files changed, 41 insertions, 375 deletions

diff --git a/doc/install.doc b/doc/install.doc
index 3f5d8ab..295154f 100644
--- a/doc/install.doc
+++ b/doc/install.doc
@@ -35,11 +35,10 @@ following to build the executable:
     \addindex libiconv
     \addindex make
     \addindex strip
+    \addindex python
 <li>In order to generate a \c Makefile for your platform, you need 
-    <a href="http://www.perl.com/">perl</a>
-    \addindex perl
-<li>The configure script assume the availability of standard UNIX tools such 
-    as <code>sed, date, find, uname, mv, cp, cat, echo, tr, cd</code> and \c rm.
+    <a href="http://www.cmake.org/">cmake</a> version 2.8.12 or later.
+    \addindex cmake
 </ul>
 
 To take full advantage of doxygen's features the following additional
@@ -49,7 +48,7 @@ tools should be installed.
 <li>Qt Software's GUI toolkit 
     <a href="http://qt-project.org/">Qt</A>
     \addindex Qt
-    version 4.3 or higher (but currently, Qt 5.x is not supported).
+    version 4.3 or higher (but currently, Qt 5.x is not yet supported).
     This is needed to build the GUI front-end doxywizard. 
 <li>A \LaTeX distribution: for instance
     <a href="http://www.tug.org/interest.html#free">TeX Live</a>
@@ -61,11 +60,10 @@ tools should be installed.
     If you compile graphviz yourself, make sure you do include
     freetype support (which requires the freetype library and header files), 
     otherwise the graphs will not render proper text labels.
-<li>For formulas or if you do not wish to use `pdflatex, the ghostscript interpreter
-    is needed. You can find it at 
+<li>For formulas in the HTML output (when MathJax is not used)
+    or in case you do not wish to use `pdflatex,
+    the ghostscript interpreter is needed. You can find it at 
     <a href="http://www.ghostscript.com/">www.ghostscript.com</a>.
-<li>In order to generate doxygen's own documentation, Python is needed, you
-    can find it  at <a href="http://www.python.org">www.python.org</a>.
 </ul>
 
 Compilation is now done by performing the following steps:
@@ -76,62 +74,46 @@ Compilation is now done by performing the following steps:
         gunzip doxygen-$VERSION.src.tar.gz    # uncompress the archive
         tar xf doxygen-$VERSION.src.tar       # unpack it
 
-<li>Run the configure script:
- 
-        sh ./configure
+<li>Create a build directory (for instance inside the source tree)
 
-    The script tries to determine the platform you use, the make tool 
-    (which \e must be GNU make) and the perl 
-    interpreter. It will report what it finds. 
+        cd doxygen-$VERSION
+        mkdir build
 
-    To override the auto detected platform and compiler you can run
-    configure as follows:
+<li>Run cmake with the makefile generator
 
-        configure --platform platform-type
+        cmake -G "Unix Makefiles" ..
 
-    See the <code>PLATFORMS</code> file for a list of possible platform
-    options.
+    <code>cmake</code> tries to determine the platform you use, and will look
+    for the requires tools. It will report if something is missing.
 
-    If you have Qt-4.3 or higher installed and want to build the GUI 
-    front-end, you should run the configure script with 
-    the `--with-doxywizard` option:
+    If you have Qt-4.3 or higher installed and want to build the GUI
+    front-end, you should enable it as follows:
 
-        configure --with-doxywizard
+        cmake -Dbuild_wizard=YES
 
     For an overview of other configuration options use
 
-        configure --help
+        cmake -L
 
 <li>Compile the program by running make:
 
         make
 
-    The program should compile without problems and the binaries 
-    (<code>doxygen</code> and optionally <code>doxywizard</code>) 
-    should be available in the bin directory of the distribution.
+    The program should compile without problems and the binaries
+    (<code>doxygen</code> and optionally <code>doxywizard</code>)
+    should be available in the bin directory within the build directory.
 
 <li>Optional: Generate the user manual.
     
+        cmake -Dbuild_doc=YES
         make docs
 
-    To let doxygen generate the HTML documentation.
+    To let doxygen generate the HTML and PDF documentation.
     
-    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). You will need the <code>python</code> interpreter 
-    for this.
+    The HTML directory within the build directory 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 PDF version of the manual
-    (you will need <code>pdflatex</code>, <code>makeindex</code>, and
-     <code>egrep</code> for this).
-
-        make pdf
-
-    The PDF manual <code>doxygen_manual.pdf</code> will be located 
-    in the latex directory of the distribution. Just 
-    view and print it via the acrobat reader. 
-
 </ol>
 
 \section install_bin_unix    Installing the binaries on UNIX
@@ -164,107 +146,15 @@ the wrong directory!
 If you have a RPM or DEP package, then please follow the 
 standard installation procedure that is required for these packages. 
 
-\section unix_problems Known compilation problems for UNIX
-
-<b>Qt problems</b>
-
-The Qt include files and libraries are not a subdirectory of the
-directory pointed to by <code>QTDIR</code> on some systems
-(for instance on Red Hat 6.0 includes are in <code>/usr/include/qt</code> and
-libs are in <code>/usr/lib</code>).
-  
-The solution: go to the root of the doxygen distribution and do:
-
-    mkdir qt
-    cd qt
-    ln -s your-qt-include-dir-here include
-    ln -s your-qt-lib-dir-here lib
-    ln -s your-qt-bin-dir-here bin
-    export QTDIR=$PWD
-
-If you have a <code>csh</code>-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>Bison problems</b>
-
-Versions 1.31 to 1.34 of \c bison contain a "bug" that results in a 
-compiler errors like this:
-
-<code>ce_parse.cpp:348: member `class CPPValue yyalloc::yyvs' with </code>
-constructor not allowed in union
-
-This problem has been solved in version 1.35 (versions before 1.31 
-will also work).
-
-<b>Sun compiler problems</b>
-
-It appears that doxygen doesn't work properly if it is compiled 
-with Sun's C++ WorkShop Compiler. I cannot verify this myself as I do 
-not have access to a Solaris machine with this compiler. With GNU compiler
-it does work and installing Sun patch 111679-13 has also been reported 
-as a way to fix the problem.
-
-when configuring with `--static` I got:
-
-\verbatim
-Undefined                       first referenced
- symbol                             in file
-dlclose                             /usr/lib/libc.a(nss_deffinder.o)
-dlsym                               /usr/lib/libc.a(nss_deffinder.o)
-dlopen                              /usr/lib/libc.a(nss_deffinder.o)
-\endverbatim
-
-Manually adding `-Bdynamic` after the target rule in 
-`Makefile.doxygen` will fix this:
-
-    $(TARGET): $(OBJECTS) $(OBJMOC) 
-            $(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic
-
-<b>GCC 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 `--english-only` option.  
-
-On some platforms (such as OpenBSD) using some versions of gcc with
--O2 can lead to eating all memory during the compilation of files 
-such as config.cpp. As a workaround use `--debug` as a configure option 
-or omit the `-O2` for the particular files in the Makefile.
-
-Gcc versions before 2.95 may produce broken binaries due to bugs in 
-these compilers. 
-
-<b>Dot problems</b>
-
-Due to a change in the way image maps are generated, older versions
-of doxygen (\<=1.2.17) will not work correctly with newer versions of
-graphviz (\>=1.8.8). The effect of this incompatibility is that
-generated graphs in HTML are not properly clickable. For doxygen 1.3
-it is recommended to use at least graphviz 1.8.10 or higher.
-For doxygen 1.4.7 or higher it is recommended to 
-use GraphViz 2.8 or higher to avoid font issues.
+\section install_src_windows Compiling from source on Windows
 
-<b>Red Hat 9.0 problems</b>
+From version 1.8.10 onwards, build files need to be generated by cmake.
+cmake can be downloaded from http://www.cmake.org/download/
 
-If you get the following error after running make
-\verbatim
-tmake error: qtools.pro:70: Syntax error
-\endverbatim
-then first type
-\verbatim
-export LANG=
-\endverbatim
-before running make.
-
-\section install_src_windows Compiling from source on Windows
+At the moment only the express version of Visual Studio 2013 is tested,
+but other version might also work.
 
-From version 1.7.0 onwards, build files are provided for Visual Studio 2008.
-Also the free (as in beer) "Express" version of Developer Studio can be used to 
-compile doxygen. Alternatively, you can compile doxygen 
+Alternatively, you can compile doxygen 
 \ref install_src_unix "the UNIX way" using 
 <a href="http://en.wikipedia.org/wiki/Cygwin">Cygwin</a>
 or <a href="http://www.mingw.org/">MinGW</a>.
@@ -273,13 +163,11 @@ The next step is to install modern versions of \c bison and \c flex
 (see http://sourceforge.net/projects/winflexbison. After installation and adding them to
 your `path` rename `win_flex.exe` to `flex.exe` and `win_bison.exe` to `bison.exe`)
 Furthermore you have to install \c python (version 2.6 or higher, see http://www.python.org).
-These packages are needed during the
-compilation process if you use a GitHub snapshot of doxygen (the official source releases 
-come with pre-generated sources).
+These packages are needed during the compilation process.
 
 Download doxygen's source tarball and put it somewhere (e.g. use <code>c:\\tools</code>)
 
-Now start a new command shell and type
+Now start a visual studio native command shell (for either x86 or x64) and type
 \verbatim
 cd c:\tools
 tar zxvf doxygen-x.y.z.src.tar.gz
@@ -288,12 +176,14 @@ to unpack the sources (you can obtain \c tar from e.g. http://gnuwin32.sourcefor
 Alternatively you can use an unpack program, like 7-Zip (see http://www.7-zip.org)
 or use the build in unpack feature of modern Windows systems).
 
-Now your environment is setup to build \c doxygen.
+Now your environment is setup to generate the required project files for \c doxygen.
 
-Inside the \c doxygen-x.y.z directory you will find a \c winbuild directory 
-containing a \c Doxygen.sln file. Open this file in Visual Studio. 
-You can now build the Release or Debug flavor of Doxygen by right-clicking
-the project in the solutions explorer, and selecting Build.
+cd into the \c doxygen-x.y.z directory, create and cd to a build directory
+\verbatim
+mkdir build
+cd build
+cmake -G "Visual Studio 12 2013"
+\endverbatim
 
 Note that compiling Doxywizard currently requires Qt version 4
 (see http://qt-project.org/).
@@ -301,149 +191,6 @@ Note that compiling Doxywizard currently requires Qt version 4
 Also read the next section for additional tools you may need to install to run
 doxygen with certain features enabled.
 
-<!--
-
-Currently, I have only compiled doxygen for Windows using Microsoft's 
-Visual C++ (). 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. If you have Visual Studio you can also use the .dsw file found in
-the <code>wintools</code> directory. Note that this file is not maintained
-by me, so it might be outdated a little.
-
-If you have Visual C++ 6.0, and the source distribution, you can easily
-build doxygen using the project files in the \c wintools directory. If
-you want to build the CVS sources, or want to build from the command line,
-or with another compiler, you have to follow the steps below.
-
-Thomas Baust reported that if you have Visual Studio.NET (2003) then 
-you should be aware that there is a problem with the _popen() and _pclose() 
-implementation, which currently leaks handles, so if you build doxygen with 
-it and use the INPUT_FILTER, you will run to risk of crashing Windows! 
-The problem is reported to and confirmed by Microsoft so maybe it will 
-fixed in the next service pack.
-
-Since Windows comes without all the nice tools that UNIX users are
-used to, you'll need to install a number of these tools before you can compile 
-doxygen for Windows from the command-line.
-
-Here is what is required:
-<ul>
-<li>An unzip/untar tool like WinZip to unpack the tar source distribution. 
-    This can be found at http://www.winzip.com/  
-
-    The good, tested, and free alternative is the <code>tar</code> utility
-    supplied with <a href="http://sourceware.cygnus.com/cygwin/">cygwin
-    tools</a>. Anyway, the Cygwin's \c flex, \c bison, and \c sed are also
-    recommended below.
-
-<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). 
-
-    Borland C++ or MINGW (see http://www.mingw.org/) are also supported. 
-
-<li>Perl 5.0 or higher for Windows. This can be downloaded from:
-    http://www.ActiveState.com/Products/ActivePerl/
-
-<li>The GNU tools \c flex, \c bison, and \c sed.
-    To get these working on Windows you should install the 
-    <a href="http://sources.redhat.com/cygwin/">cygwin tools</a>
-    
-    Alternatively, you can also choose to 
-    download only a <a href="http://www.doxygen.org/dl/cygwin_tools.zip">small subset</a> 
-    of the cygwin tools that I put together just to compile doxygen.
-
-    As a third alternative one could use the GNUWin32 tools that can be
-    found at http://gnuwin32.sourceforge.net/ 
-    
-    Make sure the <code>BISON_SIMPLE</code> environment variable points to the
-    location where the files <code>bison.simple</code> and 
-    is located. For instance if these file is in
-    <code>c:\\tools\\cygwin\\usr\\share</code> then BISON_SIMPLE should 
-    be set to <code>c:/tools/cygwin/usr/share/bison.simple</code>
-
-    Also make sure the tools are available from a dos box, by adding 
-    the directory they are in to the search path.
-    
-    For those of you who are very new to cygwin (if you are going to
-    install it from scratch), you should notice that there is an
-    archive file <code>bootstrap.zip</code> which also contains the
-    <code>tar</code> utility (<code>tar.exe</code>), <code>gzip</code>
-    utilities, and the <code>cygwin1.dll</code> core. This also means
-    that you have the <code>tar</code> in hands from the start. It
-    can be used to unpack the tar source distribution instead of
-    using WinZip -- as mentioned at the beginning of this list of
-    steps.
-
-<li>From Doxygen-1.2.2-20001015 onwards, the distribution includes the part
-    of Qt that is needed for to compile doxygen.
-    The Windows specific part were also created.
-    As a result doxygen (without the wizard) can be compiled on systems 
-    without X11 or (the commercial version of) Qt.
-
-<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.
-
-</ul>
-
-
-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).
-
-    Notice: The use of \LaTeX is optional and only needed for compilation
-    of the documentation into PostScript or PDF. 
-    It is \e not needed for compiling the doxygen's binaries. 
-    
-<li>Go to the doxygen root dir and type:
-
-\verbatim
-    make.bat msvc
-\endverbatim
-
-    This should build the executable
-    <code>doxygen.exe</code> using Microsoft's Visual C++ compiler
-    (The compiler should not produce any serious warnings or errors).
-
-    You can use also the <code>bcc</code> argument to build
-    executables using the Borland C++ compiler, or
-    <code>mingw</code> argument to compile using GNU gcc.
-
-<li>To build the examples, go to the <code>examples</code> subdirectory
-    and type:
-
-\verbatim
-    nmake
-\endverbatim
-
-<li>To generate the doxygen documentation, go to the <code>doc</code> 
-    subdirectory and type:
-
-\verbatim
-    nmake
-\endverbatim
-
-    The generated HTML docs are located in the <code>..\\html</code>
-    subdirectory.
-
-    The sources for \LaTeX documentation are located in the <code>..\\latex</code>
-    subdirectory. From those sources, the DVI, PostScript, and PDF
-    documentation can be generated. 
-</ol>
-
--->
-
 \section install_bin_windows Installing the binaries on Windows
 
 Doxygen comes as a self-installing archive, so installation is extremely simple.
@@ -481,85 +228,6 @@ latex.exe, pdflatex.exe, and gswin32c.exe are present in the search path of a
 command box. Follow <a href="http://www.computerhope.com/issues/ch000549.htm">these</a>
 instructions if you are unsure and run the commands from a command box to verify it works.
 
-<!--
-There is no fancy installation procedure at the moment (if anyone can
-add it in a location independent way 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.
-
-There are a couple of tools you may want to install to use all of doxygen's
-features:
-
-<ul>
-<li>To generate \LaTeX documentation or formulas in HTML you need the tools:
-    <code>latex</code>, <code>dvips</code> and <code>gswin32</code>. 
-    To get these working under Windows
-    install the fpTeX distribution. You can find more info at:
-    http://www.fptex.org/ and download it from CTAN or one of its mirrors.
-    In the Netherlands for example this would be: 
-    ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/
-
-    Make sure the tools are available from a dos box, by adding the 
-    directory they are in to the search path.
-
-    For your information, \LaTeX is a freely available set of so
-    called macros and styles on the top of the famous \TeX program
-    (by famous Donald Knuth) and the accompanied utilities (all
-    available for free). It is used for high quality
-    typesetting. The result -- in the form of so called
-    <code>DVI</code> (DeVice Independent) file -- can be printed or
-    displayed on various devices preserving exactly the same look up
-    to the capability of the device. The <code>dvips</code> allows you
-    to convert the <code>dvi</code> to the high quality PostScript
-    (i.e. PostScript that can be processed by utilities like 
-    <code>psnup</code>, <code>psbook</code>, <code>psselect</code>,
-    and others). The derived version of \TeX (the pdfTeX) can be used
-    to produce PDF output instead of DVI, or the PDF can be produced
-    from PostScript using the utility <code>ps2pdf</code>.
-
-    If you want to use MikTeX then you need to select at least the 
-    medium size installation. For really old versions of MikTex or minimal 
-    installations, you may need to download the fancyhdr package separately. 
-    You can find it in the 
-    <a href="ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/">
-    contrib/supported</a> directory of the tex archives.
-
-<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 from 
-    <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconHH1Start.asp">Microsoft</a>.
-
-<li>If you want to produce Qt Compressed Help files (see \ref 
-    cfg_qhelgenerator_loc "QHG_LOCATION") in the config file,
-    then you need qhelpgenerator which is part of Qt. 
-    You can download Qt from
-    <a href="http://qt-project.org/downloads">Qt Software Downloads</a>.
-
-<li><a href="http://www.graphviz.org/">
-    the Graph visualization toolkit version 1.8.10</a><br>
-    Needed for the include dependency graphs, the graphical inheritance graphs,
-    and the collaboration graphs.
-</ul>
-
--->
-
-\section build_tools Tools used to develop doxygen
-
-Doxygen was developed and tested under Linux &amp; MacOSX using the following 
-open-source tools:
-<ul>
-<li>GCC version 4.6.3 (Linux) and 4.2.1 (MacOSX)
-<li>GNU flex version 2.5.35 
-<li>GNU bison version 2.5 (Linux) and 2.3 (MacOSX)
-<li>GNU make version 3.81
-<li>Perl version 5.12
-<li>Python version 2.7 and 3.4
-<li>TeX Live 2009 (or later)
-</ul>
-
 \htmlonly
 Go to the <a href="starting.html">next</a> section or return to the
  <a href="index.html">index</a>.
diff --git a/doc/trouble.doc b/doc/trouble.doc
index 718c7bc..47ef623 100644
--- a/doc/trouble.doc
+++ b/doc/trouble.doc
@@ -18,8 +18,6 @@
 
 \section knowproblems Known Problems
 <ul>
-<li>If you have problems building doxygen from sources, please 
-    read \ref unix_problems "this section" first.
 <li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner.
     This means that it can and will not detect errors in your source code.
 <li>Doxygen has a build in preprocessor, but this works slightly different than