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.

1 files changed, 62 insertions, 24 deletions

diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst
index ec1f58a..93fbf77 100644
--- a/Help/manual/cmake-generators.7.rst
+++ b/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/NMake Makefiles JOM
+   /generator/MinGW Makefiles
    /generator/NMake Makefiles
-   /generator/Sublime Text 2 - MinGW Makefiles
-   /generator/Sublime Text 2 - Ninja
-   /generator/Sublime Text 2 - NMake Makefiles
-   /generator/Sublime Text 2 - Unix Makefiles
+   /generator/NMake Makefiles JOM
+   /generator/Ninja
    /generator/Unix Makefiles
-   /generator/Visual Studio 10 2010
-   /generator/Visual Studio 11 2012
-   /generator/Visual Studio 12 2013
+   /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 .NET 2003
    /generator/Visual Studio 7
+   /generator/Visual Studio 7 .NET 2003
    /generator/Visual Studio 8 2005
    /generator/Visual Studio 9 2008
-   /generator/Watcom WMake
+   /generator/Visual Studio 10 2010
+   /generator/Visual Studio 11 2012
+   /generator/Visual Studio 12 2013
    /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