Add a README.md at the root of the SCM repository

- A file INSTALL.md is also added,
- Installation/INSTALL is added the .md extension,

.gitignore

@@ -1124,3 +1124,4 @@ gmon.*
 /Polygon/test/Polygon/polytest.ascii
 /Polygon/test/Polygon/polytest.binary
 /Polygon/test/Polygon/polytest.pretty
+/*.html

INSTALL.md

@@ -0,0 +1,217 @@
+Building CGAL Libraries and Executables based on CGAL
+=====================================================
+
+Building CGAL using the *branch build* presented here keeps the
+build-sources attached to the Git repository. A developer, let's call her
+Jenny, can build CGAL from any CGAL branch accessible through a proper
+*source code management* (SCM) client, such as Git.
+
+This way Jenny can modify CGAL sources and test them without disturbing
+other developers and without disturbance from other developers, and at the
+same time keep (modified) CGAL sources in sync with an SCM repository and
+in turn with other developers. This documentation mainly discusses how to
+generate Unix Makefiles with CMake; however other generators are supported
+by CMake, too. In general, it is also advised to be familiar with the usual
+build procedure as the branch-build only selects another path to the main
+`CMakeLists.txt` file (i.e., picks it "from a branch" instead of "from a
+sources tarball").
+
+Example
+=======
+
+Assume that Jenny wants to try the new cool feature developed by Adam
+about coloring 2D triangulations. Adam is developing his feature in the
+branch `Triangulation_2-coloring-adam`. Jenny got a working copy of
+`next` (or of a different branch, e.g., any of her feature branches),
+e.g., by calling
+
+``` {.bash}
+ > cd /path/to/my/cgal_repository/
+ > git checkout Triangulation_2-coloring-adam
+ > git branch
+ master
+ * Triangulation_2-coloring-adam
+ ...
+```
+
+Jenny aims to compile a demo in that branch using the headers from the
+branch and the CGAL libraries built from the sources contained in the
+branch. Learn next how Jenny does it.
+
+Branch Build of CGAL
+====================
+
+Jenny has many options to use the *branch build* to build CGAL and then
+compile some examples. The build is categorized either as in-source or
+out-source. The former means that generated directories, generated
+files, and the sources are placed side by side. The latter means that
+generated directories and files are placed under a completely different
+directory, which, for example, can be removed when not needed without
+any impact on the sources. Among the different options, the in-source
+option is, while possible, less typical. Thus, it is not described here.
+
+Jenny can choose among three typical use-cases. Each case has advantages
+and disadvantages, and the preferred choice depends on how Jenny's daily
+work looks like.
+
+Preamble: Options for `cmake`
+-----------------------------
+
+All three have in common that Jenny might enhance the calls to `cmake`
+with platform-specific options or other flags as switching on or off
+components of CGAL, e.g.,
+
+``` {.bash}
+  -DWITH_CGAL_Core=ON -DWITH_CGAL_Qt3=OFF -DWITH_CGAL_Qt4=ON -DWITH_CGAL_ImageIO=ON -DWITH_examples=OFF -DWITH_demos=OFF
+```
+
+or configuring external libraries, e.g.,
+
+``` {.bash}
+ -DWITH_MPFI=ON -DWITH_RS=ON -DWITH_LEDA=ON -DLEDA_CXX_FLAGS=-ffriend-injection -DLEDA_INCLUDE_DIR=$EXACUS_LEDA/incl/ -DLEDA_LIBRARIES=$EXACUS_LEDA/libleda.so -DLEDA_LINKER_FLAGS=-lX11  
+```
+
+or any other option valid for `cmake`, e.g.
+
+``` {.bash}
+ -DCMAKE_BUILD_TYPE=Debug
+```
+
+All possible options and external libraries can be found in the
+[Installation
+manual](http://doc.cgal.org/latest/Manual/installation.html).
+So, assume next that Jenny knows the options according to her platform
+and liking when calling `cmake`. For simplicity, these options are not
+mentioned in the next examples.
+
+Those options can also be set using the CMake GUI `cmake-gui`.
+
+Building locally to the working copy
+------------------------------------
+
+Jenny can set `$CGAL_DIR` to `/path/to/my/cgal_repository/build`. It
+couples the sources and the build closer while still having an
+out-of-source-build.
+
+``` {.bash}
+  > mkdir /path/to/my/cgal_repository/build
+  > cd /path/to/my/cgal_repository/build
+  > cmake ..
+  > make
+  > export CGAL_DIR=/path/to/my/cgal_repository/build
+```
+
+Using a single version of CGAL
+------------------------------
+
+For many packages there is no trace of the package code in the CGAL
+library objects, as the entire code of the packages resides only in
+header files. As a matter of fact, the library objects themselves are
+very thin and thus building CGAL is a quick process and the generated
+library objects consume little space. In many cases it is sufficient to
+maintain a single version of CGAL at any time, for example, when only a
+single feature is developed, when several features are developed in
+parallel but the different corresponding branches can share a common
+version of CGAL, or when several features are developed in a single
+working directory and the corresponding branches are switched rarely. In
+such cases the environment variable <CGAL_DIR>, which points to the
+build target directory, is set once and never changes.
+
+Assume that Jenny would like to build CGAL from her local
+repositorylocated at `/path/to/my/cgal_repository` and place the result
+of the build in `~/CGAL/build`. She issue the following commands:
+
+``` {.bash}
+ > export CGAL_DIR=$HOME/CGAL/build
+ > cd $CGAL_DIR
+ > cmake /path/to/my/cgal_repository
+ > make
+```
+
+Using multiple versions of CGAL
+-------------------------------
+
+In this setup, Jenny develops several features and often switches
+between the corresponding branches in repository. She would like to keep
+a build version of CGAL for each of the features she is developing.
+Thus, for a branch `Triangulation_2-colored-adam` she builds CGAL in
+`~/CGAL/builds/Triangulation_2-colored-adam`.
+
+``` {.bash}
+  > mkdir ~/CGAL/builds/Triangulation_2-colored-adam
+  > cd ~/CGAL/builds/Triangulation_2-colored-adam
+  > cmake /path/to/my/cgal_repository
+  > make
+  > export CGAL_DIR=~/CGAL/builds/Triangulation_2-colored-adam
+```
+
+In such a setup she probably keeps a build of CGAL for each branch:
+
+``` {.bash}
+  > ls ~/CGAL/builds
+  Convex_hull_4-jenny
+  Convex_hull_2-make_it_faster-jenny
+```
+
+Jenny only has to set `$CGAL_DIR` to the build she wants to use before
+building a demo
+
+``` {.bash}
+   > export CGAL_DIR=~/CGAL/builds/Convex_hull_2-make_it_faster-jenny
+```
+
+Building Adam's demo
+====================
+
+Now with properly set `$CGAL_DIR` it's time for Jenny to build a demo
+contained from another branch in the local repository:
+
+``` {.bash}
+  > cd /path/to/my/cgal_repository/Triangulation_2/demo/Triangulation_2/
+  > git branch
+  master
+  * Triangulation_2-coloring-adam
+  ...
+  > ls
+  CMakeLists.txt colored_t2.cpp
+```
+
+It might be required to generate the file `CMakeLists.txt`. This can be
+done with the script [`cgal_create_cmake_script`](Scripts/scripts/cgal_create_cmake_script)
+found in `/path/to/my/cgal/Scripts/scripts/`. Then call:
+
+``` {.bash}
+  > cmake .
+  > make
+  > ./colored_t2
+```
+
+'''The important fact is that all headers are taken from the workingcopy
+that have been used while building CGAL in the current `$CGAL_DIR`.
+
+Remarks on this:
+
+-   A build may be outdated after an include/dir has been deleted,
+    switched or even updated. This might lead to compile problems (link
+    with outdated version). Thus, it is recommended to build CGAL after
+    each update, switch, merge of a branch (in particular if directories
+    have been added/deleted, or cpp files have been added, deleted or
+    altered).
+-   There is currently no warning that a build does not match the
+    branch. However, a little experience helps to be aware of this
+    problem.
+-   It might be possible to add such a warning (work in progress).
+
+Finally, she's happy about Adam's cute pictures.
+
+No installation required
+========================
+
+When you install CGAL (using `make install`), you copy all generated
+library-objects and header files from the branch to a predefined
+directory, `CMAKE_INSTALLATION_PREFIX`. Then, if you want to use the
+installed version, you need to set
+`$CGAL_DIR=$CMAKE_INSTALLATION_PREFIX` accordingly, thereby detaching
+the installed files from the branch and loosing the connection to the
+source-code management system. For most purposes there is no need to
+install CGAL.

Installation/INSTALL.md

@@ -1,17 +1,13 @@
-INSTALL
--------------------------------------------------------------------------------
-
-
 INTRODUCTION
 ============
 
 This file describes how to install CGAL. The instructions in this file
-are for the most common use cases, and cover the command line tools. 
+are for the most common use cases, and cover the command line tools.
 
 For further information, or in case of problems, please see the
 detailed installation instructions, which can be found in this
 distribution in the file ./doc_html/index.html or on the CGAL website
-http://www.cgal.org/Manual/latest/doc_html/cgal_manual/Installation/Chapter_main.html
+http://doc.cgal.org/latest/Manual/installation.html
 
 The documentation of CGAL is available in PDF and HTML formats.
 It is not bundled with the software but can be downloaded separately
@@ -26,8 +22,8 @@ of CGAL (3.5.1, 3.6, and so on).
 PREREQUISITES
 =============
 
-To install CGAL, you need 'cmake' and several third-party libraries. 
+To install CGAL, you need 'cmake' and several third-party libraries.
-Some are essential for entire CGAL, some are mandatory for particular 
+Some are essential for entire CGAL, some are mandatory for particular
 CGAL packages, some are only needed for demos.
 
    * CMake (>= 2.6.2), the build system used by CGAL
@@ -42,7 +38,7 @@ CGAL packages, some are only needed for demos.
      You need the former if you plan to compile the boost libraries yourself,
      for example because you target 64 bit applications for XP64
 
-   * Exact Arithmetic           
+   * Exact Arithmetic
      CGAL combines floating point arithmetic with exact arithmetic, in order
      to be fast and reliable. CGAL offers support for GMP and MPFR, for LEDA
      exact number types, as well as a built-in exact number type used when
@@ -62,7 +58,7 @@ CGAL packages, some are only needed for demos.
      - LEDA (>= 6.2)
        http://www.algorithmic-solutions.com/leda/index.htm
 
-   * Visualization 
+   * Visualization
      Required for most demos
 
      - Qt3 (>= 3.3)
@@ -83,10 +79,10 @@ CGAL packages, some are only needed for demos.
        Required by the packages:
        o Estimation of Local Differential Properties of Point-Sampled Surfaces
        o Approximation of Ridges and Umbilics on Triangulated Surface Meshes
-       o Planar Parameterization of Triangulated Surface Meshes       
+       o Planar Parameterization of Triangulated Surface Meshes
-       o Surface Reconstruction from Point Sets 
+       o Surface Reconstruction from Point Sets
        http://eigen.tuxfamily.org
-       
+
      - BLAS, LAPACK, ATLAS
        Required by the packages (if EIGEN is not available):
        o Estimation of Local Differential Properties of Point-Sampled Surfaces
@@ -98,7 +94,7 @@ CGAL packages, some are only needed for demos.
      - MPFI
        Required by the package:
        o Algebraic Kernel
-       https://gforge.inria.fr/projects/mpfi/ 
+       https://gforge.inria.fr/projects/mpfi/
        (or shipped with RS http://vegas.loria.fr/rs/)
 
      - RS (root isolation)
@@ -111,10 +107,10 @@ CGAL packages, some are only needed for demos.
        o Polynomial
        o Algebraic Kernel
        http://www.shoup.net/ntl/
- 
+
    * Miscellaneous
 
-     - zlib         
+     - zlib
        Optional for the package:
        o Surface Mesh Generator can read compressed images directly
        http://www.zlib.net/
@@ -129,24 +125,24 @@ CONFIGURATION
 =============
 
 To configure CGAL, type
-
+```
   cmake .
-
+```
 in the directory that contains this INSTALL file. You can add several options
 to this command. The most important ones are
 
-  -DCMAKE_INSTALL_PREFIX=<dir>          installation directory [/usr/local]
+* `-DCMAKE_INSTALL_PREFIX=<dir>`          installation directory [/usr/local]
-  -DCMAKE_BUILD_TYPE=<Debug|Release>    build type [Release]
+* `-DCMAKE_BUILD_TYPE=<Debug|Release>`    build type [Release]
-  -DBUILD_SHARED_LIBS=<TRUE|FALSE>      shared or static libraries [TRUE]
+* `-DBUILD_SHARED_LIBS=<TRUE|FALSE>`      shared or static libraries [TRUE]
-  -DCMAKE_C_COMPILER=<program>          C compiler [gcc]
+* `-DCMAKE_C_COMPILER=<program>`          C compiler [gcc]
-  -DCMAKE_CXX_COMPILER=<program>        C++ compiler [g++]
+* `-DCMAKE_CXX_COMPILER=<program>`        C++ compiler [g++]
 
 In case you want to add additional compiler and linker flags, you can use
 
-  -DCGAL_CXX_FLAGS                      additional compiler flags
+* `-DCGAL_CXX_FLAGS`                      additional compiler flags
-  -DCGAL_MODULE_LINKER_FLAGS            add. linker flags (static libraries)
+* `-DCGAL_MODULE_LINKER_FLAGS`            add. linker flags (static libraries)
-  -DCGAL_SHARED_LINKER_FLAGS            add. linker flags (shared libraries)
+* `-DCGAL_SHARED_LINKER_FLAGS`            add. linker flags (shared libraries)
-  -DCGAL_EXE_LINKER_FLAGS               add. linker flags (executables)
+* `-DCGAL_EXE_LINKER_FLAGS`               add. linker flags (executables)
 
 Variants with the additional suffix "_DEBUG" and "_RELEASE" allow to set
 separate values for debug and release builds. In case you do not want to add
@@ -154,12 +150,12 @@ additional flags, but to override the default flags, replace "CGAL" by
 "CMAKE" in the variable names above.
 
 By default demos and examples are not configured. If you want to configure
-them at the same time as the CGAL library, you can use 
+them at the same time as the CGAL library, you can use
 
-  -DWITH_examples=true
+*  `-DWITH_examples=true`
-  -DWITH_demos=true
+*  `-DWITH_demos=true`
 
-Note that CMake maintains a cache name "CMakeCache.txt". If you change options
+Note that CMake maintains a cache name `CMakeCache.txt`. If you change options
 (or your environment changes), it is best to remove that file to avoid
 problems.
 
@@ -168,28 +164,29 @@ BUILDING
 ========
 
 To build the CGAL libraries, type
-
+```
-  make                               (or nmake in a Windows command prompt)
+  make
-
+```
+(or nmake in a Windows command prompt).
 If you want, you can install the CGAL header and libraries. To do so, type
-
+```
   make install
-
+```
 You can build all demos or examples by typing
-
+```
-  make demos                          or
+  make demos
   make examples
-
+```
 If you are interested in the demos or examples of just a particular module,
 you can build them in the following way:
-
+```
   make -C demo/Alpha_shapes_2        (or: cd demo/Alpha_shapes_2; make)
   make -C examples/Alpha_shapes_2    (or: cd examples/Alpha_shapes_2; make)
-
+```
 A list of all available make targets can be obtained by
-
+```
   make help
-
+```
 
 OUT-OF-SOURCE BUILDS
 ====================
@@ -201,10 +198,10 @@ configurations (debug and release, different compilers, and so on). Using
 different build directories keeps all the generated files separated for each
 configuration.
 
-In the following, $CGAL_SRC denotes the directory with the CGAL sources;
+In the following, `$CGAL_SRC` denotes the directory with the CGAL sources;
-$CGAL_BUILD is an arbitrary directory where the generated files will be
+`$CGAL_BUILD` is an arbitrary directory where the generated files will be
 placed. You can perform an out-of-source build as follows:
-
+```
   mkdir $CGAL_BUILD
   cd $CGAL_BUILD
   cmake [options] $CGAL_SRC
@@ -212,7 +209,7 @@ placed. You can perform an out-of-source build as follows:
   make install                       (if desired)
   make demos                         (if desired)
   make examples                      (if desired)
-
+```
-Basically, the only difference is the last parameter of the "cmake" command:
+Basically, the only difference is the last parameter of the `cmake` command:
-$CGAL_SRC instead of "." .
+`$CGAL_SRC` instead of `.` .
 

Installation/README

@@ -6,7 +6,7 @@ This distribution of CGAL includes:
   AUTHORS          - current and former authors of CGAL
   CHANGES          - history of changes for the library
   CMakeLists.txt   - main script of the build system
-  INSTALL          - information about the installation process 
+  INSTALL.md       - information about the installation process
   LICENSE          - describes the license of CGAL
   LICENSE.FREE_USE - text of the free use license (see LICENSE file)
   LICENSE.GPL      - text of  GPL v3 license

README.md

@@ -0,0 +1,48 @@
+#![CGAL](Installation/doc_html/images/cgal_2013_grey.png)
+
+The Computational Geometry Algorithms Library (CGAL) is a C++ library that
+aims to provide easy access to efficient and reliable algorithms in
+computational geometry.
+
+CGAL releases
+=============
+The primary vector of distribution of CGAL are sources tarballs, released
+twice a year, announced on [the web site of CGAL](http://www.cgal.org/).
+The sources distributed that way can be built using the
+[CGAL installation manual](http://doc.cgal.org/latest/Manual/installation.html).
+
+CGAL Git repository layout
+==========================
+
+The Git repository of CGAL has a different layout from release tarballs. It
+contains a `CMakeLists.txt` file that serves as anchor for building, and a
+set of subfolders, so called *packages* (packages have their own
+[certain structure](Directory_Structure_for_Packages.md). Most packages
+implement a data structure or an algorithm for CGAL (e.g., `Convex_hull_2`,
+or `Triangulation_3`); however some packages serve special needs:
+
+* `Installation` - meta-files and CMake-support
+* `Maintenance` - infrastructural support
+* `Core`, `CGALimageIO`, `Qt_widget`, `GraphicsView` - component libraries
+* `Scripts` - scripts to simplify developer's and user's work
+* `Testsuite` - infrastructure for testsuite
+* `Documentation` - infrastructure for CGAL's manual
+* `STL_Extension` - extensions to the standard template library
+
+Compilation and installation
+============================
+The compilation and installation of CGAL from a sources tarball is
+described in the
+[CGAL installation manual](http://doc.cgal.org/latest/Manual/installation.html)
+and in the file [INSTALL.md](Installation/INSTALL.md) that is at the root
+of any sources tarball.
+
+CGAL developers, however, usually compile CGAL directly from a local Git
+repository. That kind of compilation is called a *branch build*, and is
+described in the file [INSTALL.md](INSTALL.md) that is at the root of the
+Git repository.
+
+More information
+================
+* [The CGAL web site](http://www.cgal.org/)
+* [Lastest CGAL release documentation pages](http://doc.cgal.org/)