From 797757bde2e305e035bcba65a93993ecd0716398 Mon Sep 17 00:00:00 2001 From: Rasmus Andersson Date: Tue, 22 Aug 2017 10:23:13 -0700 Subject: adds CONTRIBUTING.md and license info for fallback glyph contours in src --- CONTRIBUTING.md | 244 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 CONTRIBUTING.md (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..b10983f28 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,244 @@ +# Contributing to the Interface font project + +First off, thank you for considering contributing to Interface. +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. + +By contributing work to the Interface font project you agree to have all work +contributed becoming the intellectual property of the Interface 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 + +Interface is still an early product and so there is a lot of fun things to do. + +- More glyphs! There are many placeholder glyphs that need to be replaced with + ones designed in the style of Interface. + - Non-English glyphs are especially needed + +- 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. + + +### 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: + +- 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 + +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. + +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 "mix glyph" error messages. + + +### Generated glyphs + +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. + +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`: + +``` +A+tonos:tonos=Alphatonos +``` + +"Alphatonos" is a glyph name defined in `src/glyphlist.txt` which maps names to +Unicode code points. + +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: + +``` +E+grave:top=uni0400 +``` + +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. + +- 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. + + +## Building + +Prerequisites: + +- Python 2.7 with pip (you get pip with `brew install python`) +- [virtualenv](https://virtualenv.pypa.io/) + +``` +$ ./init.sh +``` + +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: + +``` +$ make +``` + +Or just specific styles: + +``` +$ make Regular BoldItalic +``` + +Or all fonts but only TrueType format (no web file formats): + +``` +$ make all_ttf +``` + +Or just specific styles and formats: + +``` +# Regular in all formats, BoldItalic in only TrueType format +$ make Regular BoldItalic_ttf +``` + +You can also specify specific style + file format to `make` through `build/Interface-STYLE.FORMAT`. +E.g. + +- `make build/Interface-MediumItalic.eot` +- `make build/Interface-Bold.woff2` +- `make build/Interface-Regular.ttf` +- `...` + +All resulting font files are written to the `build` directory with `Interface-` 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 + +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: + +- 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. + + +### Preview & debug + +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. +- Provides samples of words ordered by commonality in latin scripts with a + preference for English (accessible via common-pair samples.) +- Can show the complete repertoire of the fonts, with correct glyph order and + even RoboFont color labels ("marks"). +- Controls for basic font properties like family, weight, italic, size, + line-height, letter-spacing, etc. +- Controls for a lot of font features like ligature sets, contextual alternates, + alternate numerics, etc. +- Controls for web-browser text features like `capitalize`, `uppercase`, + `lowercase`, etc. +- Ability to compare Interface 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: + +``` +$ docs/serve.sh & +``` + +You can now visit `http://localhost:2015/lab/`. +After you rebuild some font files, reload the web page to refresh fonts. + + +## FAQ + +> Do I need RoboFont? + +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.) + + +> `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. + -- cgit v1.2.3