User guide (#815)

README.md

@@ -0,0 +1,111 @@
+![GitHub Actions Build Status][] ![Python Versions][] [![PyPI
+Version][]][1]
+
+# fontmake
+
+`fontmake` compiles fonts from various sources (`.glyphs`, `.ufo`, `designspace`) into binaries (`.otf`, `.ttf`). You can use it to create static instances and variable fonts.
+
+## Installation
+
+Fontmake requires Python 3.7 or later.
+
+Releases are available on [PyPI][] and can be installed with [pip][].
+
+``` bash
+pip3 install fontmake
+```
+
+Use the `-U`, `--upgrade` option to update fontmake and its dependencies
+to the newest available release:
+
+``` bash
+pip3 install -U fontmake
+```
+
+## Basic Usage
+
+After installation, you will be able to use the `fontmake` executable.
+
+For example, to compile a variable font from a Glyphs source file, use:
+
+``` bash
+fontmake -g MyFont.glyphs -o variable
+```
+
+The most important command line arguments to the `fontmake` executable are the `-g`/`-u`/`-m` flags, one of which is required and selects the source file format, and the optional `-o` flag, which chooses the output file format.
+
+### Source file format options
+
+* `-g filename.glyphs`: Converts a Glyphs source file to binary.
+* `-u filename.ufo ...`: Converts one or more UFO files to binary.
+* `-m filename.designspace`: Converts a Designspace file to binary. (The `-m` is for `mutatormath`, an old Python library for handling designspaces.)
+
+### Output file format options
+
+You may provide one or more output file formats after the `-o` option. For example, `-o otf ttf` creates OTF and TTF binary font files for each master in your input file.
+
+The following output file formats are available:
+
+* `otf`: Per-master OTF (CFF-outline) binaries. Placed in the `master_otf/` directory.
+* `ttf`: Per-master TTF (TrueType-outline) binaries. Placed in the `master_ttf/` directory.
+* `otf-cff2`: Per-master OTF binaries with CFF2 outlines. Placed in the `master_otf/` directory.
+* `variable`: A TrueType variable font. Placed in the `variable_ttf/` directory.
+* `variable-cff2`: A variable font with CFF2 outlines. Placed in the `variable_otf/` directory.
+
+The following output file formats are also available, but are generally used internally by fontmake as an intermediate step to one of the above outputs:
+
+* `otf-interpolatable`: OTF binaries suitable for merging into a variable font. Placed in the `master_otf_interpolatable/` directory. (These differ from `otf` in that the outlines are unoptimized.)
+* `ttf-interpolatable`: TTF binaries suitable for merging into a variable font. Placed in the `master_ttf_interpolatable/` directory. (The outlines are converted to quadratic curves in an interpolation-compatible way.)
+* `ufo`: Glyphs sources can be converted to UFO. Placed in the `master_ufo/` directory.
+
+If no format option is specified, the default is `-o otf ttf`.
+
+### Other important command line options
+
+* `-i` (Interpolate instances): Having per-master binaries is not always what you expect; if you have defined instances ("exports") in your Glyphs file, they will *not* be generated by default. To generate them, pass the `-i` flag, which interpolates static instances, and places them in the `instance_ttf/` or `instance_otf/` directory as appropriate.
+
+* `--output-dir <some_directory>`: Places all output in the given directory, instead of the per-format directories mentioned above.
+
+* `--output-path <filename>`: This is only valid if the output is a single binary file, and writes the output to the given filename.
+
+* `-f` (Flatten components): Ensures that any glyphs which contain components which *themselves* contain components are decomposed to a single level. This is recommended as certain rendering environments do not correctly handle nested components - see [this link](https://github.com/googlefonts/fontbakery/issues/2961) for more details.
+
+## Advanced Usage
+
+See [`USAGE.md`](USAGE.md).
+
+## Troubleshooting
+
+See [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md).
+
+## Developers
+
+Developers can get the latest version of `fontmake` by cloning the git repository:
+
+``` bash
+git clone https://github.com/googlefonts/fontmake
+cd fontmake
+pip install .
+```
+
+Developers who want to quickly test changes to the source code without re-installing can use the "--editable" option when installing from a local source checkout:
+
+``` bash
+pip install -e .
+```
+
+It is recommended to install fontmake inside a virtual environment to
+prevent conflicts between its dependencies and other modules installed
+globally.
+
+You could also use the [pipx][] tool to automate the
+installation/upgrade of python apps like fontmake in isolated
+environments.
+
+  [GitHub Actions Build Status]: https://github.com/googlefonts/fontmake/workflows/Test%20+%20Deploy/badge.svg
+  [Python Versions]: https://img.shields.io/badge/python-3.7-blue.svg
+  [PyPI Version]: https://img.shields.io/pypi/v/fontmake.svg
+  [1]: https://pypi.org/project/fontmake/
+  [PyPI]: https://pypi.org/project/fontmake
+  [pip]: https://pip.pypa.io
+  [pipx]: https://github.com/pipxproject/pipx

TROUBLESHOOTING.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+Sometimes things go wrong with `fontmake`, and you will need to track down what happened. In such circumstances, it is best to remember that `fontmake` itself does not actually do very much; its job is merely to orchestrate calls to different Python libraries which perform the compilation steps. So:
+
+* If something goes wrong with converting Glyphs files to `.designspace` and `.ufo` files, that's probably a problem with [`glyphsLib`](https://github.com/googlefonts/glyphsLib).
+* Run pre-processing filters:
+  * If something goes wrong converting cubics to quadratics, that's probably a problem with [`cu2qu`](https://github.com/googlefonts/cu2qu).
+  * If something goes wrong when decomposing mixed glyphs, that's probably a problem with [`ufo2ft.filters.decomposeComponents`](https://github.com/googlefonts/ufo2ft/blob/main/Lib/ufo2ft/filters/decomposeComponents.py).
+  * If something goes wrong when removing overlaps, that's probably a problem with [`booleanOperations`](https://github.com/typemytype/booleanOperations)
+* Anything else that goes wrong is probably a problem with [`ufo2ft`](https://github.com/googlefonts/ufo2ft), except...
+* ...if something goes wrong when compiling multiple files into a variable font, that's probably a problem with [`fontTools.varLib`](https://github.com/fonttools/fonttools/tree/main/Lib/fontTools/varLib).
+
+In other words, any problems you experience are generally *not* problems with `fontmake`. But it's important to know at which point things went wrong, and which Python library was handling your font at the time.
+
+To do this, you can follow the following troubleshooting steps: 
+
+## Troubleshooting steps
+
+* If your design source is a Glyphs file, the first step that `fontmake` will peform is to using `glyphsLib` to convert the file to masters + designspace and place them in the `master_ufo` directory. So a good start is to inspect the files in this directory and make sure that they look the way you would expect them to look. Pay particular attention to the axis ranges of multiple-axis fonts and the positions of masters and instances on these axes in the `.designspace` file. If this is correct, you can use `fontmake -m` on the `.designspace` file to skip the Glyphs conversion step on subsequent runs.
+
+*  Once you have UFO files (or if you started with them in the first place), it can be helpful to pass the `--validate-ufo` flag to `fontmake` to check that the UFO files are valid and correct.
+
+*  Next, if you receive an error from `fontmake`, you can get the full traceback by changing the log level by passing the `--verbose DEBUG` flag. Please pass this flag before filing any issues - although often the full traceback will point you to the source of the problem!
+
+* Finally, you can debug the operation of the feature writers by passing the `--debug-feature-file <file>` flag. This will cause `fontmake` to write out the generated feature file to a known filename, allowing you to inspect the file afterwards and check that it is as expected.
+
+If none of these steps are helpful, please file an issue in the `fontmake` repository, or in the repository of the Python library responsible for the problem.