Add README.wine.md and touch some other docs (#939)

Makefile.am

@@ -9,7 +9,8 @@ SUBDIRS = src util test docs
 EXTRA_DIST = \
 	autogen.sh \
 	harfbuzz.doap \
-	README.python \
+	README.python.md \
+	README.wine.md \
 	BUILD.md \
 	RELEASING.md \
 	CMakeLists.txt \

README.python.md

@@ -2,11 +2,15 @@ To enable HarfBuzz bindings for Python among other languages, make sure
 you have latest version of gobject-introspection available.  On Ubuntu,
 you can install that this way:
 
-  sudo apt-get install libgirepository1.0-dev
+```bash
+sudo apt-get install libgirepository1.0-dev
+```
 
 And then run autogen.sh (if building from git), and then:
 
-  ./configure --with-gobject --enable-introspection
+```bash
+./configure --with-gobject --enable-introspection
+```
 
 Make sure that gobject-introspection is enabled then in the final report.
 
@@ -21,7 +25,9 @@ $prefix/lib/girepository-* directory.
 Make sure you have pygobject installed.  Then check that the following
 import works in your Python interpretter:
 
-  from gi.repository import HarfBuzz
+```python
+from gi.repository import HarfBuzz
+```
 
 If it does, you are ready to call HarfBuzz from Python!  Congratulations.
 See src/sample.py.

README.wine.md

@@ -0,0 +1,40 @@
+For the development of HarfBuzz, the Microsoft shaping technology, Uniscribe,
+as a widely used and tested shaper is used as more-or-less OpenType reference
+implemenetation and that specially is important where OpenType specification
+is or wasn't that clear. For having access to Uniscribe on Linux/macOS these
+steps are recommended:
+
+1. Install Wine from your favorite package manager.
+
+2. And `mingw-w64` compiler.
+   With `brew` on macOS, you can have it like `brew install mingw-w64`
+
+3. Download and put [this](https://drive.google.com/open?id=0B3_fQkxDZZXXbWltRGd5bjVrUDQ)
+   on your `~/.local/i686-w64-mingw32`.
+
+4. Replace all the instances of `/home/behdad/.local/i586-mingw32msvc`
+   and `/home/behdad/.local/i686-w64-mingw32` with `<$HOME>/.local/i686-w64-mingw32`
+   on that folder. (`<$HOME>` replace it with `/home/XXX` or `/Users/XXX` on macOS)
+
+   Probably you shouldn't replace the ones are inside binaries.
+
+5. `NOCONFIGURE=1 ./autogen.sh && mkdir winbuild && cd winbuild`
+
+6. `../mingw32.sh --with-uniscribe && cd ..`
+
+7. `make -Cwinbuild`
+
+Now you can use hb-shape using `wine winbuild/util/hb-shape.exe` but if you like to
+to use the original Uniscribe,
+
+8. Bring a 32bit version of `usp10.dll` for youself from `C:\Windows\SysWOW64\usp10.dll` of your
+   Windows installation (asuming you have a 64-bit installation, otherwise `C:\Windows\System32\usp10.dll`)
+   that it is not a DirectWrite proxy ([for more info](https://en.wikipedia.org/wiki/Uniscribe)).
+   Rule of thumb, your `usp10.dll` should have a size more than 500kb, otherwise
+   it is designed to work with DirectWrite which Wine can't work with its original one.
+
+   Put the dll on the folder you are going to run the next command,
+
+9. `WINEDLLOVERRIDES="usp10=n" wine winbuild/util/hb-shape.exe fontname.ttf -u 0061,0062,0063 --shaper=uniscribe`
+
+(`0061,0062,0063` means `abc`, use test/shaping/hb-unicode-decode to generate ones you need)

RELEASING.md

@@ -15,23 +15,26 @@ HarfBuzz release walk-through checklist:
 2. Based on severity of changes, decide whether it's a minor or micro release
    number bump,
 
-3. Make sure you have correct date and new version at the top of NEWS file,
+3. Search for REPLACEME on the repository and replace it with the chosen version
+   for the release.
 
-4. Bump version in configure.ac line 3,
+4. Make sure you have correct date and new version at the top of NEWS file,
 
-5. Do "make distcheck", if it passes, you get a tarball.
+5. Bump version in configure.ac line 3,
+
+6. Do "make distcheck", if it passes, you get a tarball.
    Otherwise, fix things and commit them separately before making release,
 
-6. "make release-files".  Enter your GPG password.  This creates a sha256 hash
+7. "make release-files".  Enter your GPG password.  This creates a sha256 hash
    and signs it.
 
-7. Now that you have release files built, commit NEWS and configure.ac changes.
+8. Now that you have release files built, commit NEWS and configure.ac changes.
    The commit message is simply the release number.  Eg. "1.4.7"
 
-8. Tag the release and sign it: Eg. "git tag -s 1.4.7 -m 1.4.7".  Enter your
+9. Tag the release and sign it: Eg. "git tag -s 1.4.7 -m 1.4.7".  Enter your
    GPG password again.
 
-9. Build win32 bundle.
+10. Build win32 bundle.
 
    a. Put contents of [this](https://drive.google.com/open?id=0B3_fQkxDZZXXbWltRGd5bjVrUDQ) on your `~/.local/i686-w64-mingw32`,
 
@@ -41,7 +44,7 @@ HarfBuzz release walk-through checklist:
 
    d. Back in the parent directory, run `./UPDATE.sh` (available below) to build win32 bundle.
 
-10. Copy all artefacts to users.freedesktop.org and move them into
+11. Copy all artefacts to users.freedesktop.org and move them into
     `/srv/www.freedesktop.org/www/software/harfbuzz/release` There should be four
     files.  Eg.:
  ```
@@ -51,15 +54,15 @@ HarfBuzz release walk-through checklist:
 -rw-r--r--  1 behdad eng 2895619 Jul 18 11:34 harfbuzz-1.4.7-win32.zip
 ```
 
-11. While doing that, quickly double-check the size of the .tar.bz2 and .zip
+12. While doing that, quickly double-check the size of the .tar.bz2 and .zip
     files against their previous releases to make sure nothing bad happened.
     They should be in the ballpark, perhaps slightly larger.  Sometimes they
     do shrink, that's not by itself a stopper.
 
-12. Push the commit and tag out: "git push --follow-tags".  Make sure it's
+13. Push the commit and tag out: "git push --follow-tags".  Make sure it's
     pushed both to freedesktop repo and github.
 
-13. Go to GitHub release page [here](https://github.com/harfbuzz/harfbuzz/releases),
+14. Go to GitHub release page [here](https://github.com/harfbuzz/harfbuzz/releases),
     edit the tag, upload artefacts and NEWS entry and save.