Improve Visual Studio build documentation

Update the Visual Studio build documentation by:

* Convert MSVC_NMake/README to MarkDown format, to make it easier on the
  eye.
* Mention that cairo-1.17.x is recommended.
* Make the build process for both NMake and Meson builds clearer.

4 files changed, 88 insertions, 35 deletions

diff --git a/MSVC_NMake/MSVC-Builds.md b/MSVC_NMake/MSVC-Builds.md
new file mode 100644
index 0000000..ef1f50e
--- /dev/null
+++ b/MSVC_NMake/MSVC-Builds.md
@@ -0,0 +1,86 @@
+Building cairomm-1.14.x with Visual Studio 2013 or later
+=
+* You will need Visual Studio 2013 (Visual Studio 12) or later. Building with 
+Visual Studio 2012 or earlier is no longer supported due to `C++11`
+requirements.  For Visual Studio 2013, notice that it is not safe to link its
+builds with other items that is being built with Visual Studio 2015 or later,
+and code using cairomm may require Visual Studio 2015 or later, due to more
+comprehensive `C++11` support in the later Visual Studio versions.
+
+* Using/Building the latest cairo 1.17.x release is recommended, due to 
+numerous improvements on the Windows support, and supports building with Visual
+Studio using Meson. DLL/shared builds are recommended for cairo.
+Otherwise, you can install the latest Win32 GTK+ Development files from
+ftp://ftp.gnome.org/pub/GNOME/binaries/win32/gtk+/.
+By any means, add the paths to headers and import libraries to Visual Studio, if
+they are not already in `$(PREFIX)`, which is
+`$(srcroot)\..\vs$(VSVER)\$(Platform)` by default.
+
+* You will also need libsigc++-2.x built with Visual Studio 2013 or later
+
+## Building with NMake
+* In a Visual Studio command prompt, do the following:
+```
+cd $(srcroot)\MSVC_NMake
+
+# Build
+nmake /f Makefile.vc CFG=[release|debug] <PREFIX=...>
+
+# Build the tests (the Boost C++ libraries are required; Boost must
+# be built with the same compiler with the same release/debug
+# configuration)
+
+# BOOST_DLL=1 means that one is using the DLL builds of Boost to
+# build the tests.
+nmake /f Makefile.vc CFG=[release|debug] <PREFIX=...> <BOOST_DLL=1> tests
+
+# Copy the built DLL and .lib and headers to $(PREFIX) in their
+# appropriate locations
+nmake /f Makefile.vc CFG=[release|debug] <PREFIX=...> install
+```
+* Notice that for the built DLL and .lib the Visual Studio version is no
+longer `vc$(VSVER)0` for Visual Studio 2017 and later, but is named like the 
+following (Visual Studio version), to follow what is done in other C++ libraries
+such as Boost:
+  * 2013: `VSVER=12`, `cairomm-vc120-1_0.[dll|pdb|lib]`
+  * 2015: `VSVER=14`, `cairomm-vc140-1_0.[dll|pdb|lib]`
+  * 2017: `VSVER=15`, `cairomm-vc141-1_0.[dll|pdb|lib]`
+  * 2019: `VSVER=16`, `cairomm-vc142-1_0.[dll|pdb|lib]`
+  * 2022: `VSVER=17`, `cairomm-vc143-1_0.[dll|pdb|lib]`
+
+* If using the old-style naming, i.e. `vc150`, is desired for Visual Studio 
+2017 or later, such as when use cairomm is inconvenient, pass in 
+`USE_COMPAT_LIBS=1` in the NMake commandline. Note that this option is only 
+recommended when absolutely needed, and libsigc++-2.x should be built with this 
+option enabled too.
+
+## Building with Meson
+Building cairomm with Meson for Visual Studio builds is now supported, with the
+following notes:
+* Please see `$(srcroot)/README.md` for more instructions on Meson builds.
+* It is recommended that cairo-1.17.x is used, since it can be built with Meson
+with Visual Studio, with the proper pkg-config files that Meson builds will try
+to use first, which is best supported.
+* Pass in the option `-Dmsvc14x-parallel-installable=false` to the Meson
+configure command line to avoid having the toolset version in the final DLL and
+.lib filenames; again, this is only recommended if it is inconvenient to
+re-build the dependent code, and this option should be used when building items
+that depend on cairomm, if this option is provided.
+* Building from a GIT checkout is possible, which will enable maintainer mode by
+default.  In maintainer mode, you will need the following items (their `bin`
+directory must be in `%PATH%`):
+```
+mm-common
+Doxygen   # Unless -Dbuild-documentation=false is used
+LLVM      # Unless -Dbuild-documentation=false is used; likely needed by Doxygen
+Graphviz  # Unless -Dbuild-documentation=false is used
+```
+
+Cedric Gustin
+08/18/2006
+
+Armin Burgmeier
+09/29/2010
+
+Chun-wei Fan
+09/10/2015, updated 06/29/2023
diff --git a/MSVC_NMake/README b/MSVC_NMake/README
deleted file mode 100644
index 1568e43..0000000
--- a/MSVC_NMake/README
+++ /dev/null
@@ -1,33 +0,0 @@
-Building cairomm with Visual Studio .NET 2015 or later

-

-* You will need Visual Studio 2015 (MSVC 14.0) or later.  Building with Visual Studio 2015 or earlier is no longer

-  supported.

-* Install the latest Win32 GTK+ Development files from ftp://ftp.gnome.org/pub/GNOME/binaries/win32/gtk+/ and add

-  the paths to headers and import libraries to Visual Studio, if they are not already in

-  $(srcroot)/../vs$(VSVER)/$(Platform).

-* It is recommended (and possibly required) that you build cairomm and software that depends on cairomm with the

-  same compiler, even though Microsoft tried hard to make things API and ABI compatible between Visual Studio

-  2015, 2017 and 2019, so the build distinguishes between these versions with 'vc140' (2015), 'vc141' (2017) and

-  'vc142' (2019) in the output DLL and .lib filenames, as per the toolset version as Microsoft defined.  If using

-  'vc140' in the DLL and .lib names are desired (such as when rebuilding software that depends on cairomm is

-  not convenient), pass in 'USE_COMPAT_LIBS=1' in your NMake command line (note that doing this is not recommended).

-  For the Meson builds, pass in the option '-Dmsvc14x-parallel-installable=false' to the Meson configure command line

-  to avoid having the toolset version in the final DLL and .lib filenames; again, this is only recommended if it is

-  inconvenient to re-build the dependent code.

-* In a Visual Studio command prompt, go to $(srcroot)\MSVC_NMake

-* Build using nmake /f Makefile.vc CFG=[release|debug].

-* Run the tests

-* If it is inconvenient for you to re-build any software using

-  cairomm, you may need to pass in BUILD_COMPAT_LIB in your

-  NMake command line so that your application will continue to

-  run properly.

-

-Cedric Gustin

-08/18/2006

-

-Armin Burgmeier

-09/29/2010

-

-Chun-wei Fan

-09/10/2015

-10/26/2018

diff --git a/MSVC_NMake/filelist.am b/MSVC_NMake/filelist.am
index dfe199e..d81733c 100644
--- a/MSVC_NMake/filelist.am
+++ b/MSVC_NMake/filelist.am
@@ -13,4 +13,4 @@ msvc_nmake_data =		\
 	gendef/gendef.cc	\
 	generate-msvc.mak	\
 	Makefile.vc		\
-	README
+	MSVC-Builds.md
diff --git a/README.md b/README.md
index 5311eef..6d3e320 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ supplier of your operating system, such as your Linux distribution.
 
 ## Building on Windows
 
-See MSVC_NMake/README
+See MSVC_NMake/MSVC-Builds.md
 
 ## Building from a release tarball