Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history 
* Move the "Testing" section up, before the "Advanced Topics".
* Fix typo.
* Minor editorial changes.
  • Loading branch information
@kojiishi
kojiishi committed Jan 7, 2022
1 parent 2891604 commit 4f5b757
Showing 1 changed file with 146 additions and 146 deletions.
292 changes: 146 additions & 146 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,145 +178,6 @@ async def main_async():
print("Skipped")
```

## Advanced Topics
[Advanced Topics]: #advanced-topics

### Algorithm
[Algorithm]: #algorithm

The algorithm is language agnostic and is applicable to any CJK fonts.

This package determines the glyph pairs to adjust spacings
by a set of Unicode code points
defined in the [`Config` class].

Then for each pair, it checks if the spacings are applicable
by examining glyph outlines and computing ink bounding boxes of glyphs.
For example, when glyphs are very thick,
glyphs may not have enough internal spacings,
and applying the spacings may cause glyphs to collide.
This package automatically detects such cases and
avoids applying spacings to such pairs.

This automatic behavior can be disabled
by specifying the [languages] below,
or by setting `Config.use_ink_bounds` to `False` in your Python program.

### Languages
[languages]: #languages

There are language-specific conventions
for where punctuation characters are placed in the glyph spaces.
For example,
U+3002 IDEOGRAPHIC FULL STOP
should be placed at the left-bottom corner of the glyph space in Japanese,
while it should be placed at the center in Traditional Chinese.

By default,
this package determines such differences from glyph outlines
as described in the [Algorithm] section above.
But you can specify the [OpenType language system tag]
to let this package follow the language convention
instead of using glyph outlines.
The following example
disables the automatic determination by glyph outlines,
and specifies that the font is a Japanese font.
```sh
east-asian-spacing --language=JAN input-font-file
```

For TrueType Collections (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.
```sh
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.
```sh
east-asian-spacing --index=2,3 --language=JAN,ZHS input-font-file.ttc
```

[OpenType language system tag]: https://docs.microsoft.com/en-us/typography/opentype/spec/languagetags

### Character-Pairs

You may want to adjust which character-pairs should adjust spacings,
in cases such as when
your fonts may not have expected spacings for some characters.
Currently, this is possible only from Python programs.

For a simple example, please see the `test_config` function
in [`tests/config_test.py`].

The [chws_tool] project is an actual example of customizing this package.

[`Config` class]: https://github.com/kojiishi/east_asian_spacing/blob/main/east_asian_spacing/config.py
[`tests/config_test.py`]: https://github.com/kojiishi/east_asian_spacing/blob/main/tests/config_test.py

### HarfBuzz

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

If you want to use a specific build of the [HarfBuzz],
this tool can invoke the external [hb-shape] command line tool instead
by settting the `SHAPER` environment variable.
```sh
export SHAPER=hb-shape
```

To install [hb-shape] for Linux:
```sh
sudo apt get libharfbuzz-bin
```
To install [hb-shape] for Mac with [homebrew]:
```sh
brew install harfbuzz
```
Instructions for other platforms may be available at
[command-not-found.com](https://command-not-found.com/hb-shape).

[HarfBuzz]: https://github.com/harfbuzz/harfbuzz
[hb-shape]: https://harfbuzz.github.io/utilities.html#utilities-command-line-hbshape
[homebrew]: https://brew.sh/
[uharfbuzz]: https://github.com/harfbuzz/uharfbuzz


### Clone and Install
[clone and install]: #clone-and-install

If you may need to diagnose fonts or the code,
cloning and installing using [poetry] is recommended:
```sh
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.

You can also install the cloned directory using [pip]:
```sh
git clone https://github.com/kojiishi/east_asian_spacing
cd east_asian_spacing
pip install .
```

## Testing
[testing]: #testing

Expand Down Expand Up @@ -398,12 +259,12 @@ especially for large fonts,
because it skips creating TTX of tables when they are binary-equal.

The `-o` option is optional. When it is omitted,
the sub-command ouputs the diff to `stdout`.
the sub-command outputs the diff to `stdout`.
```sh
east-asian-spacing dump --diff source_fonts_dir build/NotoSansCJK.ttc | less
```

To create diff files for all fonts you bulit,
To create diff files for all fonts you built,
you can pipe the output as below:
```sh
east-asian-spacing -p *.otf | east-asian-spacing dump -o build/diff -
Expand Down Expand Up @@ -453,14 +314,153 @@ 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.

## Advanced Topics
[Advanced Topics]: #advanced-topics

### Algorithm
[Algorithm]: #algorithm

The algorithm is language agnostic and is applicable to any CJK fonts.

This package determines the glyph pairs to adjust spacings
by a set of Unicode code points
defined in the [`Config` class].

Then for each pair, it checks if the spacings are applicable
by examining glyph outlines and computing ink bounding boxes of glyphs.
For example, when glyphs are very thick,
glyphs may not have enough internal spacings,
and applying the spacings may cause glyphs to collide.
This package automatically detects such cases and
avoids applying spacings to such pairs.

This automatic behavior can be disabled
by specifying the [languages] below,
or by setting `Config.use_ink_bounds` to `False` in your Python program.

### Languages
[languages]: #languages

There are language-specific conventions
for where punctuation characters are placed in the glyph spaces.
For example,
U+3002 IDEOGRAPHIC FULL STOP
should be placed at the left-bottom corner of the glyph space in Japanese,
while it should be placed at the center in Traditional Chinese.

By default,
this package determines such differences from glyph outlines
as described in the [Algorithm] section above.
But you can specify the [OpenType language system tag]
to let this package follow the language convention
instead of using glyph outlines.
The following example
disables the automatic determination by glyph outlines,
and specifies that the font is a Japanese font.
```sh
east-asian-spacing --language=JAN input-font-file
```

For TrueType Collections (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.
```sh
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.
```sh
east-asian-spacing --index=2,3 --language=JAN,ZHS input-font-file.ttc
```

[OpenType language system tag]: https://docs.microsoft.com/en-us/typography/opentype/spec/languagetags

### Character-Pairs

You may want to adjust which character-pairs should adjust spacings,
in cases such as when
your fonts may not have expected spacings for some characters.
Currently, this is possible only from Python programs.

For a simple example, please see the `test_config` function
in [`tests/config_test.py`].

The [chws_tool] project is an actual example of customizing this package.

[`Config` class]: https://github.com/kojiishi/east_asian_spacing/blob/main/east_asian_spacing/config.py
[`tests/config_test.py`]: https://github.com/kojiishi/east_asian_spacing/blob/main/tests/config_test.py

### HarfBuzz

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

If you want to use a specific build of the [HarfBuzz],
this tool can invoke the external [hb-shape] command line tool instead
by setting the `SHAPER` environment variable.
```sh
export SHAPER=hb-shape
```

To install [hb-shape] for Linux:
```sh
sudo apt get libharfbuzz-bin
```
To install [hb-shape] for Mac with [homebrew]:
```sh
brew install harfbuzz
```
Instructions for other platforms may be available at
[command-not-found.com](https://command-not-found.com/hb-shape).

[HarfBuzz]: https://github.com/harfbuzz/harfbuzz
[hb-shape]: https://harfbuzz.github.io/utilities.html#utilities-command-line-hbshape
[homebrew]: https://brew.sh/
[uharfbuzz]: https://github.com/harfbuzz/uharfbuzz


### Clone and Install
[clone and install]: #clone-and-install

If you may need to diagnose fonts or the code,
cloning and installing using [poetry] is recommended:
```sh
git clone https://github.com/kojiishi/east_asian_spacing
cd east_asian_spacing
poetry install
poetry shell
```
This method has following advantages:
* 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.
* Creates the virtual environment automatically.

You can also install the cloned directory using [pip] if you prefer:
```sh
git clone https://github.com/kojiishi/east_asian_spacing
cd east_asian_spacing
pip install .
```

### Unit Tests
[unit tests]: #unit-tests

This repositry contains unit tests using [pytest].
The unit tests include basic functionalities
This repository contains unit tests using [pytest].
The unit tests cover the basic functionalities
including [shape tests],
adding the feature to a test font,
and comparing it with [references].
Expand All @@ -486,9 +486,9 @@ tox
[tox]: https://tox.readthedocs.io/en/latest/index.html

### Scripts
[scripts]: (#scripts)
[scripts]: #scripts

Some small shell scripts are available in the `scripts` directory.
The `scripts` directory has some small shell scripts.

`build*.sh` scripts are useful to build fonts,
compute [diff] from source fonts,
Expand Down

0 comments on commit 4f5b757

Please sign in to comment.