Merge branch 'msw-install-docs'

Minor updates to wxMSW install docs.

See https://github.com/wxWidgets/wxWidgets/pull/2433

docs/msw/install.md

@@ -47,42 +47,7 @@ All makefiles and project are located in build\msw directory.
 Microsoft Visual C++ Compilation       {#msw_build_msvs}
 ----------------------------------------------------------------
 
-* From command line using the provided makefiles:
+### From the IDE
-
-0. Open a "Visual Studio Command Prompt" window shortcut to which
-   must have been installed to the "Start" menu or the "Start" screen
-   by MSVS installation.
-
-1. Change directory to \%WXWIN\%\build\msw and type
-
-        > nmake /f makefile.vc
-
-   to build wxWidgets in the default debug configuration as a static
-   library. You can also do
-
-        > nmake /f makefile.vc BUILD=release
-
-   to build a release version or
-
-        > nmake /f makefile.vc BUILD=release SHARED=1 TARGET_CPU=X86
-
-   to build a 32 bit release DLL version from an x86 command prompt, or
-
-        > nmake /f makefile.vc BUILD=release SHARED=1 TARGET_CPU=X64
-
-   to build a 64 bit release DLL version from an x64 command prompt.
-
-   See "Configuring the Build" for more information about the
-   additional parameters that can be specified on the command line.
-
-2. To verify your build, change the directory to \%WXWIN\%\samples\minimal and
-   run the same nmake command (with the same parameters there), this
-   should create a working minimal wxWidgets sample.
-
-3. If you need to rebuild, use "clean" target first or "nmake /a".
-
-
-* From the IDE using the provided project files:
 
 Ready to use project files are provided for VC++ versions 8, 9,
 10, 11, 12, 14, 15 and 16 (also known as MSVS 2005, 2008, 2010, 2012,
@@ -96,6 +61,60 @@ are not always built in the correct order, and this may result in link
 errors. Simply do the build again, up to 3 times, to fix this.
 
 
+### From the command line
+
+wxWidgets can also be built from the command line using the provided makefiles.
+
+This needs to be done from the "Visual Studio Command Prompt" window, which can
+be opened using a shortcut installed to the "Start" menu or the "Start" screen
+by MSVS installation.
+
+In this window, change directory to `%WXWIN%\build\msw` and type
+
+        > nmake /f makefile.vc
+
+to build wxWidgets in the default debug configuration as a static library. You
+can also do
+
+        > nmake /f makefile.vc BUILD=release
+
+to build a release version or
+
+        > nmake /f makefile.vc BUILD=release SHARED=1 TARGET_CPU=X86
+
+to build a 32 bit release DLL version from an x86 command prompt, or
+
+        > nmake /f makefile.vc BUILD=release SHARED=1 TARGET_CPU=X64
+
+to build a 64 bit release DLL version from an x64 command prompt.
+
+See [Make Parameters](#msw_build_make_params) for more information about the
+additional parameters that can be specified on the command line.
+
+To verify your build, change the directory to `%WXWIN%\samples\minimal` and
+run the same nmake command (with the same parameters there), this should create
+a working minimal wxWidgets sample.
+
+If you need to rebuild, use "clean" target first or "nmake /a".
+
+
+### Using vcpkg
+
+You can download and install wxWidgets using the [vcpkg](https://github.com/Microsoft/vcpkg)
+dependency manager:
+
+    > git clone https://github.com/Microsoft/vcpkg.git
+    > cd vcpkg
+    > bootstrap-vcpkg.bat
+    > vcpkg integrate install
+    > vcpkg install wxwidgets
+
+The wxWidgets port in vcpkg is kept up to date by Microsoft team members and community
+contributors. If the version is out of date, please [create an issue or pull request]
+(https://github.com/Microsoft/vcpkg) on the vcpkg repository.
+
+
+
 ### Special notes for Visual Studio 2010+
 
 For Visual Studio 2010+ solutions it is possible to customize the build by
@@ -128,53 +147,39 @@ your responsibility to monitor for such situations.
 Debug visualizers for Visual Studio 2012+ are provided which makes inspecting
 various wxWidgets classes easier to view while debugging. To use them:
 
-1. Open the folder \%WXWIN\%\misc\msvc
+1. Open the folder `%WXWIN%\misc\msvc`
-2. Open the folder \%USERPROFILE\%\My Documents\Visual Studio 2012\Visualizers\
+2. Open the folder `%USERPROFILE%\My Documents\Visual Studio 2012\Visualizers`
-   (or the corresponding location for newer versions, e.g. ...2013\Visualizers)
+   (or the corresponding location for newer versions, e.g. `...2013\Visualizers`)
-3. Copy wxWidgets.natvis and autoexp.inc
+3. Copy `wxWidgets.natvis` and `autoexp.inc`
-4. For Visual Studio 2013+ additionally copy wxWidgets.2013.natvis
+4. For Visual Studio 2013+ additionally copy `wxWidgets.2013.natvis`
 
 
-Cygwin/MinGW Compilation               {#msw_build_cygwin}
+MinGW Compilation               {#msw_build_mingw}
 ----------------------------------------------------------------
 
-wxWidgets supports Cygwin, MinGW, MinGW-w64 and TDM-GCC tool chains under
+wxWidgets supports several different gcc-based toolchains under Windows,
-Windows. They can be downloaded from:
+including:
 
-http://www.cygwin.com/
+- [MinGW-w64](http://mingw-w64.sourceforge.net/)
+- [TDM-GCC](http://tdm-gcc.tdragon.net/)
+- Classic [MinGW](http://www.mingw.org/)
 
-http://www.mingw.org/
+Please retrieve and install the latest version of your preferred
+tool chain by following the instructions provided by these packages.
 
-http://mingw-w64.sourceforge.net/
+Additionally note that MinGW-w64 can be used as a cross-compiler from Unix
-
+systems, including [WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux).
-http://tdm-gcc.tdragon.net/
-
-respectively. Please retrieve and install the latest version of your preferred
-tool chain by following the instructions provided by these packages. Notice
-that Cygwin includes both native Cygwin compiler, which produces binaries that
-require Cygwin during run-time, and MinGW[-w64] cross-compilers which can still
-be used in Cygwin environment themselves but produce plain Windows binaries
-without any special run-time requirements. You will probably want to use the
-latter for developing your applications.
-
-If using MinGW, you can download the add-on MSYS package to provide Unix-like
-tools that you'll need to build wxWidgets using configure.
-
-C++11 note: If you want to compile wxWidgets in C++11 mode, you currently have
-            to use -std=gnu++11 switch as -std=c++11 disables some extensions
-            that wxWidgets relies on. I.e. please use CXXFLAGS="-std=gnu++11".
 
 All of these tool chains can be used either with Unix-like configure+make build
 process (preferred) or with the provided makefile.gcc makefiles without using
-configure:
+configure.
 
 ### Using configure
 
-This method works in exactly the same way as under Unix systems,
+This method works in exactly the same way as under Unix systems, and requires a
-including OS X, and requires a Unix-like environment to work, i.e.
+Unix-like environment to work, i.e. one of MSYS, [MSYS2](https://www.msys2.org/)
-either MSYS or Cygwin.
+or [Cygwin](https://www.cygwin.com/), so the following steps should be done
-
+from MSYS or Cygwin shell prompt:
-0. Open MSYS or Cygwin shell prompt.
 
 1. Create a build directory: it is is strongly recommended to not
    build the library in the directory containing the sources (`$WXWIN`)
@@ -187,9 +192,9 @@ either MSYS or Cygwin.
         $ mkdir build-debug
         $ cd build-debug
 
-2. Run configure passing it any of the options shown by "configure
+2. Run configure passing it any of the options shown by `configure
-   --help". Notice that configure builds shared libraries by default,
+   --help`. Notice that configure builds shared libraries by default,
-   use --disable-shared to build static ones. For example:
+   use `--disable-shared` to build static ones. For example:
 
         $ ../configure --enable-debug
 
@@ -210,25 +215,25 @@ either MSYS or Cygwin.
    so this step can usually be omitted.
 
 
-### Using plain makefiles:
+### Using makefiles from Windows command line
 
-NOTE: The makefile.gcc makefiles are for compilation under MinGW using
+The `makefile.gcc` makefiles are for compilation using MinGW using Windows
-      Windows command interpreter (command.com/cmd.exe), they won't work
+command interpreter (`cmd.exe`), they will *not* work if you use Unix
-      if you use Unix shell, as is the case with MSYS. Follow the instructions
+shell, as is the case with MSYS. Follow the instructions for using configure
-      for using configure above instead if you prefer to use Unix shell.
+above instead if you prefer to use Unix shell. The commands shown here must be
+executed from a DOS command line window (cmd.exe, *not* Bash sh.exe).
 
-0. Open DOS command line window (cmd.exe, *not* Bash sh.exe).
+1. Change directory to `%WXWIN%\build\msw` and type
-
-1. Change directory to \%WXWIN\%\build\msw and type
 
         > mingw32-make -f makefile.gcc
 
    to build wxWidgets in the default debug configuration as a static
    library. Add "BUILD=release" and/or "SHARED=1" to build the library
    in release configuration and/or as a shared library instead of the
-   default static one.
+   default static one, see [Make Parameters](#msw_build_make_params)
+   for more details.
 
-   NOTE: For parallel builds, i.e. using -jN make option, please run
+   NOTE: For parallel builds, i.e. using `-jN` make option, please run
          `mingw32-make -jN ... setup_h` first and then rerun the full
          make command without `setup_h` at the end to work around a bug
          in the current makefiles.
@@ -243,28 +248,10 @@ NOTE: The makefile.gcc makefiles are for compilation under MinGW using
 
 
 
-Installing and building wxWidgets using vcpkg         {#msw_install_and_build}
+Make Parameters                         {#msw_build_make_params}
-=============================================
-
-You can download and install wxWidgets using the [vcpkg](https://github.com/Microsoft/vcpkg) 
-dependency manager:
-
-    > git clone https://github.com/Microsoft/vcpkg.git
-    > cd vcpkg
-    > bootstrap-vcpkg.bat
-    > vcpkg integrate install
-    > vcpkg install wxwidgets
-
-The wxWidgets port in vcpkg is kept up to date by Microsoft team members and community 
-contributors. If the version is out of date, please [create an issue or pull request]
-(https://github.com/Microsoft/vcpkg) on the vcpkg repository.
-
-
-
-Configuring the Build                  {#msw_build_config}
 ================================================================
 
-NOTE: If you use configure to build the library with Cygwin/MinGW, the
+NOTE: If you use configure to build the library with MinGW, the
       contents of this section does not apply, just pass the arguments
       to configure directly in this case.
 
@@ -272,7 +259,7 @@ Library configuration
 ----------------------------------------------------------------
 
 While it is never necessary to do it, you may want to change some of
-the options in the \%WXWIN\%\\include\\wx\\msw\\setup.h file before building
+the options in the `%WXWIN%\include\wx\msw\setup.h` file before building
 wxWidgets. This file is heavily commented, please read it and enable or disable
 the features you would like to compile wxWidgets with[out].
 
@@ -415,7 +402,7 @@ The full list of the build settings follows:
   different setup.h settings coexisting in same tree. The value of
   this option is appended to the build directories names. This is
   useful for building the library in some non-default configuration,
-  e.g. you could change `wxUSE_STL` to 1 in `\%WXWIN\%\include\wx\msw\setup.h` and
+  e.g. you could change `wxUSE_STL` to 1 in `%WXWIN%\include\wx\msw\setup.h` and
   then build with `CFG=-stl`. Alternatively, you could build with e.g.
   `RUNTIME_LIBS=static CFG=-mt` when using MSVC.