Help: Suggest using -A to specify platform for VS generators

We already suggest `-T` for the toolset.  Create a dedicated section for
platform selection and suggest `-A`.  Provide examples.

6 files changed, 119 insertions, 60 deletions

diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst
index b8d6872..0446b8c 100644
--- a/Help/generator/Visual Studio 10 2010.rst
+++ b/Help/generator/Visual Studio 10 2010.rst
@@ -3,18 +3,6 @@ Visual Studio 10 2010
 
 Generates Visual Studio 10 (VS 2010) project files.
 
-The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name (architecture).
-
-For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of this generator name:
-
-``Visual Studio 10 2010 Win64``
-  Specify target platform ``x64``.
-
-``Visual Studio 10 2010 IA64``
-  Specify target platform ``Itanium``.
-
 For compatibility with CMake versions prior to 3.0, one may specify this
 generator using the name ``Visual Studio 10`` without the year component.
 
@@ -24,6 +12,27 @@ Project Types
 Only Visual C++ and C# projects may be generated.  Other types of
 projects (Database, Website, etc.) are not supported.
 
+Platform Selection
+^^^^^^^^^^^^^^^^^^
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+name (architecture).  For example:
+
+* ``cmake -G "Visual Studio 10 2010" -A Win32``
+* ``cmake -G "Visual Studio 10 2010" -A x64``
+* ``cmake -G "Visual Studio 10 2010" -A Itanium``
+
+For compatibility with CMake versions prior to 3.1, one may specify
+a target platform name optionally at the end of the generator name.
+This is supported only for:
+
+``Visual Studio 10 2010 Win64``
+  Specify target platform ``x64``.
+
+``Visual Studio 10 2010 IA64``
+  Specify target platform ``Itanium``.
+
 Toolset Selection
 ^^^^^^^^^^^^^^^^^
 
diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst
index 8e9998a..8fddbb3 100644
--- a/Help/generator/Visual Studio 11 2012.rst
+++ b/Help/generator/Visual Studio 11 2012.rst
@@ -3,11 +3,31 @@ Visual Studio 11 2012
 
 Generates Visual Studio 11 (VS 2012) project files.
 
-The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name (architecture).
+For compatibility with CMake versions prior to 3.0, one may specify this
+generator using the name "Visual Studio 11" without the year component.
+
+Project Types
+^^^^^^^^^^^^^
+
+Only Visual C++ and C# projects may be generated.  Other types of
+projects (JavaScript, Database, Website, etc.) are not supported.
+
+Platform Selection
+^^^^^^^^^^^^^^^^^^
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+name (architecture).  For example:
+
+* ``cmake -G "Visual Studio 11 2012" -A Win32``
+* ``cmake -G "Visual Studio 11 2012" -A x64``
+* ``cmake -G "Visual Studio 11 2012" -A ARM``
+* ``cmake -G "Visual Studio 11 2012" -A <WinCE-SDK>``
+  (Specify a target platform matching a Windows CE SDK name.)
 
 For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of this generator name:
+a target platform name optionally at the end of the generator name.
+This is supported only for:
 
 ``Visual Studio 11 2012 Win64``
   Specify target platform ``x64``.
@@ -18,15 +38,6 @@ a target platform name optionally at the end of this generator name:
 ``Visual Studio 11 2012 <WinCE-SDK>``
   Specify target platform matching a Windows CE SDK name.
 
-For compatibility with CMake versions prior to 3.0, one may specify this
-generator using the name "Visual Studio 11" without the year component.
-
-Project Types
-^^^^^^^^^^^^^
-
-Only Visual C++ and C# projects may be generated.  Other types of
-projects (JavaScript, Database, Website, etc.) are not supported.
-
 Toolset Selection
 ^^^^^^^^^^^^^^^^^
 
diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst
index 03f7586..8b4c162 100644
--- a/Help/generator/Visual Studio 12 2013.rst
+++ b/Help/generator/Visual Studio 12 2013.rst
@@ -3,18 +3,6 @@ Visual Studio 12 2013
 
 Generates Visual Studio 12 (VS 2013) project files.
 
-The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name (architecture).
-
-For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of this generator name:
-
-``Visual Studio 12 2013 Win64``
-  Specify target platform ``x64``.
-
-``Visual Studio 12 2013 ARM``
-  Specify target platform ``ARM``.
-
 For compatibility with CMake versions prior to 3.0, one may specify this
 generator using the name "Visual Studio 12" without the year component.
 
@@ -24,6 +12,27 @@ Project Types
 Only Visual C++ and C# projects may be generated.  Other types of
 projects (JavaScript, Powershell, Python, etc.) are not supported.
 
+Platform Selection
+^^^^^^^^^^^^^^^^^^
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+name (architecture).  For example:
+
+* ``cmake -G "Visual Studio 12 2013" -A Win32``
+* ``cmake -G "Visual Studio 12 2013" -A x64``
+* ``cmake -G "Visual Studio 12 2013" -A ARM``
+
+For compatibility with CMake versions prior to 3.1, one may specify
+a target platform name optionally at the end of the generator name.
+This is supported only for:
+
+``Visual Studio 12 2013 Win64``
+  Specify target platform ``x64``.
+
+``Visual Studio 12 2013 ARM``
+  Specify target platform ``ARM``.
+
 Toolset Selection
 ^^^^^^^^^^^^^^^^^
 
diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst
index e55bc73..917d8e5 100644
--- a/Help/generator/Visual Studio 14 2015.rst
+++ b/Help/generator/Visual Studio 14 2015.rst
@@ -3,11 +3,26 @@ Visual Studio 14 2015
 
 Generates Visual Studio 14 (VS 2015) project files.
 
-The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name (architecture).
+Project Types
+^^^^^^^^^^^^^
+
+Only Visual C++ and C# projects may be generated.  Other types of
+projects (JavaScript, Powershell, Python, etc.) are not supported.
+
+Platform Selection
+^^^^^^^^^^^^^^^^^^
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+name (architecture).  For example:
+
+* ``cmake -G "Visual Studio 14 2015" -A Win32``
+* ``cmake -G "Visual Studio 14 2015" -A x64``
+* ``cmake -G "Visual Studio 14 2015" -A ARM``
 
 For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of this generator name:
+a target platform name optionally at the end of the generator name.
+This is supported only for:
 
 ``Visual Studio 14 2015 Win64``
   Specify target platform ``x64``.
@@ -15,12 +30,6 @@ a target platform name optionally at the end of this generator name:
 ``Visual Studio 14 2015 ARM``
   Specify target platform ``ARM``.
 
-Project Types
-^^^^^^^^^^^^^
-
-Only Visual C++ and C# projects may be generated.  Other types of
-projects (JavaScript, Powershell, Python, etc.) are not supported.
-
 Toolset Selection
 ^^^^^^^^^^^^^^^^^
 
diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst
index 809be4b..42a3bb6 100644
--- a/Help/generator/Visual Studio 15 2017.rst
+++ b/Help/generator/Visual Studio 15 2017.rst
@@ -3,18 +3,6 @@ Visual Studio 15 2017
 
 Generates Visual Studio 15 (VS 2017) project files.
 
-The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name (architecture).
-
-For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of this generator name:
-
-``Visual Studio 15 2017 Win64``
-  Specify target platform ``x64``.
-
-``Visual Studio 15 2017 ARM``
-  Specify target platform ``ARM``.
-
 Project Types
 ^^^^^^^^^^^^^
 
@@ -37,6 +25,28 @@ one of the instances, that instance will be used.  Otherwise, if more
 than one instance is installed we do not define which one is chosen
 by default.
 
+Platform Selection
+^^^^^^^^^^^^^^^^^^
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+name (architecture).  For example:
+
+* ``cmake -G "Visual Studio 15 2017" -A Win32``
+* ``cmake -G "Visual Studio 15 2017" -A x64``
+* ``cmake -G "Visual Studio 15 2017" -A ARM``
+* ``cmake -G "Visual Studio 15 2017" -A ARM64``
+
+For compatibility with CMake versions prior to 3.1, one may specify
+a target platform name optionally at the end of the generator name.
+This is supported only for:
+
+``Visual Studio 15 2017 Win64``
+  Specify target platform ``x64``.
+
+``Visual Studio 15 2017 ARM``
+  Specify target platform ``ARM``.
+
 Toolset Selection
 ^^^^^^^^^^^^^^^^^
 
diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst
index 40471b9..a29033f 100644
--- a/Help/generator/Visual Studio 9 2008.rst
+++ b/Help/generator/Visual Studio 9 2008.rst
@@ -3,11 +3,22 @@ Visual Studio 9 2008
 
 Generates Visual Studio 9 2008 project files.
 
-The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name.
+Platform Selection
+^^^^^^^^^^^^^^^^^^
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+name (architecture).  For example:
+
+* ``cmake -G "Visual Studio 9 2008" -A Win32``
+* ``cmake -G "Visual Studio 9 2008" -A x64``
+* ``cmake -G "Visual Studio 9 2008" -A Itanium``
+* ``cmake -G "Visual Studio 9 2008" -A <WinCE-SDK>``
+  (Specify a target platform matching a Windows CE SDK name.)
 
 For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of this generator name:
+a target platform name optionally at the end of the generator name.
+This is supported only for:
 
 ``Visual Studio 9 2008 Win64``
   Specify target platform ``x64``.