Fix Markdown syntax of INSTALL file and rename it to *.md

This enables proper formatted display of the file on e.g. GitHub, increasing readability.

2 files changed, 172 insertions, 159 deletions

diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index 0fb4862f..00000000
--- a/INSTALL
+++ /dev/null
@@ -1,159 +0,0 @@
-TagLib Installation
-===================
-
-TagLib uses the CMake build system. As a user, you will most likely want to
-build TagLib in release mode and install it into a system-wide location.
-This can be done using the following commands:
-
-  cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release .
-  make
-  sudo make install
-
-In order to build the included examples, use the BUILD_EXAMPLES option:
-
-  cmake -DBUILD_EXAMPLES=ON [...]
-
-See http://www.cmake.org/cmake/help/runningcmake.html for generic help on
-running CMake.
-
-Mac OS X
---------
-
-On Mac OS X, you might want to build a framework that can be easily integrated
-into your application. If you set the BUILD_FRAMEWORK option on, it will compile
-TagLib as a framework. For example, the following command can be used to build
-an Universal Binary framework with Mac OS X 10.4 as the deployment target:
-
-  cmake -DCMAKE_BUILD_TYPE=Release \
-    -DBUILD_FRAMEWORK=ON \
-    -DCMAKE_C_COMPILER=/usr/bin/gcc-4.0 \
-    -DCMAKE_CXX_COMPILER=/usr/bin/c++-4.0 \
-    -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk/ \
-    -DCMAKE_OSX_DEPLOYMENT_TARGET=10.4 \
-    -DCMAKE_OSX_ARCHITECTURES="ppc;i386;x86_64"
-
-For a 10.6 Snow Leopard static library with both 32-bit and 64-bit code, use:
-
-  cmake -DCMAKE_BUILD_TYPE=Release \
-    -DCMAKE_OSX_DEPLOYMENT_TARGET=10.6 \
-    -DCMAKE_OSX_ARCHITECTURES="i386;x86_64" \
-    -DBUILD_SHARED_LIBS=OFF \
-    -DCMAKE_INSTALL_PREFIX="<folder you want to build to>"
-
-After 'make', and 'make install', add libtag.a to your XCode project, and add
-the include folder to the project's User Header Search Paths.
-
-Windows
--------
-
-It's Windows ... Systems vary!
-This means you need to adjust things to suit your system, especially paths.
-
-Tested with:
-  Microsoft Visual Studio 2010
-  Gcc by mingw-w64.sf.net v4.6.3 (Strawberry Perl 32b)
-  MinGW32-4.8.0
-
-Requirements:
-  1. Tool chain, Build Environment, Whatever ya want to call it ...
-     Installed and working.
-  2. CMake program. (Available at: www.cmake.org)
-     Installed and working.
-
-Optional:
-  1. Zlib library.
-     Available in some Tool Chains, Not all.
-     Search the web, Take your choice.
-
-Useful configuration options used with CMake (GUI and/or Command line):
-  Any of the ZLIB_ variables may be used at the command line, ZLIB_ROOT is only
-  available on the Command line.
-  ZLIB_ROOT=            Where to find ZLib's root directory.
-                        Assumes parent of: \include and \lib.
-  ZLIB_INCLUDE_DIR=     Where to find ZLib's Include directory.
-  ZLIB_LIBRARY=         Where to find ZLib's Library.
-  ZLIB_SOURCE=          Where to find ZLib's Source Code.
-                        Alternative to ZLIB_INCLUDE_DIR and ZLIB_LIBRARY.
-  CMAKE_INSTALL_PREFIX= Where to install Taglib.
-  CMAKE_BUILD_TYPE=     Release, Debug, etc ... (Not available in MSVC)
-
-The easiest way is at the Command Prompt.
-  MSVS Command Prompt for MSVS Users.
-  (Batch file and/or Shortcuts are your friends)
-
-  1. Build the Makefiles:
-       Replace "GENERATOR" with your needs.
-       For MSVS : "Visual Studio X" where X is the single or two digit version.
-       For MinGW: "MinGW Makefiles"
-
-       C:\GitRoot\taglib> cmake -G "GENERATOR" -DCMAKE_INSTALL_PREFIX=C:\Libraries\taglib
-
-     Or use the CMake GUI:
-       1. Open CMake GUI.
-       2. Set Paths.
-          "Where is the source code" and "Where to build the binaries"
-          Example, Both would be: C:\GitRoot\taglib
-       3. Tick: Advanced
-       4. Select: Configure
-       5. Select: Generator
-       6. Tick: Use default native compilers
-       7. Select: Finish
-       Wait until done.
-       5. If using ZLib, Scroll down.
-          (to the bottom of the list of options ... should go over them all)
-          1. Edit: ZLIB_INCLUDE_DIR
-          2. Edit: ZLIB_LIBRARY
-       6. Select: Generate
-
-  2. Build the project:
-       MSVS:
-         C:\GitRoot\taglib> msbuild all_build.vcxproj /p:Configuration=Release
-           OR (Depending on MSVS version or personal choice)
-         C:\GitRoot\taglib> devenv all_build.vcxproj /build Release
-       MinGW:
-         C:\GitRoot\taglib> gmake
-           OR (Depending on MinGW install)
-         C:\GitRoot\taglib> mingw32-make
-
-     Or in the MSVS GUI:
-       1. Open MSVS.
-       2. Open taglib solution.
-       3. Set build type to: Release (look in the tool bars)
-       2. Hit F7 to build the solution. (project)
-
-  3. Install the project:
-       (Change 'install' to 'uninstall' to uninstall the project)
-       MSVS:
-         C:\GitRoot\taglib> msbuild install.vcxproj
-           OR (Depending on MSVC version or personal choice)
-         C:\GitRoot\taglib> devenv install.vcxproj
-       MinGW:
-         C:\GitRoot\taglib> gmake install
-           OR (Depending on MinGW install)
-         C:\GitRoot\taglib> mingw32-make install
-
-     Or in the MSVS GUI:
-       1. Open project.
-       2. Open Solution Explorer.
-       3. Right Click: INSTALL
-       4. Select: Project Only
-       5. Select: Build Only INSTALL
-
-To build a static library, set the following two options with CMake.
-  -DBUILD_SHARED_LIBS=OFF -DENABLE_STATIC_RUNTIME=ON
-
-Including ENABLE_STATIC_RUNTIME=ON indicates you want TagLib built using the
-static runtime library, rather than the DLL form of the runtime.
-
-Unit Tests
-----------
-
-If you want to run the test suite to make sure TagLib works properly on your
-system, you need to have cppunit installed. To build the tests, include
-the option -DBUILD_TESTS=on when running cmake.
-
-The test suite has a custom target in the build system, so you can run
-the tests using make:
-
-  make check
-
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 00000000..cbda309d
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,172 @@
+TagLib Installation
+===================
+
+TagLib uses the CMake build system. As a user, you will most likely want to
+build TagLib in release mode and install it into a system-wide location.
+This can be done using the following commands:
+
+    cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release .
+    make
+    sudo make install
+
+In order to build the included examples, use the `BUILD_EXAMPLES` option:
+
+    cmake -DBUILD_EXAMPLES=ON [...]
+
+See http://www.cmake.org/cmake/help/runningcmake.html for generic help on
+running CMake.
+
+Mac OS X
+--------
+
+On Mac OS X, you might want to build a framework that can be easily integrated
+into your application. If you set the BUILD_FRAMEWORK option on, it will compile
+TagLib as a framework. For example, the following command can be used to build
+an Universal Binary framework with Mac OS X 10.4 as the deployment target:
+
+    cmake -DCMAKE_BUILD_TYPE=Release \
+      -DBUILD_FRAMEWORK=ON \
+      -DCMAKE_C_COMPILER=/usr/bin/gcc-4.0 \
+      -DCMAKE_CXX_COMPILER=/usr/bin/c++-4.0 \
+      -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk/ \
+      -DCMAKE_OSX_DEPLOYMENT_TARGET=10.4 \
+      -DCMAKE_OSX_ARCHITECTURES="ppc;i386;x86_64"
+
+For a 10.6 Snow Leopard static library with both 32-bit and 64-bit code, use:
+
+    cmake -DCMAKE_BUILD_TYPE=Release \
+      -DCMAKE_OSX_DEPLOYMENT_TARGET=10.6 \
+      -DCMAKE_OSX_ARCHITECTURES="i386;x86_64" \
+      -DBUILD_SHARED_LIBS=OFF \
+      -DCMAKE_INSTALL_PREFIX="<folder you want to build to>"
+
+After `make`, and `make install`, add `libtag.` to your XCode project, and add
+the include folder to the project's User Header Search Paths.
+
+Windows
+-------
+
+It's Windows ... Systems vary!
+This means you need to adjust things to suit your system, especially paths.
+
+Tested with:
+* Microsoft Visual Studio 2010, 2015
+* Microsoft C++ Build Tools 2015, 2017 (standalone packages not requiring Visual Studio)
+* Gcc by mingw-w64.sf.net v4.6.3 (Strawberry Perl 32b)
+* MinGW32-4.8.0
+
+Requirements:
+* Tool chain, build environment, whatever ya want to call it ...
+     Installed and working.
+* CMake program. (Available at: www.cmake.org)
+     Installed and working.
+
+Optional:
+*  Zlib library.
+     Available in some tool chains, not all.
+     Search the web, take your choice.
+
+Useful configuration options used with CMake (GUI and/or command line):
+  Any of the `ZLIB_` variables may be used at the command line, `ZLIB_ROOT` is only
+  available on the command line.
+  
+  | option               | description |
+   ---------------------| ------------|
+  `ZLIB_ROOT=`         | Where to find ZLib's root directory. Assumes parent of: `\include` and `\lib.`|
+   `ZLIB_INCLUDE_DIR=`  | Where to find ZLib's Include directory.|
+   `ZLIB_LIBRARY=`      | Where to find ZLib's Library.
+   `ZLIB_SOURCE=`       | Where to find ZLib's Source Code. Alternative to `ZLIB_INCLUDE_DIR` and `ZLIB_LIBRARY`.
+   `CMAKE_INSTALL_PREFIX=` | Where to install Taglib. |
+   `CMAKE_BUILD_TYPE=`  | Release, Debug, etc ... (Not available in MSVC) |
+
+The easiest way is at the command prompt (Visual C++ command prompt for MSVS users – batch file and/or shortcuts are your friends).
+
+1.  **Build the Makefiles:**
+
+    Replace "GENERATOR" with your needs.
+    * For MSVS: `Visual Studio XX YYYY`, e.g. `Visual Studio 14 2015`
+    * For MinGW: `MinGW Makefiles`
+       
+          C:\GitRoot\taglib> cmake -G "GENERATOR"  -DCMAKE_INSTALL_PREFIX=C:\Libraries\taglib
+
+    Or use the CMake GUI:
+    1. Open CMake GUI.
+    2. Set paths: *Where is the source code* and *Where to build the binaries*.
+
+       In the example, both would be: `C:\GitRoot\taglib`
+    3. Tick: Advanced
+    4. Select: Configure
+    5. Select: Generator
+    6. Tick: Use default native compilers
+    7. Select: Finish
+      Wait until done.
+    8. If using ZLib, Scroll down.
+    (to the bottom of the list of options ... should go over them all)
+       1. Edit: `ZLIB_INCLUDE_DIR`
+       2. Edit: `ZLIB_LIBRARY`
+    9. Select: Generate
+
+2.  **Build the project**
+    * MSVS:
+
+          C:\GitRoot\taglib> msbuild all_build.vcxproj /p:Configuration=Release
+      OR (Depending on MSVS version or personal choice)
+
+          C:\GitRoot\taglib> devenv all_build.vcxproj /build Release
+      OR in the MSVS GUI:
+      1. Open MSVS.
+      2. Open taglib solution.
+      3. Set build type to: Release (look in the tool bars)
+      2. Hit F7 to build the solution. (project)
+    * MinGW:
+
+          C:\GitRoot\taglib> gmake
+
+      OR (Depending on MinGW install)
+      
+          C:\GitRoot\taglib> mingw32-make
+
+
+
+3.  **Install the project**
+  
+    (Change `install` to `uninstall` to uninstall the project)
+    * MSVS:
+
+          C:\GitRoot\taglib> msbuild install.vcxproj
+      OR (Depending on MSVC version or personal choice)
+
+          C:\GitRoot\taglib> devenv install.vcxproj
+      
+      Or in the MSVS GUI:
+        1. Open project.
+        2. Open Solution Explorer.
+        3. Right Click: INSTALL
+        4. Select: Project Only
+        5. Select: Build Only INSTALL
+    * MinGW:
+
+          C:\GitRoot\taglib> gmake install
+      OR (Depending on MinGW install)
+          
+          C:\GitRoot\taglib> mingw32-make install
+
+
+To build a static library, set the following two options with CMake:
+
+    -DBUILD_SHARED_LIBS=OFF -DENABLE_STATIC_RUNTIME=ON
+
+Including `ENABLE_STATIC_RUNTIME=ON` indicates you want TagLib built using the
+static runtime library, rather than the DLL form of the runtime.
+
+Unit Tests
+----------
+
+If you want to run the test suite to make sure TagLib works properly on your
+system, you need to have cppunit installed. To build the tests, include
+the option `-DBUILD_TESTS=on` when running cmake.
+
+The test suite has a custom target in the build system, so you can run
+the tests using make:
+
+    make check