Updated CONTRIBUTING.md to match new build setup and source files

1 files changed, 79 insertions, 198 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d05364532..85496cf97 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,201 +3,125 @@
 First off, thank you for considering contributing to Inter UI.
 It's people like you that make the Internet such a great place.
 
-Following these guidelines helps to communicate that you respect the time of
-the people managing and developing this open source project.
-In return, they should reciprocate that respect in addressing your issue or
-suggestion.
+Following these guidelines helps to communicate that you respect the time of the people managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue or suggestion.
 
-By contributing work to the Inter UI font project you agree to have all work
-contributed becoming the intellectual property of the Inter UI font project as
-described by [SIL Open Font License, Version 1.1](http://scripts.sil.org/OFL)
+By contributing work to the Inter UI font project you agree to have all work contributed becoming the intellectual property of the Inter UI font project as described by [SIL Open Font License, Version 1.1](http://scripts.sil.org/OFL)
 
 
 ## Types of contributions this project is looking for
 
-Inter UI is still an early product and so there is a lot of fun things to do.
+**More glyphs!** Several glyphs, especially non-latin ones, are placeholders that need to be replaced with ones designed in the style of Inter UI. Cyrillic glyphs are especially requested.
 
-- More glyphs! There are many placeholder glyphs that need to be replaced with
-  ones designed in the style of Inter UI.
-  - Non-English glyphs are especially needed
+**Kerning**, kerning, kerning — there are so many pairs and pairs-in-words that need to be kerned, or have their kerning improved. When adding kerning, use _groups_ rather than individual pairs. See [Kerning](#kerning) for more information.
 
-- Improvements and corrections to existing glyphs
-
-- Kerning, kerning, kerning — there are so many pairs and pairs-in-words that
-  need to be kerned, or have their kerning improved. When adding kerning, try
-  to use `@GROUPS` (groups.plist in the UFO source directories.)
-
-- A thin "master" font that can additionally be used to derive interpolated
-  weights in between "regular" and "thin." This is a very large project and
-  should probably be done in a branch over a longer period of time, rather than
-  as one huge contribution/pull request.
+**Thin "master" style** for lighter weights. This is a very large project and should probably be done in a branch over a longer period of time, rather than as one huge contribution/pull request.
 
 
 ### Master fonts and interpolated derivatives
 
-This project uses "master fonts", or "key fonts" which are combined using
-some clever math to generate other fonts that is a "mix" of two "masters."
-Because of this, there are some **very important rules** you must stick to:
+This project uses "master styles" (or "key styles") which are combined using some clever math to generate other styles that are "mixed" from two masters. Because of this, there are some **very important rules** you must stick to:
 
-- When adding or removing a glyph, you _must_ add or remove the same glyph in
-  all master fonts.
-- When modifying a glyph's contours, the corresponding glyphs in all masters must:
-  - Have the same amount of contours (aka "shapes")
-  - Have the same amount of points in roughly the same locations
-  - Each point must have the same amount and kind of handles
-  - Each contour's winding direction must match
+- When adding or removing a glyph, you _must_ add or remove the same glyph in all master fonts. If you're using Glyphs.app, this is automatically taken care of, but not with RoboFont or some other font tools.
+- When modifying a glyph's contours, we must make sure:
+    - all masters have the same amount of paths, nodes and handles, as well as components.
+    - all components, paths, nodes and handles are in the same order across all masters.
+    - all masters have the same set of anchors.
 
-Unless these rules are followed, generated weights will fail to build.
-If you are uncertain, simply try building a generated weight like "Medium" — the
-build system will tell you when a glyph fails to "mix" with an error message.
+If these rules are not followed, generated styles will fail to build.
 
-To make life a little easier when working on glyphs, the build system will not stop
-if there's a glyph-mixing error, but instead just pick a glyph from one of the
-master weights and continue. For this reason you need to look at the output from
-the build system and watch out for "mixglyph" error messages. They look like this:
+[Multiple Masters: Keeping Your Outlines Compatible](https://glyphsapp.com/tutorials/multiple-masters-part-2-keeping-your-outlines-compatible) is a great article on this topic.
 
-```
-mixglyph failed for J
-```
 
+## Compiling font files
 
-### Generated glyphs
+There are two ways by which you can generate font files (OTF, TTF, WOFF2, etc) from the sources files:
 
-Many glyphs which are based on basic latin characters are generated by composing
-other glyphs. These are defined in `src/diacritics.txt` where each line of the
-file defines one "composition" that names a base glyph followed by the name of
-one or more additional glyphs, followed by anchor names which are used for alignment.
+- Using the "export" feature in font editors like [Glyphs](https://glyphsapp.com/) or [RoboFont](http://robofont.com/)
+- Using Inter UI's own build system (which requires no external tools.)
 
-For example `Ά` U+0386 "GREEK CAPITAL LETTER ALPHA WITH TONOS" is composed from
-`A` and `tonos`, aligned on the "tonos" anchor.
-It's defined like this in `src/diacritics.txt`:
+Exporting from font editors is a great alternative if you just want to test things out, but using Inter UI's own build system is the way to go for "production quality" font files. The rest of this section covers how to use Inter UI's own build system, aka _the toolchain_.
 
-```
-A+tonos:tonos=Alphatonos
-```
+### Using the toolchain
 
-"Alphatonos" is a glyph name defined in `src/glyphlist.txt` which maps names to
-Unicode code points.
+Currently the toolchain has only been tested on macOS, and all you need is [Python](https://www.python.org/), which comes pre-installed with macOS, so no need to install anything. Python can easily be installed in Windows, Linux and other OSes.
 
-When you see a name starting with "uni" followed by some hexadecimal digits, that
-means no symbolic name has been assigned to that glyph, but it maps to a Unicode
-code point. For instance:
+You'll want to open a Terminal for this.
+
+The first step is to initialize the toolchain itself:
 
 ```
-E+grave:top=uni0400
+./init.sh
 ```
 
-Creates Composes `Ѐ` U+0400 "CYRILLIC CAPITAL LETTER IE WITH GRAVE"
-from "E" and "grave" aligned on the "top" anchor.
-
-If we were to introduce a glyph named `uni0400` into the UFO source file, that
-glyph would be used instead of the composition when a font is built. This allows
-us to define a "baseline" of glyph compositions in `src/diacritics.txt` and then
-progressively introduce specially-designed glyphs on a per font basis.
-
-When doing this, you still have to be careful about the [master interpolation rules](#master-fonts-and-interpolated-derivatives).
-
-
-### `src/fontbuild.cfg`
-
-`src/fontbuild.cfg` defines a lot of things that directs the font build system.
+This will fetch, setup and configure everything needed to build and test Inter UI.
 
-- What glyphs to decompose (flatten; remove components)
-- What glyphs should have a lesser italic angle when generating italic fonts
-- What glyphs shouldn't be italicized at all when generating italic fonts
-- What glyphs should be _excluded_ (or "removed") from resulting font files
-  (some glyphs are only used as components and don't correspond to an actual
-  glyph in the end-result font file.)
-- Other information, like version, author, build system cache directory, etc.
+> **—Important—** Run `init.sh` everytime you pull new changes to the source code or before pushing source code to a remote repository. `init.sh` may update the UFO source files and makefile, changes which may be required to be included in a source code change.
 
+We can now run `make` to build all font files:
 
-## Building
+```
+$ make -j
+```
 
-Prerequisites:
+This may take a long time (a few minutes) the first time as it generates "font instances" (i.e. all styles that are derived through interpolation from the master styles) in addition to compiling the actual font files (OTF, TTF, etc.)
 
-- Python 2.7 with pip (you get pip with `brew install python`)
-- [virtualenv](https://virtualenv.pypa.io/)
+The toolchain comes with a few other useful actions, one of them is `test` which runs some checks on the compiled font files to make sure they behave as intended:
 
 ```
-$ ./init.sh
+$ make -j test
 ```
 
-This will generate makefile support, dependencies required by the toolchain, etc.
-At the end, the script prints instructions for how to activate `virtualenv`.
-As a convenience, you can also source init.sh to activate virtualenv.
 
-We can now run `make` to build all font files:
+### Try & sample as you go
 
-```
-$ make
-```
+When making changes to the typeface and its source files, it's a good idea to sample your changes not only in a font editor or graphics editor, but also in real-world scenarios.
 
-Or just specific styles:
+There are two things in particular that will help you with this:
 
-```
-$ make Regular BoldItalic
-```
+- `make -j STYLE_FORMAT` to quickly compile only a particular style
+- Interactive "Lab"
 
-Or all fonts but only TrueType format (no web file formats):
+You can invoke `make` with either names of styles, names of styles and file formats, or even specific filenames. Here are a few examples:
 
 ```
-$ make all_ttf
+make -j Regular BoldItalic    # Regular and Bold Italic
+make -j all_ttf               # All styles but only TTF files
+make -j MediumItalic_web      # Medium Italic as TTF, WOFF and WOFF2
+make -j build/hinted/Bold.ttf # Bold TTF with autohints
 ```
 
-Or just specific styles and formats:
+All resulting font files are written to the `build` directory with `InterUI-` as the filename prefix. The `Makefile` file contains information about more possibilities of `make`.
+
+[**The interactive Lab**](#interactive-lab) is a great tool for quickly exploring your font files. It's a web-based tool which you start in a terminal by running:
 
 ```
-# Regular in all formats, BoldItalic in only TrueType format
-$ make Regular BoldItalic_ttf
+python docs/lab/serve.py
 ```
 
-You can also specify specific style + file format to `make` through `build/InterUI-STYLE.FORMAT`.
-E.g.
+Open up the URL printed on the screen and you can now explore your font files. Simply `make -j STYLE_web` (or `make -j all_web` for all styles) and reload the web page to try a new build.
 
-- `make build/dist-unhinted/InterUI-MediumItalic.otf`
-- `make build/dist-unhinted/InterUI-Bold.woff2`
-- `make build/dist-hinted/InterUI-Regular.ttf`
-- `...`
+See [Interactive Lab](#interactive-lab) for more details.
 
-All resulting font files are written to the `build` directory with `InterUI-` as the filename prefix.
 
-Note: Making all files takes a considerable amount of time.
-It's a CPU and I/O intensive task to compile the fonts and so the build system has been setup to
-be able to run many jobs in parallel. Therefore it's recommended to pass the [`-j` flag to make](https://www.gnu.org/software/make/manual/html_node/Parallel.html) and
-optionally pipe the fairly verbose output to /dev/null, e.g. `make -j 8 >/dev/null`.
+### Editing source files
 
+This font is stored and authored primarily in a unified [Glyphs](https://glyphsapp.com/) `.glyphs` file. However, if you prefer to use a different font editor, the master styles are also maintained as [UFO (Unified Font Object)](http://unifiedfontobject.org/) files and can be edited by lots of font software, some free like (FontForge)[https://fontforge.github.io/], some commercial like [RoboFont](http://robofont.com/).
 
-### Editing
+> **—Important—** The UFO source files are generated from the Glyphs source file. Editing the Glyphs file will cause the UFO files to be over-written. You have to commit to editing _either_ the .glyphs file _or_ the .ufo files.
 
-This font is stored and authored in the [Unified Font Object (UFO)](http://unifiedfontobject.org/) file format and can be edited by many different software, some free. However, it's only been "tested" with [RoboFont](http://robofont.com/) which is a popular commercial font editor. There's a 30 day fully-functional free trial version of the app, so you can use it for smaller contributions without needing to buy a RoboFont license.
-
-To make life easier for you, configure RoboFont's settings like this:
+To make life easier for you, configure your editor as follows:
 
 - Set the grid to 128 units. This means that each grid square equals one pixel at 2x scale.
 - Set "Snap points to" to a reasonably high number that's a power-of-two, like 8.
 - Set "SHIFT increment" to 16
 - Set "CMD SHIFT increment" to 128
 
-When you've made an edit, simply save your changes and run make:
-
-```
-$ make
-```
-
-*For quick turnaround, consider:*
-
-- Build and test only the "Regular" style.
-- Use `misc/notify` to get desktop notifications on builds so that you don't have to sit and wait looking at the terminal while it's building.
-
-E.g. `misc/notify make Regular`
-
-See ["Building"](#Building) for more details.
+Note: If you're using Glyphs, this will already be the case as this information is stored in the .glyphs file.
 
 
-### Preview & debug
+### Interactive Lab
 
-This project comes with a simple web-based application for debugging and
-previewing the font. It's a very useful tool to have when working on the font.
+This project comes with a simple web-based application for debugging and previewing the font. It's a very useful tool to have when working on the font.
 
 - Comes with a large body of sample text data (which is also editable.)
 - Provides samples of the most common latin-script pairs, useful for kerning.
@@ -213,107 +137,64 @@ previewing the font. It's a very useful tool to have when working on the font.
   `lowercase`, etc.
 - Ability to compare Inter UI side-by-side with other fonts.
 
-![Preview app screenshot](docs/res/preview-app.png)
-
-The following will start a local web server (which is only accessible from your local computer; not the internet) that serves the debug-and-preview app:
+To start the lab, simply run this in a terminal (and keep the terminal running.)
 
 ```
-$ docs/serve.sh &
+python docs/lab/serve.py
 ```
 
-You can now visit `http://localhost:2015/lab/`.
-After you rebuild some font files, reload the web page to refresh fonts.
+You can now visit the URL printed on the screen to use the lab. Simply `make -j STYLE_web` (or `make -j all_web` for all styles) and reload the web page to try a new build.
 
 
 ### Kerning
 
-Kerning is the concept of harmony in the pace of characters, defined as a set of distances
-between specific character pairs, like "A" & "c".
-Good kerning makes words more readable. Oftentimes this means that when adjusting kerning,
-you have to look at whole words and sentences when adjusting the kerning of a pair, since
-the spacing between two characters should work in harmony with the spacing of all other characters.
+Kerning is the concept of harmony in the pace of characters, defined as a set of distances between specific character pairs, like "A" & "c". Good kerning makes words more readable. Oftentimes this means that when adjusting kerning, you have to look at whole words and sentences when adjusting the kerning of a pair, since the spacing between two characters should work in harmony with the spacing of all other characters.
+
+All major font editors provide user interfaces for previewing and adjusting kerning. There is even dedicated software specifically for working with kerning.
 
-All major font editors provide user interfaces for previewing and adjusting kerning.
+When adding kerning, use _kerning groups_ rather than specific pairs.
 
-When adding or adjusting kerning:
+- If you're using Glyphs, read more about kerning and how the "padlock" icon affects kerning specific pairs vs groups here: <https://glyphsapp.com/tutorials/kerning>
+- If you're editing the UFO files, the groups can be found in the `groups.plist` files.
 
-- Make sure to use kerning groups (`src/Inter-UI-*.ufo/groups.plist`)
+If a glyphname is missing in kerning groups, define a new group for it. Group name should reflect the most prominent or common glyph that belongs to the group. For example, "V" for a group containing "Y", "Ÿ", "V" and "W". A kerning group is specific to one "side" of a glyph (left or right) and therefore the name should reflect a glyph which side is the most relevant one. For instance, consider the character "D" which on the left side looks like "M" and "L" but on the right side looks like "O" and "C". It belongs to the "O left" group and the "M right" group. Similarly for "g" ("o left", "m right"), "p" ("m left", "o right") and many other glyphs.
 
-- If a glyphname is missing in kerning groups, define a new group for it.
-  Group naming scheme is: `@KERN_<DIRECTION>_<NAME>` where `<DIRECTION>`
-  is either `LEFT` or `RIGHT`, depending on if the group represents the left-hand side
-  of a pair or the right-hand side. `<NAME>` is the name of a glyph that most commonly
-  represents the group. For instance, for all glyphs that has a left-side shape similar
-  to "c", like "d", the group name is "c". This makes it easy to test kerning of groups
-  by just using the `<NAME>` part in previews.
+Kerning groups is a really simple but incredibly time-saving way of kerning a font.
 
-- Try to submit image samples of kerning adjustments with your pull requests whenever
-  feasible.
+> Tip: Include sample images of kerning adjustments with code pull requests that affect kerning.
 
-The script `misc/kernsample.py` is helpful in generating samples for all existing
-right-hand side characters given a left-hand side glyphname.
+The script `misc/tools/kernsample.py` is helpful in generating samples for all existing right-hand side characters given a left-hand side glyphname.
 
 ```txt
 $ misc/kernsample.py src/Inter-UI-Black.ufo P -suffix MOR
 PAMOR P/AE MOR PJMOR PXMOR PYMOR PZMOR P/ae mor P/ampersand mor P/backslash mor P/dzcaron mor P/eightsub mor P/ellipsis mor Pfmor P/four mor P/guilsinglleft mor P/idieresisacute mor P/periodcentered mor P/quotedblbase mor Psmor P/seven mor P/slash mor Ptmor P/two mor P/underscore mor Pymor
 ```
 
-Type `misc/kernsample.py -h` for help on how to use the program.
-
-This only includes existing kerning and is thus only useful for adjustments.
-Additions must still be done manually.
+Type `misc/tools/kernsample.py -h` for help on how to use the program.
 
+This only includes existing kerning and is thus only useful for adjustments. Additions must still be done manually.
 
-### Removing glyphs
 
-Removal of glyphs is a bit tricky both because there are a lot of places in
-which a glyph might be referenced and used, as well as the fact that many
-glyphs uses composition where removal of one glyph might cause other glyphs to
-have their component instances be broken disappear.
+### Miscellaneous tools
 
-There's a script which takes care of 95% of this process for you: `misc/rmglyph.py`
+There are several tools included with Inter UI to help "wrangle" metrics, generate glyphs, create PDFs and so on. You can find these tools in the `misc/tools` directory. They are all command-line tools and their usage can be queried by providing the help flag `-h`.
 
-Before running, make sure your git working tree is clean (at least the `src` folder),
-then run something like this:
+For example, the fontinfo tool can be used to generate a JSON description of all metadata and merics of a TTF or OTF file:
 
 ```
-misc/rmglyph.py -decompose -dry glyphname1 U+1234 U+1235-1238
+misc/tools/fontinfo.py -h
 ```
 
-Run without `-dry` to write the effects to the file system (safe when you have a clean working directory; just `git checkout src` to "undo")
-
-Run with `-h` for details on usage.
-
 
 ## FAQ
 
-> Do I need RoboFont?
+> Do I need Glyphs or RoboFont to build font files?
 
-No, you don't. To build font files, all you need is Python. To edit the font files, you need something that can edit UFO files (like [RoboFont](http://robofont.com/) or a text editor.)
+No, you don't. To build font files, all you need is Python. To edit the font files, you need something that can edit .glyphs or UFO files.
 
 ----
 
-> `KeyError: 'Lj'` when building
-
-This probably means that you need to run `./init.sh` to setup the case-sensitive virtual file system mount that is needed by the font build system. Unfortunately the toolchain used (which is the same as for Roboto) requires not only a case-preserving file system, but also a case-sensitive one.
-
-----
-
-> `ImportError: No module named robofab.objects.objectsRF`
-
-Python virtualenv not configured. Run `. init.sh`
-
-----
-
-> `make: *** No rule to make target ...`
-
-Run `./init.sh` to update the generated makefile.
-
-----
+> I'm getting errors when running `make` in my terminal
 
-> How can I inspect a compiled font file?
+This probably means that you need to run `./init.sh`
 
-Use the fontinfo.py tool which outputs JSON describing all properties of
-one or more font files.
-See `misc/fontinfo.py -h` for details.
-Example use: `misc/fontinfo.py -pretty build/dist-unhinted/Inter-UI-BoldItalic.ttf`