Help: Organize and revise the cmake-generators.7 manual

Move "extra" generators to their own section instead of duplicating them
for each corresponding main generator.  Divide the list of main
generators into command-line and IDE sections and sort the names within
each section.  Document the environment from which each kind of
generator may be used.

Add a section to each "extra" generator documenting which main
generators may be used with it.

Help/generator/CodeBlocks - NMake Makefiles.rst

@@ -1,11 +0,0 @@
-CodeBlocks - NMake Makefiles
-----------------------------
-
-Generates CodeBlocks project files.
-
-Project files for CodeBlocks will be created in the top directory and
-in every subdirectory which features a CMakeLists.txt file containing
-a PROJECT() call.  Additionally a hierarchy of makefiles is generated
-into the build tree.  The appropriate make program can build the
-project through the default make target.  A "make install" target is
-also provided.

Help/generator/CodeBlocks - Ninja.rst

@@ -1,11 +0,0 @@
-CodeBlocks - Ninja
-------------------
-
-Generates CodeBlocks project files.
-
-Project files for CodeBlocks will be created in the top directory and
-in every subdirectory which features a CMakeLists.txt file containing
-a PROJECT() call.  Additionally a hierarchy of makefiles is generated
-into the build tree.  The appropriate make program can build the
-project through the default make target.  A "make install" target is
-also provided.

Help/generator/CodeBlocks - Unix Makefiles.rst

@@ -1,11 +0,0 @@
-CodeBlocks - Unix Makefiles
----------------------------
-
-Generates CodeBlocks project files.
-
-Project files for CodeBlocks will be created in the top directory and
-in every subdirectory which features a CMakeLists.txt file containing
-a PROJECT() call.  Additionally a hierarchy of makefiles is generated
-into the build tree.  The appropriate make program can build the
-project through the default make target.  A "make install" target is
-also provided.

Help/generator/CodeBlocks.rst

@@ -1,5 +1,5 @@
-CodeBlocks - MinGW Makefiles
+CodeBlocks
-----------------------------
+----------
 
 Generates CodeBlocks project files.
 
@@ -9,3 +9,17 @@ a PROJECT() call.  Additionally a hierarchy of makefiles is generated
 into the build tree.  The appropriate make program can build the
 project through the default make target.  A "make install" target is
 also provided.
+
+This "extra" generator may be specified as:
+
+``CodeBlocks - MinGW Makefiles``
+ Generate with :generator:`MinGW Makefiles`.
+
+``CodeBlocks - NMake Makefiles``
+ Generate with :generator:`NMake Makefiles`.
+
+``CodeBlocks - Ninja``
+ Generate with :generator:`Ninja`.
+
+``CodeBlocks - Unix Makefiles``
+ Generate with :generator:`Unix Makefiles`.

Help/generator/Eclipse CDT4 - NMake Makefiles.rst

@@ -1,11 +0,0 @@
-Eclipse CDT4 - NMake Makefiles
-------------------------------
-
-Generates Eclipse CDT 4.0 project files.
-
-Project files for Eclipse will be created in the top directory.  In
-out of source builds, a linked resource to the top level source
-directory will be created.  Additionally a hierarchy of makefiles is
-generated into the build tree.  The appropriate make program can build
-the project through the default make target.  A "make install" target
-is also provided.

Help/generator/Eclipse CDT4 - Ninja.rst

@@ -1,11 +0,0 @@
-Eclipse CDT4 - Ninja
---------------------
-
-Generates Eclipse CDT 4.0 project files.
-
-Project files for Eclipse will be created in the top directory.  In
-out of source builds, a linked resource to the top level source
-directory will be created.  Additionally a hierarchy of makefiles is
-generated into the build tree.  The appropriate make program can build
-the project through the default make target.  A "make install" target
-is also provided.

Help/generator/Eclipse CDT4 - Unix Makefiles.rst

@@ -1,11 +0,0 @@
-Eclipse CDT4 - Unix Makefiles
------------------------------
-
-Generates Eclipse CDT 4.0 project files.
-
-Project files for Eclipse will be created in the top directory.  In
-out of source builds, a linked resource to the top level source
-directory will be created.  Additionally a hierarchy of makefiles is
-generated into the build tree.  The appropriate make program can build
-the project through the default make target.  A "make install" target
-is also provided.

Help/generator/Eclipse CDT4.rst

@@ -1,5 +1,5 @@
-Eclipse CDT4 - MinGW Makefiles
+Eclipse CDT4
-------------------------------
+------------
 
 Generates Eclipse CDT 4.0 project files.
 
@@ -9,3 +9,17 @@ directory will be created.  Additionally a hierarchy of makefiles is
 generated into the build tree.  The appropriate make program can build
 the project through the default make target.  A "make install" target
 is also provided.
+
+This "extra" generator may be specified as:
+
+``Eclipse CDT4 - MinGW Makefiles``
+ Generate with :generator:`MinGW Makefiles`.
+
+``Eclipse CDT4 - NMake Makefiles``
+ Generate with :generator:`NMake Makefiles`.
+
+``Eclipse CDT4 - Ninja``
+ Generate with :generator:`Ninja`.
+
+``Eclipse CDT4 - Unix Makefiles``
+ Generate with :generator:`Unix Makefiles`.

Help/generator/KDevelop3 - Unix Makefiles.rst

@@ -1,13 +0,0 @@
-KDevelop3 - Unix Makefiles
---------------------------
-
-Generates KDevelop 3 project files.
-
-Project files for KDevelop 3 will be created in the top directory and
-in every subdirectory which features a CMakeLists.txt file containing
-a PROJECT() call.  If you change the settings using KDevelop cmake
-will try its best to keep your changes when regenerating the project
-files.  Additionally a hierarchy of UNIX makefiles is generated into
-the build tree.  Any standard UNIX-style make program can build the
-project through the default make target.  A "make install" target is
-also provided.

Help/generator/KDevelop3.rst

@@ -11,3 +11,15 @@ files.  Additionally a hierarchy of UNIX makefiles is generated into
 the build tree.  Any standard UNIX-style make program can build the
 project through the default make target.  A "make install" target is
 also provided.
+
+This "extra" generator may be specified as:
+
+``KDevelop3 - Unix Makefiles``
+ Generate with :generator:`Unix Makefiles`.
+
+``KDevelop3``
+ Generate with :generator:`Unix Makefiles`.
+
+ For historical reasons this extra generator may be specified
+ directly as the main generator and it will be used as the
+ extra generator with :generator:`Unix Makefiles` automatically.

Help/generator/Sublime Text 2 - NMake Makefiles.rst

@@ -1,11 +0,0 @@
-Sublime Text 2 - NMake Makefiles
---------------------------------
-
-Generates Sublime Text 2 project files.
-
-Project files for Sublime Text 2 will be created in the top directory
-and in every subdirectory which features a CMakeLists.txt file
-containing a PROJECT() call.  Additionally Makefiles (or build.ninja
-files) are generated into the build tree.  The appropriate make
-program can build the project through the default make target.  A
-"make install" target is also provided.

Help/generator/Sublime Text 2 - Ninja.rst

@@ -1,11 +0,0 @@
-Sublime Text 2 - Ninja
-----------------------
-
-Generates Sublime Text 2 project files.
-
-Project files for Sublime Text 2 will be created in the top directory
-and in every subdirectory which features a CMakeLists.txt file
-containing a PROJECT() call.  Additionally Makefiles (or build.ninja
-files) are generated into the build tree.  The appropriate make
-program can build the project through the default make target.  A
-"make install" target is also provided.

Help/generator/Sublime Text 2 - Unix Makefiles.rst

@@ -1,11 +0,0 @@
-Sublime Text 2 - Unix Makefiles
--------------------------------
-
-Generates Sublime Text 2 project files.
-
-Project files for Sublime Text 2 will be created in the top directory
-and in every subdirectory which features a CMakeLists.txt file
-containing a PROJECT() call.  Additionally Makefiles (or build.ninja
-files) are generated into the build tree.  The appropriate make
-program can build the project through the default make target.  A
-"make install" target is also provided.

Help/generator/Sublime Text 2.rst

@@ -1,5 +1,5 @@
-Sublime Text 2 - MinGW Makefiles
+Sublime Text 2
---------------------------------
+--------------
 
 Generates Sublime Text 2 project files.
 
@@ -9,3 +9,17 @@ containing a PROJECT() call.  Additionally Makefiles (or build.ninja
 files) are generated into the build tree.  The appropriate make
 program can build the project through the default make target.  A
 "make install" target is also provided.
+
+This "extra" generator may be specified as:
+
+``Sublime Text 2 - MinGW Makefiles``
+ Generate with :generator:`MinGW Makefiles`.
+
+``Sublime Text 2 - NMake Makefiles``
+ Generate with :generator:`NMake Makefiles`.
+
+``Sublime Text 2 - Ninja``
+ Generate with :generator:`Ninja`.
+
+``Sublime Text 2 - Unix Makefiles``
+ Generate with :generator:`Unix Makefiles`.

Help/manual/cmake-generators.7.rst

@@ -7,40 +7,78 @@ cmake-generators(7)
 
    .. contents::
 
-All Generators
+Introduction
-==============
+============
+
+A *CMake Generator* is responsible for writing the input files for
+a native build system.  Exactly one of the `CMake Generators`_ must be
+selected for a build tree to determine what native build system is to
+be used.  Optionally one of the `Extra Generators`_ may be selected
+as a variant of some of the `Command-Line Build Tool Generators`_ to
+produce project files for an auxiliary IDE.
+
+CMake Generators are platform-specific so each may be available only
+on certain platforms.  The :manual:`cmake(1)` command-line tool ``--help``
+output lists available generators on the current platform.  Use its ``-G``
+option to specify the generator for a new build tree.
+The :manual:`cmake-gui(1)` offers interactive selection of a generator
+when creating a new build tree.
+
+CMake Generators
+================
+
+Command-Line Build Tool Generators
+----------------------------------
+
+These generators support command-line build tools.  In order to use them,
+one must launch CMake from a command-line prompt whose environment is
+already configured for the chosen compiler and build tool.
 
 .. toctree::
    :maxdepth: 1
 
    /generator/Borland Makefiles
-   /generator/CodeBlocks - MinGW Makefiles
-   /generator/CodeBlocks - Ninja
-   /generator/CodeBlocks - NMake Makefiles
-   /generator/CodeBlocks - Unix Makefiles
-   /generator/Eclipse CDT4 - MinGW Makefiles
-   /generator/Eclipse CDT4 - Ninja
-   /generator/Eclipse CDT4 - NMake Makefiles
-   /generator/Eclipse CDT4 - Unix Makefiles
-   /generator/KDevelop3
-   /generator/KDevelop3 - Unix Makefiles
-   /generator/MinGW Makefiles
    /generator/MSYS Makefiles
-   /generator/Ninja
+   /generator/MinGW Makefiles
-   /generator/NMake Makefiles JOM
    /generator/NMake Makefiles
-   /generator/Sublime Text 2 - MinGW Makefiles
+   /generator/NMake Makefiles JOM
-   /generator/Sublime Text 2 - Ninja
+   /generator/Ninja
-   /generator/Sublime Text 2 - NMake Makefiles
-   /generator/Sublime Text 2 - Unix Makefiles
    /generator/Unix Makefiles
+   /generator/Watcom WMake
+
+IDE Build Tool Generators
+-------------------------
+
+These generators support Integrated Development Environment (IDE)
+project files.  Since the IDEs configure their own environment
+one may launch CMake from any environment.
+
+.. toctree::
+   :maxdepth: 1
+
+   /generator/Visual Studio 6
+   /generator/Visual Studio 7
+   /generator/Visual Studio 7 .NET 2003
+   /generator/Visual Studio 8 2005
+   /generator/Visual Studio 9 2008
    /generator/Visual Studio 10 2010
    /generator/Visual Studio 11 2012
    /generator/Visual Studio 12 2013
-   /generator/Visual Studio 6
-   /generator/Visual Studio 7 .NET 2003
-   /generator/Visual Studio 7
-   /generator/Visual Studio 8 2005
-   /generator/Visual Studio 9 2008
-   /generator/Watcom WMake
    /generator/Xcode
+
+Extra Generators
+================
+
+Some of the `CMake Generators`_ listed in the :manual:`cmake(1)`
+command-line tool ``--help`` output may have variants that specify
+an extra generator for an auxiliary IDE tool.  Such generator
+names have the form ``<extra-generator> - <main-generator>``.
+The following extra generators are known to CMake.
+
+.. toctree::
+   :maxdepth: 1
+
+   /generator/CodeBlocks
+   /generator/Eclipse CDT4
+   /generator/KDevelop3
+   /generator/Sublime Text 2