Improve build documentation.

Fixes #1012.

2 files changed, 39 insertions, 7 deletions

diff --git a/docs/INSTALL b/docs/INSTALL
index 4cede7375..de51d781d 100644
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -7,7 +7,19 @@ overview of the documentation available:
 I. Normal installation and upgrades
 ===================================
 
-  1. Unix Systems (including Mac OS X, Cygwin, and MSys on Windows)
+  0. Modify  `include/freetype/config/ftoption.h',  if  necessary,  to
+     control how the FreeType library gets built.  Normally, you don't
+     need to change anything.
+
+     Applications can't  control FreeType's  behaviour at  build time.
+     To make  applications control  (some of) FreeType's  behaviour at
+     run-time,    look    at    the    documentation    of    function
+     `FT_Property_Set'.
+
+  1. Unix and Unix-like systems
+
+    This also includes MacOS, Cygwin, MinGW + MSYS, Mingw-w64 + MSYS2,
+    and possibly other, similar environments.
 
     Please read `INSTALL.UNIX' to install or upgrade FreeType  2 on  a
     Unix system.   Note  that  you  *need*  GNU  Make   for  automatic
@@ -26,10 +38,11 @@ I. Normal installation and upgrades
 
   3. Other systems using GNU Make
 
-    On non-Unix platforms,  it is possible to build  the library using
-    GNU Make  utility.  Note that  *NO OTHER MAKE TOOL  WILL WORK*[1]!
-    This  methods supports  several  compilers on  Windows, OS/2,  and
-    BeOS, including MinGW, Visual C++, Borland C++, and more.
+    On some  non-Unix platforms, it  is possible to build  the library
+    using only  the GNU Make utility.   Note that *NO OTHER  MAKE TOOL
+    WILL  WORK*[1]!   This  methods   supports  several  compilers  on
+    Windows, OS/2, and BeOS,  including MinGW* (without MSYS*), Visual
+    C++, Borland C++, and more.
 
     Instructions are provided in the file `INSTALL.GNU'.
 
diff --git a/docs/INSTALL.UNIX b/docs/INSTALL.UNIX
index c22df347c..bdf42e277 100644
--- a/docs/INSTALL.UNIX
+++ b/docs/INSTALL.UNIX
@@ -44,14 +44,21 @@ or MSys on Win32:
 
       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
+    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 following  should work  on all Unix  systems where  the `make'
     command invokes GNU Make:
 
@@ -75,6 +82,18 @@ or MSys on Win32:
     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: