[freetype2] gsoc-anurag-docs-2023 848f51916: [docs] Migrate docs/INSTALL to Markdown

[Werner Lemberg]

branch: gsoc-anurag-docs-2023
commit 848f51916ac8500309b76df3c8fe9f6ea22caa74
Author: Anurag Thakur <anurag105csec21@bpitindia.edu.in>
Commit: Anurag Thakur <anurag105csec21@bpitindia.edu.in>

    [docs] Migrate docs/INSTALL to Markdown
---
 README.md                    |  2 +-
 docs/.gitignore              |  2 ++
 docs/{INSTALL => INSTALL.md} | 66 ++++++++++++++++++++++++++++++++++----------
 3 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index b9a73c8b4..33ba1ea95 100644
--- a/README.md
+++ b/README.md
@@ -154,7 +154,7 @@ and accept it fully.
 [Documentation GZ]: 
https://download.savannah.gnu.org/releases/freetype/freetype-2.11.1.tar.gz
 [Documentation ZIP]: 
https://download.savannah.gnu.org/releases/freetype/ftdmo2111.zip
 
-[INSTALL]: ./docs/INSTALL
+[INSTALL]: ./docs/INSTALL.md
 [CHANGES]: ./docs/CHANGES
 [LICENSE]: ./LICENSE.TXT
 [DOCGUIDE]: ./docs/DOCGUIDE
diff --git a/docs/.gitignore b/docs/.gitignore
index b8d05d11a..24dffcbc7 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -5,6 +5,8 @@ reference/
 *.html
 *.md
 
+!INSTALL.md
+
 # MkDocs Config file
 mkdocs.yml
 
diff --git a/docs/INSTALL b/docs/INSTALL.md
similarity index 65%
rename from docs/INSTALL
rename to docs/INSTALL.md
index 49ab112e4..6c9e9c250 100644
--- a/docs/INSTALL
+++ b/docs/INSTALL.md
@@ -1,11 +1,11 @@
+# Building FreeType
 
 There are  several ways  to build the  FreeType library,  depending on
 your system and the level of  customization you need.  Here is a short
 overview of the documentation available:
 
 
-I. Prerequisites and dependencies
-=================================
+## A. Prerequisites and dependencies
 
   FreeType is a low level C library  that only depends on the standard
   C library with very few platform-dependent optimizations utilized at
@@ -24,8 +24,7 @@ I. Prerequisites and dependencies
   run-time;  look at the documentation of function `FT_Property_Set`.
 
 
-II. Normal installation and upgrades
-====================================
+## B. Normal installation and upgrades
 
   1. Unix and Unix-like systems
 
@@ -57,10 +56,10 @@ II. Normal installation and upgrades
     the  corresponding instruction files  in  the FreeType root folder
     or the builds/ sub-folder.
 
-      CMake   :: see `CMakeLists.txt` for more information
-      Meson   :: see `meson.build` for more information
-      MSBuild :: see `builds/windows/vc2010/freetype.vcxproj`
-      MMS     :: see `vms_make.com` and `docs/INSTALL.VMS`
+      |CMake   | see `CMakeLists.txt` for more information |
+      |Meson   | see `meson.build` for more information |
+      |MSBuild | see `builds/windows/vc2010/freetype.vcxproj` |
+      |MMS     | see `vms_make.com` and `docs/INSTALL.VMS` |
 
 
   4. With an IDE Project File (e.g., for Visual Studio or CodeWarrior)
@@ -81,15 +80,56 @@ II. Normal installation and upgrades
     directory.
 
 
-III. Custom builds of the library
-=================================
+## C. Custom builds of the library
 
   Customizing the compilation  of FreeType is easy, and  allows you to
   select only the components of  the font engine that you really need.
   For more details read the file `CUSTOMIZE`.
 
+## D. Standard builds with `configure`
 
-----------------------------------------------------------------------
+  The git repository doesn't contain pre-built configuration scripts for
+  UNIXish platforms.  To generate them say
+
+    sh autogen.sh
+
+  which in turn depends on the following packages:
+
+    automake (1.10.1)
+    libtool (2.2.4)
+    autoconf (2.62)
+
+  The versions given  in parentheses are known to  work.  Newer versions
+  should  work too,  of course.   Note  that `autogen.sh`  also sets  up
+  proper file permissions for the `configure` and auxiliary scripts.
+
+  The `autogen.sh` script checks whether the versions of the above three
+  tools match the numbers above.  Otherwise it will complain and suggest
+  either  upgrading or  using  environment variables  to  point to  more
+  recent versions of the required tools.
+
+  Note that  `aclocal` is provided  by the 'automake' package  on Linux,
+  and that `libtoolize` is called `glibtoolize` on Darwin (OS X).
+
+
+## E. Alternative build methods
+
+  For static  builds that don't use  platform-specific optimizations, no
+  configure script is necessary at all; saying
+
+    make setup ansi
+    make
+
+  should work on all platforms that have GNU `make` (or `makepp`).
+
+  A build  with `cmake`  or `meson`  can be done  directly from  the git
+  repository.  However, if you want  to use the `FT_DEBUG_LOGGING` macro
+  (see file `docs/DEBUG` for more information) it is currently mandatory
+  to execute `autogen.sh`  in advance; this script clones  the 'dlg' git
+  submodule and copies some files into FreeType's source tree.
+
+
+---
 
 [1] make++, a make tool written in Perl, has sufficient support of GNU
     make extensions to build FreeType.  See
@@ -99,7 +139,7 @@ III. Custom builds of the library
     for more information;  you need version 2.0 or newer, and you must
     pass option `--norc-substitution`.
 
-----------------------------------------------------------------------
+---
 
 Copyright (C) 2000-2023 by
 David Turner, Robert Wilhelm, and Werner Lemberg.
@@ -110,5 +150,3 @@ license,  LICENSE.TXT.  By  continuing to  use, modify,  or 
distribute
 this file you  indicate that you have read  the license and understand
 and accept it fully.
 
-
---- end of INSTALL ---