# displaymap.schema.json

This mapping file provides data for remapping the touch layout and visual
keyboard key caps. The primary purpose of this file is to provide a pathway for
consistent display of diacritics and other unattached marks which may be
displayed on the keyboard by use of a special font with formatted glyphs in the
Private Use Area, which will have consistent display across all platforms and
not rely on platform-specific or font-specific rendering behaviors.

This file can be generated by `kmc analyze osk-char-use` command, or hand
crafted. The compiler uses only the `str` and `pua` values in the file, although
there may be additional data in the file provided for reference purposes. The
file should have the following structure, in this example, mapping the Unicode
values `U+17BB U+17C7` (ុះ) to the Private Use Area code `U+F19F`:

```json
{
  "map": [
    {
      "pua": "F19F",
      "str": "ុះ",
      "unicode": "17BB 17C7",
      "usages": [
        "khmer_angkor.kvks",
        "khmer_angkor.keyman-touch-layout"
      ]
    },
    ...
  ]
}
```

The file can be passed without modification to the [ttkbdfont.py script][2]
(unsupported) to generate a Kbd font. The font may need some manual editing as
insertion of dotted circle (`U+25CC`) as a base may not always be possible
automatically, and combined marks may not render as a cluster in some scenarios.
The open source tool [FontForge][3] is suitable for making these kinds of minor
adjustments to the generated font.

## Standard conventions for use of displayMaps

In the Keyman keyboards repository, the PUA range used should start at `U+F100`.

`&displayMap` JSON files should be named `Kbd<script>.json` where `<script>` is
a [4 letter script subtag][4], for example `KbdKhmr.json`, and the corresponding
font is named `KbdKhmr.ttf` (with face name `KbdKhmr`). These fonts are intended
only for use in visual keyboards and touch layouts and generally will not be
suitable for any other use. An optional suffix to a font may be included, if
appropriate, for example, `KbdArab-Nastaliq.ttf` (face name `KbdArab-Nastaliq`).

## Fields in the `map` objects

* `pua`: must be a single hex value, by convention in the PUA range starting at
  `U+F100`. Do not include the `U+` prefix.
* `str`: contains the codepoints that will be mapped to the PUA code;
  if `U+25CC` (◌, dotted circle) is specified in the key cap, it will be
  stripped before matching in the `&displayMap`, so `U+25CC` should not be
  included in `str`.
* `unicode`: must be the unicode codepoints contained in the `str` field, as
  hexadecimal values, without initial `U+` prefix. Used only for reference when
  reading the file.
* `usages`: data provided by `kmc analyze osk-char use` on which files this
  specific string is found in. This may be an array of strings, or optionally
  may be an array of objects with `filename` and `count` fields.

See [`&displaymap` system store][1] online documentation for more information on
how this format is used.

## 2023-06-17 1.0

* Initial version 1.0, describes osk usage data file format generated by kmc
  analyze osk-char-use. Schema is kept reasonably loose for future expansion.

  [1]: https://help.keyman.com/developer/language/reference/displaymap
  [2]: https://github.com/silnrsi/palaso-python/blob/master/scripts/font/ttkbdfont.py
  [3]: https://fontforge.org
  [4]: https://help.keyman.com/developer/current-version/reference/bcp-47#toc-the-script-subtag