Merge pull request #4304 from MaelRL/CGAL-Header_only_doc_rewrite-GF

Documentation: switch manual to header-only by default (+misc improvements)

Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt

@@ -236,8 +236,8 @@ operating system and compiler that is defined as follows.
   quite compiler specific).
 </DL>
 
-Examples are <TT>mips_IRIX64-6.5_CC-n32-7.30</TT> or <TT>sparc_SunOS-5.6_g++-2.95</TT>. For more information, see the \cgal 
-\link installation installation guide \endlink.
+Examples are <TT>mips_IRIX64-6.5_CC-n32-7.30</TT> or <TT>sparc_SunOS-5.6_g++-2.95</TT>.
+For more information, see the \cgal \link usage usage guide \endlink.
 
 This platform-specific configuration file is created during
 

Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt

@@ -0,0 +1,40 @@
+/*!
+
+\page devman_create_cgal_CMakeLists Creating a CMake Script for a Program Using %CGAL
+
+To compile a program that is not shipped with \cgal, it is recommended to also rely on a CMake-supported
+configuration using a `CMakeLists.txt`. The Bourne-shell script `cgal_create_CMakeLists.txt`
+can be used to create such `CMakeLists.txt` files.
+This script resides in the `scripts` directory of \cgal (e.g. `CGAL-\cgalReleaseNumber``/scripts`
+directory if you have downloaded a tarball).
+Executing `cgal_create_CMakeLists.txt` in an application directory creates a
+`CMakeLists.txt` containing rules to build the contained
+application(s). Three command line options determine details of the
+configuration.
+
+<DL>
+<DT><B>`-s source`</B><DD> If this parameter is given the script will
+create <B>a single executable</B> for 'source' linked with
+compilations of all other source files
+(`*.cc`, `*.cp`, `*.cxx`, `*.cpp`, `*.CPP`, `*.c++`, or `*.C`).
+This behaviour is usually needed for (graphical) demos.
+
+If the parameter is not given, the script creates <B>one executable for each given
+source file</B>.
+<DT><B>`-c com1:com2:...`</B><DD> Lists components ("com1",
+"com2") of \cgal to which the executable(s) should be linked. Valid components are \cgal's
+libraries (i.e.\ "Core", "ImageIO", and "Qt5"). An example is `-c Core`.
+
+<DT><B>`-b boost1:boost2:...`</B><DD> Lists components ("boost1",
+"boost2") of \sc{Boost} to which the executable(s) should be
+linked. Valid options are, for instance, "filesystem" or "program_options".
+
+</DL>
+
+This options should suffice to create `CMakeLists.txt` script
+for most directories containing programs. However, in some special
+cases, it might still be required to create the script manually, for
+instance, if some source files/executables need a different linking than
+other source files.
+
+*/

Documentation/doc/Documentation/Developer_manual/developer_manual.txt

@@ -2,6 +2,8 @@
 
 \page dev_manual Developer Manual
 
+The developer manual is primarly aimed at \cgal developers, but may also be interesting to any \cgal user.
+
 - \subpage devman_intro
 - \subpage devman_code_format
 - \subpage devman_kernels
@@ -19,6 +21,6 @@
 - \subpage devman_testing
 - \subpage devman_submission
 - \subpage devman_info
+- \subpage devman_create_cgal_CMakeLists
 - \subpage deprecated
-
 */

Documentation/doc/Documentation/Getting_started.txt

@@ -1,13 +1,30 @@
 /*!
-\page general_intro Getting Started
+\page general_intro Getting Started with %CGAL
 
-- \subpage installation describes how to install %CGAL, and lists the third party libraries on which %CGAL depends, or for which %CGAL provides interfaces. 
+The following pages describe how to use \cgal on different environments
 
-- \subpage manual gives an idea where you should look for documentation.
-  The documentation for a class, may be spread over manual pages of
-  base classes, and reference manual pages of concepts the class is a model of.
-
+- \subpage usage
 
-- \subpage preliminaries lists the licenses under which the %CGAL datastructures and algorithms are distributed, how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior. 
+- \subpage windows
+
+- \subpage thirdparty gives information (supported versions, download links) of the required and optional third party libraries.
+
+The following pages cover advanced installation options
+
+- \subpage configurationvariables gives information about which CMake variables can be used to help
+resolve missing dependencies while using the cmake command line tool.
+
+- \subpage installation describes the deprecated process of configuring and building \cgal.
+
+The following pages cover the structure of the manual and general information about \cgal
+
+- \subpage manual gives an idea of where you should look for documentation.
+
+- \subpage preliminaries lists how to control inlining, thread safety, code deprecation, checking
+of pre- and postconditions, and how to alter the failure behavior.
+
+Once you are familiar with building your programs with \cgal and how the documentation is structured,
+you can head over to the \ref tutorials for a gentle introduction to \cgal, or directly to the package(s)
+that interest you the \ref packages. Each package contains simple examples of the various functionalities of the package.
 
 */