[freetype2] gsoc-anurag-docs-2023 5a60d2ef0 2/2: [docs] Migrate all INSTALL files to Markdown

[Werner Lemberg]

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

    [docs] Migrate all INSTALL files to Markdown
---
 docs/.gitignore                          |   6 ++
 docs/INSTALL.UNIX                        | 139 ------------------------------
 docs/{INSTALL.ANY => INSTALL_ANY.md}     | 116 +++++++++++++------------
 docs/{INSTALL.CROSS => INSTALL_CROSS.md} |   0
 docs/{INSTALL.GNU => INSTALL_GNU.md}     |   0
 docs/{INSTALL.MAC => INSTALL_MAC.md}     |   0
 docs/INSTALL_UNIX.md                     | 141 +++++++++++++++++++++++++++++++
 docs/{INSTALL.VMS => INSTALL_VMS.md}     |   0
 8 files changed, 204 insertions(+), 198 deletions(-)

diff --git a/docs/.gitignore b/docs/.gitignore
index 24dffcbc7..d7777e70c 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -6,6 +6,12 @@ reference/
 *.md
 
 !INSTALL.md
+!INSTALL_ANY.md
+!INSTALL_CROSS.md
+!INSTALL_GNU.md
+!INSTALL_MAC.md
+!INSTALL_UNIX.md
+!INSTALL_VMS.md
 
 # MkDocs Config file
 mkdocs.yml
diff --git a/docs/INSTALL.UNIX b/docs/INSTALL.UNIX
deleted file mode 100644
index 659f3a21f..000000000
--- a/docs/INSTALL.UNIX
+++ /dev/null
@@ -1,139 +0,0 @@
-This  document contains  instructions  on how  to  build the  FreeType
-library on Unix  systems.  This also works for  emulations like Cygwin
-or MSys on Win32:
-
-
-  1. Ensure that you are using GNU Make
-  -------------------------------------
-
-    The FreeType build system  _exclusively_ works with GNU Make.  You
-    will  not be  able to  compile the  library with  the instructions
-    below using any other alternative (including BSD Make).
-
-    Check that you have GNU make by running the command:
-
-       make -v
-
-    This should dump some text that begins with:
-
-       GNU Make  <version number>
-       Copyright (C) <year> Free Software Foundation Inc.
-
-    Note that version  3.81 or higher is *required* or the  build will
-    fail.
-
-    It is also fine to have GNU Make under another name (e.g. 'gmake')
-    if you use the MAKE variable as described below.
-
-    As  a  special exception,  'makepp'  can  also  be used  to  build
-    FreeType 2.  See the file docs/MAKEPP for details.
-
-    For builds  with `cmake' please check file `CMakeLists.txt';  this
-    is a contributed file not directly supported by the FreeType team.
-
-
-  2. Regenerate the configure script if needed
-  --------------------------------------------
-
-    This only applies if you  are building a git snapshot or checkout,
-    *not* if you grabbed the sources of an official release.
-
-    You  need  to invoke  the  `autogen.sh'  script  in the  top-level
-    directory  in order  to  create the  `configure'  script for  your
-    platform.  Normally, this simply means typing:
-
-      sh autogen.sh
-
-    In case of problems, you may  need to install or upgrade Automake,
-    Autoconf or Libtool.  See  `README.git' in the top-level directory
-    for more information.
-
-
-  3. Build and install the library
-  --------------------------------
-
-    Say
-
-      ./configure --help
-
-    to see  the list of  possible configuration options  and important
-    environment  variables.  The ./configure script  will detect  some
-    prerequisite  system  libraries  (libpng, brotli, etc.)  if  their
-    headers are available at the default locations.
-
-    The following  should work  on all Unix  systems where  the `make'
-    command invokes GNU Make:
-
-      ./configure [options]
-      make
-      make install           (as root)
-
-    The default installation path  is `/usr/local'.  It can be changed
-    with the `--prefix=<path>' option.  Example:
-
-      ./configure --prefix=/usr
-
-    When using  a different command  to invoke GNU Make,  use the MAKE
-    variable.  For example,  if `gmake' is the command  to use on your
-    system, do something like:
-
-       MAKE=gmake ./configure [options]
-       gmake
-       gmake install            (as root)
-
-    If  this still doesn't  work, there  must be  a problem  with your
-    system (e.g., you are using a very old version of GNU Make).
-
-    For library identification, FreeType's `configure' script uses the
-    `pkg-config' interface: Assuming it  needs library `foo', it calls
-    the  `pkg-config' program  to find  information on  library `foo',
-    which in turn  looks for a `foo.pc' file installed  at the system.
-    Some platforms,  however, don't come with  `pkg-support'; you then
-    have  to  use environment  variables  as  described by  `configure
-    --help'.  Example:
-
-      LIBPNG_CFLAGS="-I/path/to/libpng/include/directory" \
-      LIBPNG_LIBS="-L/path/to/libpng/lib/directory" \
-      configure ...
-
-    It  is possible  to  compile FreeType  in  a different  directory.
-    Assuming the FreeType source  files in directory `/src/freetype' a
-    compilation in directory `foo' works as follows:
-
-      cd foo
-      /src/freetype/configure [options]
-      make
-      make install
-
-
-  3.1 Interdependency with HarfBuzz
-  .................................
-
-    Note that there  is a chicken-and-egg problem  currently since the
-    HarfBuzz library  (used by the  auto-hinter to improve  support of
-    OpenType  fonts)  depends on  FreeType,  which  can be  solved  as
-    follows in case HarfBuzz is not yet installed on your system.
-
-    1. Call    FreeType's     `configure'    script     with    option
-       `--without-harfbuzz', then compile and install FreeType.
-
-    2. Compile and install HarfBuzz.
-
-    3. Call    FreeType's    `configure'   script    without    option
-       `--without-harfbuzz' (after  executing `make  distclean'), then
-       compile and install FreeType again.
-
-
-----------------------------------------------------------------------
-
-Copyright (C) 2003-2023 by
-David Turner, Robert Wilhelm, and Werner Lemberg.
-
-This  file is  part of  the FreeType  project, and  may only  be used,
-modified,  and distributed  under the  terms of  the  FreeType project
-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.UNIX ---
diff --git a/docs/INSTALL.ANY b/docs/INSTALL_ANY.md
similarity index 53%
rename from docs/INSTALL.ANY
rename to docs/INSTALL_ANY.md
index bb77b1b9c..23b787b97 100644
--- a/docs/INSTALL.ANY
+++ b/docs/INSTALL_ANY.md
@@ -1,33 +1,32 @@
-Instructions on how to build FreeType with your own build tool
-==============================================================
+# Instructions on how to build FreeType with your own build tool
 
-See  the  file `CUSTOMIZE'  to  learn  how  to customize  FreeType  to
-specific environments.
 
+See  the  file [docs/CUSTOMIZE][CUSTOMIZE]  to  learn  how  to 
+customize FreeType to specific environments.
 
-I. Standard procedure
----------------------
 
-  * If you use macro names  for FreeType header files (while mandatory
-    in earlier versions,  this is now optional  since FreeType version
-    2.6.1) it  is necessary to  disable pre-compiled headers.  This is
-    very important for Visual C++, because lines like
+## A. Standard procedure
+
+* If you use macro names  for FreeType header files (while mandatory
+  in earlier versions,  this is now optional  since FreeType version
+  2.6.1) it  is necessary to  disable pre-compiled headers.  This is
+  very important for Visual C++, because lines like
 
       #include FT_FREETYPE_H
 
-    are not  correctly supported  by this compiler  while being  ISO C
-    compliant!
+  are not  correctly supported  by this compiler  while being  ISO C
+  compliant!
 
-  * You need to add the directory `include' to your  include path when
-    compiling the library.
+* You need to add the directory `include` to your  include path when
+  compiling the library.
 
-  * FreeType 2 is made of several  components; each of them is located
-    in    a   subdirectory    of    `freetype/src'.    For    example,
-    `freetype/src/truetype/' contains the TrueType font driver.
+* FreeType 2 is made of several  components; each of them is located
+  in    a   subdirectory    of    `freetype/src`.    For    example,
+  `freetype/src/truetype/` contains the TrueType font driver.
 
-  * DO NOT COMPILE ALL C FILES!  Rather, compile the following ones.
+* DO NOT COMPILE ALL C FILES!  Rather, compile the following ones.
 
-    -- base components (required)
+  ### base components (required):
 
       src/base/ftsystem.c
       src/base/ftinit.c
@@ -55,7 +54,7 @@ I. Standard procedure
 
       src/base/ftmac.c        -- only on the Macintosh
 
-    -- font drivers (optional; at least one is needed)
+  ### font drivers (optional; at least one is needed)
 
       src/bdf/bdf.c           -- BDF font driver
       src/cff/cff.c           -- CFF/OpenType font driver
@@ -69,14 +68,13 @@ I. Standard procedure
       src/type42/type42.c     -- Type 42 font driver
       src/winfonts/winfnt.c   -- Windows FONT / FNT font driver
 
-    -- rasterizers (optional; at least one is needed for vector
-       formats)
+  ### rasterizers (optional; at least one is needed for vector formats)
 
       src/raster/raster.c     -- monochrome rasterizer
       src/sdf/sdf.c           -- Signed Distance Field driver
       src/smooth/smooth.c     -- anti-aliasing rasterizer
 
-    -- auxiliary modules (optional)
+  ### auxiliary modules (optional)
 
       src/autofit/autofit.c   -- auto hinting module
       src/cache/ftcache.c     -- cache sub-system (in beta)
@@ -90,54 +88,53 @@ I. Standard procedure
       src/psnames/psnames.c   -- PostScript glyph names support
 
 
-    Notes:
+  ## Notes:
 
-      `ftcache.c'  needs `ftglyph.c'
-      `ftfstype.c' needs `fttype1.c'
-      `ftglyph.c'  needs `ftbitmap.c'
-      `ftstroke.c' needs `ftglyph.c'
-      `ftsynth.c'  needs `ftbitmap.c'
+      `ftcache.c`  needs `ftglyph.c`
+      `ftfstype.c` needs `fttype1.c`
+      `ftglyph.c`  needs `ftbitmap.c`
+      `ftstroke.c` needs `ftglyph.c`
+      `ftsynth.c`  needs `ftbitmap.c`
 
-      `cff.c'      needs `sfnt.c', `pshinter.c', and `psnames.c'
-      `truetype.c' needs `sfnt.c' and `psnames.c'
-      `type1.c'    needs `psaux.c' `pshinter.c', and `psnames.c'
-      `type1cid.c' needs `psaux.c', `pshinter.c', and `psnames.c'
-      `type42.c'   needs `truetype.c'
+      `cff.c`      needs `sfnt.c`, `pshinter.c`, and `psnames.c`
+      `truetype.c` needs `sfnt.c` and `psnames.c`
+      `type1.c`    needs `psaux.c` `pshinter.c`, and `psnames.c`
+      `type1cid.c` needs `psaux.c`, `pshinter.c`, and `psnames.c`
+      `type42.c`   needs `truetype.c`
 
-      Please consult the central  `include/freetype/config/ftoption.h'
-      configuration file for details on additional libraries necessary
-      for some optional features.
+    Please consult the central  `include/freetype/config/ftoption.h`
+    configuration file for details on additional libraries necessary
+    for some optional features.
 
 
-  Read the file `CUSTOMIZE' in case  you want to compile only a subset
-  of  the  drivers,  renderers,   and  optional  modules;  a  detailed
-  description of the various base  extension is given in the top-level
-  file `modules.cfg'.
+Read the file `CUSTOMIZE` in case  you want to compile only a subset
+of  the  drivers,  renderers,   and  optional  modules;  a  detailed
+description of the various base  extension is given in the top-level
+file `modules.cfg`.
 
-  You are done.  In case of problems, see the archives of the FreeType
-  development mailing list.
+You are done.  In case of problems, see the archives of the FreeType
+development mailing list.
 
 
-II. Support for flat-directory compilation
-------------------------------------------
+## B. Support for flat-directory compilation
 
-  It is  possible to  put all  FreeType 2 source  files into  a single
-  directory, with the *exception* of the `include' hierarchy.
+It is  possible to  put all  FreeType 2 source  files into  a single
+directory, with the *exception* of the `include` hierarchy.
 
-  1. Copy all files in current directory
+1. Copy all files in current directory
 
-      cp freetype/src/base/*.[hc] .
-      cp freetype/src/raster1/*.[hc] .
-      cp freetype/src/smooth/*.[hc] .
-      etc.
+        cp freetype/src/base/*.[hc] .
+        cp freetype/src/raster1/*.[hc] .
+        cp freetype/src/smooth/*.[hc] .
+        etc.
 
-  2. Compile sources
+2. Compile sources
 
-      cc -c -Iinclude -DFT2_BUILD_LIBRARY ftsystem.c
-      cc -c -Iinclude -DFT2_BUILD_LIBRARY ftinit.c
-      cc -c -Iinclude -DFT2_BUILD_LIBRARY ftdebug.c
-      cc -c -Iinclude -DFT2_BUILD_LIBRARY ftbase.c
-      etc.
+        cc -c -Iinclude -DFT2_BUILD_LIBRARY ftsystem.c
+        cc -c -Iinclude -DFT2_BUILD_LIBRARY ftinit.c
+        cc -c -Iinclude -DFT2_BUILD_LIBRARY ftdebug.c
+        cc -c -Iinclude -DFT2_BUILD_LIBRARY ftbase.c
+        etc.
 
     You don't  need to define  the FT_FLAT_COMPILATION macro  (as this
     was required in previous releases of FreeType 2).
@@ -154,4 +151,5 @@ this file you  indicate that you have read  the license and 
understand
 and accept it fully.
 
 
---- end of INSTALL.ANY ---
+<!---->
+[CUSTOMIZE]: ./CUSTOMIZE
diff --git a/docs/INSTALL.CROSS b/docs/INSTALL_CROSS.md
similarity index 100%
rename from docs/INSTALL.CROSS
rename to docs/INSTALL_CROSS.md
diff --git a/docs/INSTALL.GNU b/docs/INSTALL_GNU.md
similarity index 100%
rename from docs/INSTALL.GNU
rename to docs/INSTALL_GNU.md
diff --git a/docs/INSTALL.MAC b/docs/INSTALL_MAC.md
similarity index 100%
rename from docs/INSTALL.MAC
rename to docs/INSTALL_MAC.md
diff --git a/docs/INSTALL_UNIX.md b/docs/INSTALL_UNIX.md
new file mode 100644
index 000000000..bc6323b7c
--- /dev/null
+++ b/docs/INSTALL_UNIX.md
@@ -0,0 +1,141 @@
+# Building FreeType on Unix Systems
+
+This also works for  emulations like Cygwin or MSys on Win32:
+
+
+1. **Ensure that you are using GNU Make**
+
+    The FreeType build system  _exclusively_ works with GNU Make.  You
+    will  not be  able to  compile the  library with  the instructions
+    below using any other alternative (including BSD Make).
+
+    Check that you have GNU make by running the command:
+    ```bash
+    make -v
+    ```
+
+    This should dump some text that begins with:
+
+        GNU Make  <version number>
+        Copyright (C) <year> Free Software Foundation Inc.
+
+    Note that version  3.81 or higher is *required* or the  build will
+    fail.
+
+    It is also fine to have GNU Make under another name (e.g. 'gmake')
+    if you use the MAKE variable as described below.
+
+    As  a  special exception,  'makepp'  can  also  be used  to  build
+    FreeType 2.  See the file `docs/MAKEPP` for details.
+
+    For builds  with `cmake` please check file `CMakeLists.txt`;  this
+    is a contributed file not directly supported by the FreeType team.
+
+
+2. **Regenerate the configure script if needed**
+
+    This only applies if you  are building a git snapshot or checkout,
+    *not* if you grabbed the sources of an official release.
+
+    You  need  to invoke  the  `autogen.sh`  script  in the  top-level
+    directory  in order  to  create the  `configure`  script for  your
+    platform.  Normally, this simply means typing:
+    ```bash
+    sh autogen.sh
+    ```
+
+    In case of problems, you may  need to install or upgrade Automake,
+    Autoconf or Libtool.  See  [INSTALL.md] for more information.
+
+
+3. **Build and install the library**
+
+    Say
+    ```bash
+    ./configure --help
+    ```
+
+    to see  the list of  possible configuration options  and important
+    environment  variables.  The `./configure` script  will detect  some
+    prerequisite  system  libraries  (libpng, brotli, etc.)  if  their
+    headers are available at the default locations.
+
+    The following  should work  on all Unix  systems where  the `make`
+    command invokes GNU Make:
+    ```bash
+    ./configure [options]
+    make
+    make install           (as root)
+    ```
+
+    The default installation path  is `/usr/local`.  It can be changed
+    with the `--prefix=<path>` option.  Example:
+    ```bash
+    ./configure --prefix=/usr
+    ```
+
+    When using  a different command  to invoke GNU Make,  use the MAKE
+    variable.  For example,  if `gmake` is the command  to use on your
+    system, do something like:
+    ```bash
+    MAKE=gmake ./configure [options]
+    gmake
+    gmake install            (as root)
+    ```
+
+    If  this still doesn't  work, there  must be  a problem  with your
+    system (e.g., you are using a very old version of GNU Make).
+
+    For library identification, FreeType's `configure` script uses the
+    `pkg-config` interface: Assuming it  needs library `foo`, it calls
+    the  `pkg-config` program  to find  information on  library `foo`,
+    which in turn  looks for a `foo.pc` file installed  at the system.
+    Some platforms,  however, don't come with  `pkg-support`; you then
+    have  to  use environment  variables  as  described by  `configure
+    --help`.  Example:
+    ```bash
+    LIBPNG_CFLAGS="-I/path/to/libpng/include/directory" \
+    LIBPNG_LIBS="-L/path/to/libpng/lib/directory" \
+    configure ...
+    ```
+    It  is possible  to  compile FreeType  in  a different  directory.
+    Assuming the FreeType source  files in directory `/src/freetype` a
+    compilation in directory `foo` works as follows:
+    ```bash
+    cd foo
+    /src/freetype/configure [options]
+    make
+    make install
+    ```
+
+
+3.1 **Interdependency with HarfBuzz**
+
+  Note that there  is a chicken-and-egg problem  currently since the
+  HarfBuzz library  (used by the  auto-hinter to improve  support of
+  OpenType  fonts)  depends on  FreeType,  which  can be  solved  as
+  follows in case HarfBuzz is not yet installed on your system.
+
+  1. Call    FreeType's     `configure`    script     with    option
+      `--without-harfbuzz`, then compile and install FreeType.
+
+  2. Compile and install HarfBuzz.
+
+  3. Call    FreeType's    `configure`   script    without    option
+      `--without-harfbuzz` (after  executing `make  distclean`), then
+      compile and install FreeType again.
+
+
+----------------------------------------------------------------------
+
+Copyright (C) 2003-2023 by
+David Turner, Robert Wilhelm, and Werner Lemberg.
+
+This  file is  part of  the FreeType  project, and  may only  be used,
+modified,  and distributed  under the  terms of  the  FreeType project
+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.
+
+<!---->
+[INSTALL.md]: ./INSTALL.md
diff --git a/docs/INSTALL.VMS b/docs/INSTALL_VMS.md
similarity index 100%
rename from docs/INSTALL.VMS
rename to docs/INSTALL_VMS.md