|
| 1 | +# displaymap.schema.json |
| 2 | + |
| 3 | +This mapping file provides data for remapping the touch layout and visual |
| 4 | +keyboard key caps. The primary purpose of this file is to provide a pathway for |
| 5 | +consistent display of diacritics and other unattached marks which may be |
| 6 | +displayed on the keyboard by use of a special font with formatted glyphs in the |
| 7 | +Private Use Area, which will have consistent display across all platforms and |
| 8 | +not rely on platform-specific or font-specific rendering behaviors. |
| 9 | + |
| 10 | +This file can be generated by `kmc analyze osk-char-use` command, or hand |
| 11 | +crafted. The compiler uses only the `str` and `pua` values in the file, although |
| 12 | +there may be additional data in the file provided for reference purposes. The |
| 13 | +file should have the following structure, in this example, mapping the Unicode |
| 14 | +values `U+17BB U+17C7` (ុះ) to the Private Use Area code `U+F19F`: |
| 15 | + |
| 16 | +```json |
| 17 | +{ |
| 18 | + "map": [ |
| 19 | + { |
| 20 | + "pua": "F19F", |
| 21 | + "str": "ុះ", |
| 22 | + "unicode": "17BB 17C7", |
| 23 | + "usages": [ |
| 24 | + "khmer_angkor.kvks", |
| 25 | + "khmer_angkor.keyman-touch-layout" |
| 26 | + ] |
| 27 | + }, |
| 28 | + ... |
| 29 | + ] |
| 30 | +} |
| 31 | +``` |
| 32 | + |
| 33 | +The file can be passed without modification to the [ttkbdfont.py script][2] |
| 34 | +(unsupported) to generate a Kbd font. The font may need some manual editing as |
| 35 | +insertion of dotted circle (`U+25CC`) as a base may not always be possible |
| 36 | +automatically, and combined marks may not render as a cluster in some scenarios. |
| 37 | +The open source tool [FontForge][3] is suitable for making these kinds of minor |
| 38 | +adjustments to the generated font. |
| 39 | + |
| 40 | +## Standard conventions for use of displayMaps |
| 41 | + |
| 42 | +In the Keyman keyboards repository, the PUA range used should start at `U+F100`. |
| 43 | + |
| 44 | +`&displayMap` JSON files should be named `Kbd<script>.json` where `<script>` is |
| 45 | +a [4 letter script subtag][4], for example `KbdKhmr.json`, and the corresponding |
| 46 | +font is named `KbdKhmr.ttf` (with face name `KbdKhmr`). These fonts are intended |
| 47 | +only for use in visual keyboards and touch layouts and generally will not be |
| 48 | +suitable for any other use. An optional suffix to a font may be included, if |
| 49 | +appropriate, for example, `KbdArab-Nastaliq.ttf` (face name `KbdArab-Nastaliq`). |
| 50 | + |
| 51 | +## Fields in the `map` objects |
| 52 | + |
| 53 | +* `pua`: must be a single hex value, by convention in the PUA range starting at |
| 54 | + `U+F100`. Do not include the `U+` prefix. |
| 55 | +* `str`: contains the codepoints that will be mapped to the PUA code; |
| 56 | + if `U+25CC` (◌, dotted circle) is specified in the key cap, it will be |
| 57 | + stripped before matching in the `&displayMap`, so `U+25CC` should not be |
| 58 | + included in `str`. |
| 59 | +* `unicode`: must be the unicode codepoints contained in the `str` field, as |
| 60 | + hexadecimal values, without initial `U+` prefix. Used only for reference when |
| 61 | + reading the file. |
| 62 | +* `usages`: data provided by `kmc analyze osk-char use` on which files this |
| 63 | + specific string is found in. This may be an array of strings, or optionally |
| 64 | + may be an array of objects with `filename` and `count` fields. |
| 65 | + |
| 66 | +See [`&displaymap` system store][1] online documentation for more information on |
| 67 | +how this format is used. |
| 68 | + |
| 69 | +## 2023-06-17 1.0 |
| 70 | + |
| 71 | +* Initial version 1.0, describes osk usage data file format generated by kmc |
| 72 | + analyze osk-char-use. Schema is kept reasonably loose for future expansion. |
| 73 | + |
| 74 | + [1]: https://help.keyman.com/developer/language/reference/displaymap |
| 75 | + [2]: https://github.com/silnrsi/palaso-python/blob/master/scripts/font/ttkbdfont.py |
| 76 | + [3]: https://fontforge.org |
| 77 | + [4]: https://help.keyman.com/developer/current-version/reference/bcp-47#toc-the-script-subtag |
0 commit comments