Docs: update and linearize build instructions; add installation overview material.

1 files changed, 188 insertions, 41 deletions

diff --git a/docs/usermanual-install-harfbuzz.xml b/docs/usermanual-install-harfbuzz.xml
index 899cc5bd..9d10e2da 100644
--- a/docs/usermanual-install-harfbuzz.xml
+++ b/docs/usermanual-install-harfbuzz.xml
@@ -1,70 +1,217 @@
 <chapter id="install-harfbuzz">
-  <title>Install HarfBuzz</title>
+  <title>Installing HarfBuzz</title>
+  
   <section id="download">
-    <title id="download.title">Download</title>
+    <title id="download.title">Downloading HarfBuzz</title>
     <para>
-      For tarball releases of HarfBuzz, look
-      <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">here</ulink>.
-      At the same place you will
-      also find Win32 binary bundles that include libharfbuzz DLL, hb-view.exe,
-      hb-shape.exe, and all dependencies.
+      The HarfBuzz source code is hosted at <ulink
+      url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>. The
+      same source tree is also available at the
+      <ulink
+	  url="http://cgit.freedesktop.org/harfbuzz/">Freedesktop.org</ulink>
+      site.
     </para>
     <para>
-      The canonical source tree is available
-      <ulink url="http://cgit.freedesktop.org/harfbuzz/">here</ulink>.
-      Also available on <ulink url="https://github.com/harfbuzz/harfbuzz">github</ulink>.
+      Tarball releases and Win32 binary bundles (which include the
+      libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all
+      dependencies) of HarfBuzz can be downloaded from <ulink
+      url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz/releases</ulink>
+      or from 
+      <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">Freedesktop.org</ulink>.
     </para>
     <para>
-      The API that comes with <filename class='headerfile'>hb.h</filename> will
-      not change incompatibly. Other, peripheral, headers are more likely to go
-      through minor modifications, but again, will do our best to never change
-      API in an incompatible way. We will never break the ABI.
+      Release notes are posted with each new release to provide an
+      overview of the changes. The project <ulink url="https://github.com/harfbuzz/harfbuzz/issues">tracks bug
+      reports and other issues</ulink> on GitHub. Discussion and
+      questions are welcome on the <ulink
+      url="http://freedesktop.org/mailman/listinfo/harfbuzz/">HarfBuzz
+      mailing list</ulink>.
     </para>
     <para>
-      If you are not sure whether Pango or HarfBuzz is right for you, read
-      <ulink url="http://mces.blogspot.in/2009/11/pango-vs-harfbuzz.html">this</ulink>.
+      The API included in the <filename
+      class='headerfile'>hb.h</filename> file will not change in a
+      compatibility-breaking way in any release. However, other,
+      peripheral headers are more likely to go through minor
+      modifications. We will do our best to never change APIs in an
+      incompatible way. We will <emphasis>never</emphasis> break the ABI. 
     </para>
   </section>
+  
   <section id="building">
-    <title>Building</title>
+    <title>Building HarfBuzz</title>
+
+    <section id="building.linux">
+      <title>Building on Linux</title>
     <para>
-      On Linux, install the development packages for FreeType, Cairo, and GLib.
-      For example, on Ubuntu / Debian, you would do:
-      <programlisting>
-<command>sudo apt-get install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
-      </programlisting>
-      whereas on Fedora, RHEL, CentOS, and other Red Hat based systems you would do:
+      <emphasis>(1)</emphasis> To build HarfBuzz on Linux, you must first install the
+      development packages for FreeType, Cairo, and GLib. The exact
+      commands required for this step will vary depending on
+      the Linux distribution you use.
+    </para>
+    <para>
+      For example, on an Ubuntu or Debian system, you would run:
       <programlisting>
-<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
+	<command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
       </programlisting>
-      or using MacPorts:
+      On Fedora, RHEL, CentOS, or other Red-Hat&ndash;based systems, you would run:
       <programlisting>
-<command>sudo port install</command> <package>freetype glib2 cairo</package>
+	<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
       </programlisting>
+
+    </para>
+    
+    <para>
+      <emphasis>(2)</emphasis> The next step depends on whether you
+      are building from the source in a downloaded release tarball or
+      from the source directly from the git repository.
+    </para>
+    <para>
+      <emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz
+      source code in a tarball, you can now extract the source.
+    </para>
+    <para>
+      From a shell in the top-level directory of the extracted source
+      code, you can run <command>./configure</command> followed by
+      <command>make</command> as with any other standard package.
+    </para>
+    <para>
+      This should leave you with a shared
+      library in the <filename>src/</filename> directory, and a few
+      utility programs including <command>hb-view</command> and
+      <command>hb-shape</command> under the <filename>util/</filename>
+      directory.
     </para>
     <para>
-      If you are using a tarball, you can now proceed to running
-      <command>configure</command> and <command>make</command> as with any
-      other standard package. That should leave you with a shared library in
-      <filename>src/</filename>, and a few utility programs including hb-view
-      and hb-shape under <filename>util/</filename>.
+      <emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git
+      repository, rather than installing from a downloaded tarball
+      release, then you must install two more auxiliary tools before you 
+      can build for the first time: <package>pkg-config</package> and
+      <ulink url="http://www.complang.org/ragel/">ragel</ulink>.
     </para>
     <para>
-      If you are bootstrapping from git, you need a few more tools before you
-      can run <filename>autogen.sh</filename> for the first time. Namely,
-      pkg-config and <ulink url="http://www.complang.org/ragel/">ragel</ulink>.
-      Again, on Ubuntu / Debian:
+      On Ubuntu or Debian, run:
       <programlisting>
-<command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
+	<command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
       </programlisting>
-      and on Fedora, RHEL, CentOS:
+      On Fedora, RHEL, CentOS, run:
       <programlisting>
-<command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+	<command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
       </programlisting>
-      or using MacPorts:
+      
+    </para>
+    <para>
+      With <package>pkg-config</package> and <package>ragel</package>
+      installed, you can now run <command>./autogen.sh</command>,
+      followed by <command>./configure</command> and
+      <command>make</command> to build HarfBuzz.
+    </para>
+    </section>
+
+    
+    <section id="building.windows">
+      <title>Building on Windows</title>
+
+      <para>
+	On Windows, consider using Microsoft's free <ulink
+	url="https://github.com/Microsoft/vcpkg">vcpkg</ulink> utility
+	to build HarfBuzz, its dependencies, and other open-source
+	libraries. 
+      </para>
+      <para>
+	If you need to build HarfBuzz from source, first put the
+	<program>ragel</program> binary on your
+	<literal>PATH</literal>, then follow the appveyor CI cmake
+	<ulink
+	    url="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml">build
+	instructions</ulink>. 
+      </para>
+    </section>
+
+    
+    <section id="building.macos">
+      <title>Building on macOS</title>
+
+      <para>
+	There are two ways to build HarfBuzz on Mac systems: MacPorts
+	and Homebrew. The process is similar to the process used on a
+	Linux system.
+      </para>
+      <para>
+	<emphasis>(1)</emphasis> You must first install the
+	development packages for FreeType, Cairo, and GLib. If you are
+	using MacPorts, you should run:
       <programlisting>
-<command>sudo port install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+	<command>sudo port install</command> <package>freetype glib2 cairo</package>
       </programlisting>
-    </para>
+      </para>
+      <para>
+	If you are using Homebrew, you should run:
+	<programlisting>	
+	  <command>brew install</command> <package>freetype glib cairo</package>
+	</programlisting>
+      </para>
+      <para>
+	<emphasis>(2)</emphasis> The next step depends on whether you are building from the
+	source in a downloaded release tarball or from the source directly
+	from the git repository.
+      </para>
+      <para>
+	<emphasis>(2)(a)</emphasis> If you are installing HarfBuzz
+	from a downloaded tarball release, extract the tarball and
+	open a Terminal in the extracted source-code directory. Run:
+	<programlisting>
+	  <command>./configure</command>
+	</programlisting>
+	followed by:
+	<programlisting>	
+	  <command>make</command>
+	</programlisting>
+	to build HarfBuzz.
+      </para>
+      <para>
+	<emphasis>(2)(b)</emphasis> Alternatively, if you are building
+	HarfBuzz from the source in the HarfBuzz git repository, then
+	you must install several built-time dependencies before
+	proceeding.
+      </para>
+      <para>If you are
+	using MacPorts, you should run:
+      <programlisting>
+	<command>sudo port install</command> <package>autoconf
+	automake libtool pkgconfig ragel gtk-doc</package> 
+      </programlisting>
+      to install the build dependencies.
+      </para>
+      <para>If you are using Homebrew, you should run:
+	<programlisting>	
+	  <command>brew install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+	</programlisting>
+      	Finally, you can run:
+	<programlisting>
+	  <command>./autogen.sh</command>
+	</programlisting>
+      </para>
+      <para>
+	<emphasis>(3)</emphasis> You can now build HarfBuzz (on either
+	a MacPorts or a Homebrew system) by running:
+	<programlisting>
+	  <command>./configure</command>
+	</programlisting>
+	followed by:
+	<programlisting>
+	  <command>make</command>
+	</programlisting>
+      </para>
+      <para>
+	This should leave you with a shared
+	library in the <filename>src/</filename> directory, and a few
+	utility programs including <command>hb-view</command> and
+	<command>hb-shape</command> under the <filename>util/</filename>
+	directory.
+      </para>      
+	
+    </section>
+
+    
   </section>
 </chapter>