[freetype2] gsoc-anurag-docs-2023 41a211733: [docs] Migrate docs/INSTALL to Markdown

[Werner Lemberg]

branch: gsoc-anurag-docs-2023
commit 41a21173362177d7f487ba6078aa25f9ae8acf26
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} | 76 +++++++++++++++++++++++++++++++++-----------
 3 files changed, 60 insertions(+), 20 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 61%
rename from docs/INSTALL
rename to docs/INSTALL.md
index 49ab112e4..687ed2abf 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,10 +24,9 @@ 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
+1. Unix and Unix-like systems
 
     This also includes MacOS, Cygwin, MinGW + MSYS, Mingw-w64 + MSYS2,
     and possibly other, similar environments.
@@ -40,7 +39,7 @@ II. Normal installation and upgrades
     GNU Make VERSION 3.81 OR NEWER IS NEEDED!
 
 
-  2. Other systems using GNU Make
+2. Other systems using GNU Make
 
     On some  non-Unix platforms, it  is possible to build  the library
     using only  the GNU Make utility.   Note that *NO OTHER  MAKE TOOL
@@ -51,19 +50,19 @@ II. Normal installation and upgrades
     Instructions are provided in the file `INSTALL.GNU`.
 
 
-  3. Other build tools and platforms.
+3. Other build tools and platforms.
 
     A few other tools  can be used  to build FreeType.  You  can  find
     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)
+4. With an IDE Project File (e.g., for Visual Studio or CodeWarrior)
 
     We provide a  small number of 'project files'  for various IDEs to
     automatically build  the library as  well.  Note that  these files
@@ -74,22 +73,63 @@ II. Normal installation and upgrades
     directory, where <system> stands for your OS or environment.
 
 
-  5. From you own IDE, or own Makefiles
+5. From you own IDE, or own Makefiles
 
     If  you  want  to  create   your  own  project  file,  follow  the
     instructions   given  in  the   `INSTALL.ANY`  document   of  this
     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 ---