east-asian-spacing 1.0.0

East Asian Contextual Spacing Build Tools

East Asian Contextual Spacing

This directory contains tools for the OpenType Contextual Half-width Spacing feature ("chws" and "vchw" feature tags) for Japanese/Chinese/Korean typography. This feature enables the typography described in JLREQ 3.1.2 Positioning of Punctuation Marks (Commas, Periods and Brackets) 句読点や，括弧類などの基本的な配置方法 and CLREQ 3.1.6.1 Punctuation Adjustment Space 标点符号的调整空间 標點符號的調整空間. Following is a figure from JLREQ:

You can find sample text here. The sample page uses fonts built with this tool. Also, early discussion at Adobe CJK Type blog article may help to understand the feature.

Install

This tool requires Python 3.8 or later.

If you may need to diagnose fonts or the code, installing using poetry is recommended:

git clone https://github.com/kojiishi/east_asian_spacing
cd east_asian_spacing
poetry install
poetry shell

This method:

• Installs the exact versions of dependencies.
• Installs in the editable mode (i.e., pip "-e" option or setuptools "development mode").
• Installs testing tools too. You can run unit tests to verify your installation if needed.

If all what you need is the command line tool, pipx can install it globally while still isolating it in a virtual environment:

pipx install git+https://github.com/kojiishi/east_asian_spacing

Otherwise, you can install with pip. When installing with pip, it is still recommended to install into a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install git+https://github.com/kojiishi/east_asian_spacing

Adding the feature to your fonts

Usage

The following example adds the feature to input-font-file and saves it to the build directory.

east-asian-spacing -o build input-font-file

The --help option shows the full list of options.

Languages

Because the glyph for a code point may vary by languages, different tables are desired for different languages.

In many cases, when the font supports multiple East Asian languages, this tool can detect the languages automatically. But it shows an error when it failed to detect. You need to specify the OpenType language system tag of the font in that case.

The following example specifies that the font is a Japanese font.

east-asian-spacing --language=JAN input-font-file

TrueType Collection (TTC)

When the input-font-file is a TrueType Collection (TTC), this tool adds the feature to all fonts in the TTC by default.

If you want to add the feature to only some of fonts in the TTC, you can specify a comma-separated list of font indices. The following example adds the feature to the font index 0 and 1, but not to other fonts in the TTC.

east-asian-spacing --index=0,1 input-font-file.ttc

The language option applies to all fonts in the TTC by default. When you want to specify different languages to each font in the TTC, it accepts a comma-separated list. The following example specifies Korean for the font index 1, Simplified Chinese for the font index 2, and automatic for all other fonts.

east-asian-spacing --language=,KOR,ZHS input-font-file.ttc

You can combine these two options. The following example applies JAN to the index 2, and ZHS to the index 3. Other fonts in the TTC are not changed.

east-asian-spacing --index=2,3 --language=JAN,ZHS input-font-file.ttc

Noto CJK

For Noto CJK fonts, this tool has a built-in support to determine the font indices and the languages automatically.

When the first argument is noto, it a) computes the appropriate language for each font, and b) skips Mono fonts, both determined by the font name.

east-asian-spacing noto NotoSansCJK.ttc

You can also run it for a directory to find all font files recursively.

east-asian-spacing noto ~/googlefonts/noto-cjk

Scripts

Some small shell scripts are available in the scripts directory.

build*.sh scripts are useful to build fonts, compute diff from source fonts, and compare the diff files with references. Followings are example usages.

./scripts/build.sh input-font-file.otf -v
./scripts/build-noto-cjk.sh ~/fonts/noto-cjk -v

Character-Pairs

Some fonts may not have expected spacings for some characters, and you may want to adjust which character-pairs should adjust spacings.

Currently, this is possible only from a Python program. Please see tests/test_config.py for an example.

HarfBuzz

This package uses the HarfBuzz shaping engine using a Cython bindings uharfbuzz.

If you install or build HarfBuzz, you can use the hb-shape command line tool by settting the SHAPER environment variable.

export SHAPER=hb-shape

To install hb-shape for Linux:

sudo apt get libharfbuzz-bin

To install hb-shape for Mac with homebrew:

brew install harfbuzz

Instructions for other platforms may be available at command-not-found.com.

Testing

Test HTML

A test HTML is available to check the behavior of fonts on browsers.

It can test fonts you built locally. Download it to your local drive and add your fonts to the "fonts" list at the beginning of the <script> block.

Dump

The dump sub-command can create various types of text dump files.

The most simple usage is to show a list of tables. This is similar to the "-l" option of TTX, except for TrueType Collections (TTC), this tool can show tables of all fonts in the TTC, along with which tables are shared with which fonts.

east-asian-spacing dump build/NotoSansCJK-Regular.ttc

The "-o" option creates table list files in the specified directory:

east-asian-spacing dump -o build/dump build/*.ttc

The "--ttx" option creates TTX text dumps of all tables in addition to the table list files. This is similar to the "-s" option of TTX, except that it can dump all tables in TrueType Collections (TTC).

east-asian-spacing dump -o build/dump --ttx build/*.ttc

Diff

The dump sub-command can also create dump files of two font files and compare them. This helps visualizing differences in two fonts, specifically, the font files you created from the original font files.

east-asian-spacing dump -o build/diff --diff source_fonts_dir build/NotoSansCJK.ttc

The example above creates following 3 sets of files:

1. The table list and TTX text dump files for build/NotoSansCJK.ttc in the build/diff/dump directory.
2. The table list and TTX text dump files for source_fonts_dir/NotoSansCJK.ttc in the build/diff/src directory.
3. Diff files of the two sets of dump files in the build/diff directory.

The "--diff" option is more efficient than doing all these, especially for large fonts, because it skips creating TTX of tables when they are binary-equal.

To create diff files for all fonts you bulit, you can pipe the output as below:

east-asian-spacing -p *.otf | east-asian-spacing dump -o build/diff -

The "-p" option prints the input and output font paths to stdout in the tab-separated-values format. The dump sub-command with the "-" argument reads this list from stdin, and creates their text dump and diff files in the build/diff directory. The "--diff" option is not necessary in this case, because the source font paths are provided from the pipe.

References

Once you reviewed the diff files created above, or tested fonts you build, you can copy the diff files into the references directory. Then when you want to build them again, such as when the fonts are updated or when the build environment is changed, you can compare the diff files with the reference files to know how new fonts are different from previous builds.

With the "-r" option, the dump sub-command creates diff files between two font files, and compare the diff files with once-reviewed diff files in the references directory.

The typical usage of this option is as below:

east-asian-spacing -p -g=build/glyphs *.otf |
    east-asian-spacing dump -o=build/diff -r=references -

Please see the Diff section for the "-p" option and piping.

The build*.sh scripts include this option.

Shape Test

The shape testing shapes test strings and checks whether the contextual spacing is applied or not.

The --test option sets the level of the shape testing.

east-asian-spacing --test 2 -v -o build input-font-file

The level 0 disables the shape testing. The level 1 runs a smoke test using a small set of samples. The level 2 runs the shape testing using a large set of test strings.

The default value is 1.

Unit Tests

This repositry contains unit tests using pytest. The unit tests include basic functionalities including shape tests, adding the feature to a test font, and comparing it with references.

If you used poetry to install, tools for unit testing are already installed. Before you run them first time, you need to download fonts for testing:

./download-fonts.sh

You can then run the tests by:

pytest

or run them with multiple versions of Python using tox:

tox