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.

14 files changed, 60 insertions, 118 deletions

diff --git a/Help/generator/CodeBlocks - NMake Makefiles.rst b/Help/generator/CodeBlocks - NMake Makefiles.rst
deleted file mode 100644
index c7f944a..0000000
--- a/Help/generator/CodeBlocks - NMake Makefiles.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/CodeBlocks - Ninja.rst b/Help/generator/CodeBlocks - Ninja.rst
deleted file mode 100644
index 0253af6..0000000
--- a/Help/generator/CodeBlocks - Ninja.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/CodeBlocks - Unix Makefiles.rst b/Help/generator/CodeBlocks - Unix Makefiles.rst
deleted file mode 100644
index 0a29835..0000000
--- a/Help/generator/CodeBlocks - Unix Makefiles.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/CodeBlocks - MinGW Makefiles.rst b/Help/generator/CodeBlocks.rst
index f54eb11..01798c7 100644
--- a/Help/generator/CodeBlocks - MinGW Makefiles.rst
+++ b/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`.
diff --git a/Help/generator/Eclipse CDT4 - NMake Makefiles.rst b/Help/generator/Eclipse CDT4 - NMake Makefiles.rst
deleted file mode 100644
index b5133ad..0000000
--- a/Help/generator/Eclipse CDT4 - NMake Makefiles.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/Eclipse CDT4 - Ninja.rst b/Help/generator/Eclipse CDT4 - Ninja.rst
deleted file mode 100644
index 270011f..0000000
--- a/Help/generator/Eclipse CDT4 - Ninja.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/Eclipse CDT4 - Unix Makefiles.rst b/Help/generator/Eclipse CDT4 - Unix Makefiles.rst
deleted file mode 100644
index c3449a7..0000000
--- a/Help/generator/Eclipse CDT4 - Unix Makefiles.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/Eclipse CDT4 - MinGW Makefiles.rst b/Help/generator/Eclipse CDT4.rst
index 9e7a26e..eb68bf0 100644
--- a/Help/generator/Eclipse CDT4 - MinGW Makefiles.rst
+++ b/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`.
diff --git a/Help/generator/KDevelop3 - Unix Makefiles.rst b/Help/generator/KDevelop3 - Unix Makefiles.rst
deleted file mode 100644
index 2a29a2e..0000000
--- a/Help/generator/KDevelop3 - Unix Makefiles.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/KDevelop3.rst b/Help/generator/KDevelop3.rst
index 788d557..eaa218b 100644
--- a/Help/generator/KDevelop3.rst
+++ b/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.
diff --git a/Help/generator/Sublime Text 2 - NMake Makefiles.rst b/Help/generator/Sublime Text 2 - NMake Makefiles.rst
deleted file mode 100644
index 5e02fd4..0000000
--- a/Help/generator/Sublime Text 2 - NMake Makefiles.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/Sublime Text 2 - Ninja.rst b/Help/generator/Sublime Text 2 - Ninja.rst
deleted file mode 100644
index b7a2b88..0000000
--- a/Help/generator/Sublime Text 2 - Ninja.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/Sublime Text 2 - Unix Makefiles.rst b/Help/generator/Sublime Text 2 - Unix Makefiles.rst
deleted file mode 100644
index 67d329e..0000000
--- a/Help/generator/Sublime Text 2 - Unix Makefiles.rst
+++ /dev/null
@@ -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.
diff --git a/Help/generator/Sublime Text 2 - MinGW Makefiles.rst b/Help/generator/Sublime Text 2.rst
index 6e2ed02..0597a95 100644
--- a/Help/generator/Sublime Text 2 - MinGW Makefiles.rst
+++ b/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`.