spiegel-keyman/common/schemas/displaymap

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:

{
  "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 (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 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, 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 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.