mirror of
https://github.com/keymanapp/keyman.git
synced 2026-08-07 01:15:33 +00:00
77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
# 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
|