Revamp the documentation

Makefile

@@ -17,7 +17,7 @@
 
 SHELL=/bin/bash
 
-STYLES = $(VALID_STYLES)
+WEIGHTS = $(VALID_WEIGHTS)
 ifdef RELEASE
     override RELEASE = --release
 endif
@@ -35,13 +35,13 @@ else
     VERSION = 1.0
 endif
 unexport CHARSET
-CHECK_ARGS = $(if $(filter testing,$(CHARSET)),,--incomplete)
 SUFFIXES = $(VALID_SUFFIXES)
 TALL_TEXT = 𛰋𛱚𛰚‌𛰆𛱁𛰚𛰊
 HB_VERSION = 9.0.0
 
+CHECK_ARGS = $(if $(filter testing,$(CHARSET)),,--incomplete)
 FONT_FILE_NAME = $(subst $(eval ) ,,$(FONT_FAMILY_NAME))
-FONTS = $(foreach suffix,$(SUFFIXES),$(addprefix fonts/$(FONT_FILE_NAME)/unhinted/$(suffix)/$(FONT_FILE_NAME)-,$(addsuffix .$(suffix),$(STYLES))))
+FONTS = $(foreach suffix,$(SUFFIXES),$(addprefix fonts/$(FONT_FILE_NAME)/unhinted/$(suffix)/$(FONT_FILE_NAME)-,$(addsuffix .$(suffix),$(WEIGHTS))))
 INTERMEDIATE_PREFIX = tmp-
 INTERMEDIATE_FONTS = $(addprefix $(INTERMEDIATE_PREFIX),$(FONTS))
 SUBSET_PREFIX = subset-
@@ -52,9 +52,9 @@ ifneq ($(strip $(filter-out $(VALID_CHARSETS),$(CHARSET))),)
     $(error One or more invalid values: $(CHARSET); must be one of: $(VALID_CHARSETS))
 endif
 
-VALID_STYLES = Regular Bold
-ifneq ($(strip $(filter-out $(VALID_STYLES),$(STYLES))),)
-    $(error One or more invalid values: $(STYLES); must be subset of: $(VALID_STYLES))
+VALID_WEIGHTS = Regular Bold
+ifneq ($(strip $(filter-out $(VALID_WEIGHTS),$(WEIGHTS))),)
+    $(error One or more invalid values: $(WEIGHTS); must be subset of: $(VALID_WEIGHTS))
 endif
 
 VALID_SUFFIXES = otf ttf
@@ -120,7 +120,7 @@ endef
 %.ttf: %.otf
 	$(MAKE_TTF)
 
-$(addprefix $(INTERMEDIATE_PREFIX)fonts/$(FONT_FILE_NAME)/unhinted/ttf/$(FONT_FILE_NAME)-,$(addsuffix .ttf,$(STYLES))): $(INTERMEDIATE_PREFIX)fonts/$(FONT_FILE_NAME)/unhinted/ttf/%.ttf: $(INTERMEDIATE_PREFIX)fonts/$(FONT_FILE_NAME)/unhinted/otf/%.otf
+$(addprefix $(INTERMEDIATE_PREFIX)fonts/$(FONT_FILE_NAME)/unhinted/ttf/$(FONT_FILE_NAME)-,$(addsuffix .ttf,$(WEIGHTS))): $(INTERMEDIATE_PREFIX)fonts/$(FONT_FILE_NAME)/unhinted/ttf/%.ttf: $(INTERMEDIATE_PREFIX)fonts/$(FONT_FILE_NAME)/unhinted/otf/%.otf
 	$(MAKE_TTF)
 
 .PHONY: clean

README.md

@@ -1,5 +1,5 @@
 <!--
-Copyright 2020 Google LLC
+Copyright 2024 David Corbett
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -16,10 +16,47 @@ limitations under the License.
 
 # Duployan font
 
-A Unicode font for Duployan.
+An OpenType Unicode font for Duployan shorthand.
 
-This is a project to improve support of Unicode Duployan.
-Currently, that means creating Noto Sans Duployan.
-After that, it will involve researching all Duployan variants and creating a
-font supporting them all, ultimately leading to a Unicode proposal to expand
-its Duployan repertoire.
+Duployan is a shorthand used for French, English, Romanian, Chinook Jargon, and
+many other languages. This font is a technical proof of concept for all of
+Duployan’s features that is also suitable for practical use.
+
+## Installation
+
+The font has not been released yet. Until then, you can download a development
+build from the latest [workflow run](
+https://github.com/dscorbett/duployan-font/actions) or [the alpha version](
+https://github.com/dscorbett/duployan-test/tree/gh-pages/assets/fonts) used by
+the font demo.
+
+[The font demo](https://dscorbett.github.io/duployan-test/) is an online
+keyboard app that lets you type in Duployan. It is useful for testing the font
+without installing it locally and for use as a Duployan IME.
+
+The third-party article [“How to get the Chinuk Pipa font”](
+https://kaltashwawa.ca/2021/12/26/how-to-get-the-chinuk-pipa-font/) has further
+advice about installing the font that might be helpful.
+
+## Features
+
+The font has full support for Unicode Duployan:
+
+* All characters in the Duployan and Shorthand Format Controls blocks
+* Contextual forms and cursive joining
+* Shaded characters
+* Overlapping characters
+* Non-Duployan characters used with Duployan, such as digits and punctuation
+
+There are [multiple variants](docs/variants.md) of the font, including:
+
+* Duployan: the main font
+* Duployan Unjoined: the font with cursive joining removed
+* Noto Sans Duployan: the font with modifications for the Noto font project
+
+See [the user guide](docs/user-documentation.md) for more information.
+
+## Building
+
+See [the developer documentation](docs/developer-documentation.md) for how to
+build the fonts from source.

docs/README.md

@@ -1,5 +1,6 @@
 <!--
 Copyright 2022 Google LLC
+Copyright 2024 David Corbett
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -14,7 +15,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# Noto Sans Duployan
+# Table of contents
 
 * [User documentation](user-documentation.md)
+  * [Font variants](variants.md)
 * [Developer documentation](developer-documentation.md)
+  * [The width system](width-system.md)

docs/developer-documentation.md

@@ -26,29 +26,29 @@ The prerequisites are:
 * FontForge 20190801 with Python 3 extensions
 * unifdef
 
-To build Noto Sans Duployan, run:
+To build the basic default set of fonts, run:
 
 ```sh
 python3 -m venv venv
 . venv/bin/activate
 pip install --no-deps -r requirements.txt
-make NOTO=1
+make
 ```
 
 That will produce four fonts:
 
-* fonts/NotoSansDuployan/unhinted/ttf/NotoSansDuployan-Regular.ttf
-* fonts/NotoSansDuployan/unhinted/ttf/NotoSansDuployan-Bold.ttf
-* fonts/NotoSansDuployan/unhinted/otf/NotoSansDuployan-Regular.otf
-* fonts/NotoSansDuployan/unhinted/otf/NotoSansDuployan-Bold.otf
+* fonts/Duployan/unhinted/otf/Duployan-Bold.otf
+* fonts/Duployan/unhinted/otf/Duployan-Regular.otf
+* fonts/Duployan/unhinted/ttf/Duployan-Bold.ttf
+* fonts/Duployan/unhinted/ttf/Duployan-Regular.ttf
 
-To only build one weight, append `STYLES=Regular` or `STYLES=Bold`.
-
-To only build fonts with cubic Bézier curves, append `SUFFIXES=otf`.
+See .github/workflows/main.yml for how to get the prerequisites on Ubuntu. The
+steps should be analogous on other platforms. Getting FontForge to build
+correctly is a challenge.
 
 ## Testing
 
-The prerequisites are:
+The additional prerequisite for testing is:
 
 * HarfBuzz 8.1.0 or later
 
@@ -58,15 +58,75 @@ To test the fonts, run:
 python3 -m venv venv
 . venv/bin/activate
 pip install --no-deps -r dev-requirements.txt
-make NOTO=1 check
+make check
 ```
 
-`STYLES` and `SUFFIXES` are also respected here.
-
-To measure coverage and check that it is above the target percentage,
-add `COVERAGE=1` to both make commands for building and testing.
-
-## Understanding the code
-
-The [width system](width-system.md) has documentation.
-Some of the code has docstrings.
+Alternatively, push a commit and wait for GitHub Actions to run CI.
+
+## Advanced build options
+
+Makefile has many available targets. The main ones are:
+
+* `all`: Build the fonts. This is the default target.
+* A specific font path ending with `.otf` or `.ttf`: Build one font. (This might
+  build other fonts too; see below for a discussion of vertical metrics.)
+* `clean`: Remove the fonts and other build leftovers.
+* `check`: Run various tests.
+* `hb-shape` and `hb-view`: Build HarfBuzz’s command-line utilities.
+* `requirements.txt` and `dev-requirements.txt`: Update `*requirements.txt`
+  based on `*requirements.in`.
+* `sync-noto`: Prepare to sync the downstream Noto repository with changes in
+  this repository. (Some manual work is still required.)
+
+These targets are affected by various variables:
+
+* `CHARSET`: Which [character set variant](variants.md) to build: `standard` for
+  Duployan, `noto` for Noto Sans Duployan, or `testing` for Duployan Test.
+* `WEIGHTS`: A space-separated list of weights to build. The only valid weights
+  are `Regular` and `Bold`. The default is both.
+* `SUFFIXES`: A space-separated list of OpenType variants to build. The only
+  valid variants are `otf` and `ttf`. The default is both.
+* `NOTO`: If defined, build a Noto font.
+* `UNJOINED`: If defined, build an Unjoined font.
+* `FONT_FAMILY_NAME`: The name of the font.
+* `VERSION`: The base version number. It is automatically augmented with various
+  affixes.
+* `RELEASE`: If defined, this is a release build. This only affects the version
+  number.
+* `TALL_TEXT`: A string that helps determine the common vertical metrics across
+  all the fonts.
+* `COVERAGE`: Whether to measure code coverage when building the fonts and
+  whether to enforce a minimum coverage percentage when testing.
+* `HB_VERSION`: The version of HarfBuzz to build when building its command-line
+  utilities.
+
+All the fonts for a given character set variant should share the same vertical
+metrics. When building the fonts, preliminary versions of all of the fonts with
+that character set variant are built, and the final fonts’ vertical metrics are
+set to the most extreme values of all of them. If `TALL_TEXT` is defined, the
+vertical metrics are also modified to make sure the bounding box of `TALL_TEXT`
+falls within every font’s vertical metrics. By default, it is defined with a
+string that is suitable for Chinook Jargon and reasonable for other modes.
+
+## How it works
+
+Most of the build is done by a Python script, which has some documentation in
+docstrings and comments. At a high level, this is what is does:
+
+1. Using the specified character set, decide what code points will go in 'cmap'.
+  Each code point gets a schema. A schema is a build-time abstraction of a
+  glyph.
+1. Send the schemas through a sequence of phases. A phase is an abstraction of a
+  sequence of OTL lookups (usually GSUB). A GSUB phase can add or remove schemas
+  from the set of current schemas, corresponding to the set of glyphs that can
+  exist at that point in OTL.
+1. Using FontForge, draw the schemas by expanding their strokes, and convert
+  them to glyphs. Schemas that behave and look the same up to this point are
+  merged and get the same glyph.
+1. Send the schemas through another sequence of phases. These phases have access
+  to glyphs and can create lookups that depend on their exact bounding boxes and
+  anchor points. (Bounding boxes in particular are necessary for [the width
+  system](width-system.md).) Schemas created in these phases are not subject to
+  later merging.
+1. Add mark attachment GPOS rules.
+1. Compile the font with fontTools.