diff --git a/docs/ldml/tr35-keyboards.md b/docs/ldml/tr35-keyboards.md index a5edc729df9..ae250228c98 100644 --- a/docs/ldml/tr35-keyboards.md +++ b/docs/ldml/tr35-keyboards.md @@ -82,22 +82,22 @@ The LDML specification is divided into the following parts: * [Disabling Normalization](#disabling-normalization) * [Element Hierarchy](#element-hierarchy) * [Element: keyboard3](#element-keyboard3) + * [Element: import](#element-import) * [Element: locales](#element-locales) * [Element: locale](#element-locale) * [Element: version](#element-version) * [Element: info](#element-info) * [Element: settings](#element-settings) + * [Element: displays](#element-displays) + * [Element: display](#element-display) + * [Non-spacing marks on keytops](#non-spacing-marks-on-keytops) + * [Element: displayOptions](#element-displayoptions) * [Element: keys](#element-keys) * [Element: key](#element-key) * [Implied Keys](#implied-keys) - * [Element: flicks](#element-flicks) + * [Element: flicks](#element-flicks) * [Element: flick](#element-flick) * [Element: flickSegment](#element-flicksegment) - * [Element: import](#element-import) - * [Element: displays](#element-displays) - * [Element: display](#element-display) - * [Non-spacing marks on keytops](#non-spacing-marks-on-keytops) - * [Element: displayOptions](#element-displayoptions) * [Element: forms](#element-forms) * [Element: form](#element-form) * [Implied Form Values](#implied-form-values) @@ -618,7 +618,7 @@ This is the top level element. All other elements defined below are under this e > > Parents: _none_ > -> Children: [displays](#element-displays), [import](#element-import), [info](#element-info), [keys](#element-keys), [flicks](#element-flicks), [layers](#element-layers), [locales](#element-locales), [settings](#element-settings), [_special_](tr35.md#special), [transforms](#element-transforms), [variables](#element-variables), [version](#element-version) +> Children: [displays](#element-displays), [flicks](#element-flicks), [forms](#element-forms), [import](#element-import), [info](#element-info), [keys](#element-keys), [layers](#element-layers), [locales](#element-locales), [settings](#element-settings), [_special_](tr35.md#special), [transforms](#element-transforms), [variables](#element-variables), [version](#element-version) > > Occurrence: required, single > @@ -654,12 +654,101 @@ For further details about the choice of locale ID, see [Keyboard IDs](#keyboard- … ``` +* * * + +### Element: import + +The `import` element is used to reference another xml file so that elements are imported from +another file. The use case is to be able to import a standard set of `transform`s and similar +from the CLDR repository, especially to be able to share common information relevant to a particular script. +The intent is for each single XML file to contain all that is needed for a keyboard layout, other than required standard import data from the CLDR repository. + +`` can be used as a child of a number of elements (see the _Parents_ section immediately below). Multiple `` elements may be used, however, `` elements must come before any other sibling elements. +If two identical elements are defined, the later element will take precedence, that is, override. +Imported elements may contain other `` statements. Implementations must prevent recursion, that is, each imported file may only be included once. + +**Note:** imported files do not have any indication of their normalization mode. For this reason, the keyboard author must verify that the imported file is of a compatible normalization mode. See the [`settings` element](#element-settings) for further details. + +**Syntax** +```xml + +``` +> +> +> Parents: [displays](#element-displays), [flicks](#element-flicks), [forms](#element-forms), [keyboard3](#element-keyboard3), [keys](#element-keys), [layers](#element-layers), [transformGroup](#element-transformgroup), [transforms](#element-transforms), [variables](#element-variables) +> Children: _none_ +> +> Occurrence: optional, multiple +> +> + +_Attribute:_ `base` + +> The base may be omitted (indicating a local import) or have the value `"cldr"`. + +**Note:** `base="cldr"` is required for all `` statements within keyboard files in the CLDR repository. + +_Attribute:_ `path` (required) + +> If `base` is `cldr`, then the `path` must start with a CLDR major version (such as `45`) representing the CLDR version to pull imports from. The imports are located in the `keyboard/import` subdirectory of the CLDR source repository. +> Implementations are not required to have all CLDR versions available to them. +> +> If `base` is omitted, then `path` is an absolute or relative file path. + + +**Further Examples** + +```xml + +… + + + + + +… + + + + + + + + + + + + + +``` + +**Note:** The root element, here `transforms`, is the same as +the _parent_ of the `` element. It is an error to import an XML file +whose root element is different than the parent element of the `` element. + +After loading, the above example will be the equivalent of the following. + +```xml + + + + + + + + + + + + + +``` * * * ### Element: locales -The optional `` element allows specifying additional or alternate locales. Denotes intentional support for an extra language, not just that a keyboard incidentally supports a language’s orthography. +The optional `` element allows specifying additional or alternate locales. **Syntax** @@ -682,7 +771,7 @@ The optional `` element allows specifying additional or alternate local ### Element: locale -The optional `` element allows specifying additional or alternate locales. Denotes intentional support for an extra language, not just that a keyboard incidentally supports a language’s orthography. +The `` element specifies an additional or alternate locale. Denotes intentional support for an extra language, not just that a keyboard incidentally supports a language’s orthography. **Syntax** @@ -862,6 +951,160 @@ _Attribute:_ `normalization="disabled"` * * * +### Element: displays + +The `displays` element consists of a list of [`display`](#element-display) subelements. + +**Syntax** + +```xml + + + + … + +``` + +> +> +> Parents: [keyboard3](#element-keyboard3) +> +> Children: [display](#element-display), [displayOptions](#element-displayoptions), [_special_](tr35.md#special) +> +> Occurrence: optional, single +> +> + +* * * + +### Element: display + +The `display` elements can be used to describe what is to be displayed on the keytops for various keys. For the most part, such explicit information is unnecessary since the `@to` element from the `keys/key` element will be used for keytop display. + +- Some characters, such as diacritics, do not display well on their own. +- Another useful scenario is where there are doubled diacritics, or multiple characters with spacing issues. +- Finally, the `display` element provides a way to specify the keytop for keys which do not otherwise produce output. Keys which switch layers using the `@layerId` attribute typically do not produce output. + +> Note: `displays` elements are designed to be shared across many different keyboard layout descriptions, and imported with `` where needed. + +#### Non-spacing marks on keytops + +For non-spacing marks, U+25CC `◌` is used as a base. It is an error to use a nonspacing character without a base in the `display` attribute. For example, `display="\u{0303}"` would produce an error. + +A key which outputs a combining tilde (U+0303) could be represented as either of the following: + +```xml + + +``` + +This way, a key which outputs a combining tilde (U+0303) will be represented as `◌̃` (a tilde on a dotted circle). + +Users of some scripts/languages may prefer a different base than U+25CC. See [``](#element-displayoptions). + + +**Syntax** + +```xml + +``` + +> +> +> Parents: [displays](#element-displays) +> +> Children: _none_ +> +> Occurrence: required, multiple +> +> + +One of the `output` or `id` attributes is required. + +**Note**: There is currently no way to indicate a custom display for a key without output (i.e. without a `to=` attribute), nor is there a way to indicate that such a key has a standardized identity (e.g. that a key should be identified as a “Shift”). These may be addressed in future versions of this standard. + + +_Attribute:_ `output` (optional) + +> Specifies the character or character sequence from the `keys/key` element that is to have a special display. +> This attribute may be escaped with `\u` notation, see [Escaping](#escaping). +> The `output` attribute may also contain the `\m{…}` syntax to reference a marker. See [Markers](#markers). Implementations may highlight a displayed marker, such as with a lighter text color, or a yellow highlight. +> String variables may be substituted. See [String variables](#element-string) + +_Attribute:_ `id` (optional) + +> Specifies the `key` id. This is useful for keys which do not produce any output (no `output=` value), such as a shift key. +> +> This attribute must match `[A-Za-z0-9][A-Za-z0-9-]*` + +_Attribute:_ `display` (required) + +> Required and specifies the character sequence that should be displayed on the keytop for any key that generates the `@output` sequence or has the `@id`. (It is an error if the value of the `display` attribute is the same as the value of the `output` attribute, this would be an extraneous entry.) + +> String variables may be substituted. See [String variables](#element-string) + +This attribute may be escaped with `\u` notation, see [Escaping](#escaping). + +**Example** + +```xml + + + + + + + + + + + + +``` + +To allow `displays` elements to be shared across keyboards, there is no requirement that `@output` in a `display` element matches any `@output`/`@id` in any `keys/key` element in the keyboard description. + +* * * + +### Element: displayOptions + +The `displayOptions` is an optional singleton element providing additional settings on this `displays`. It is structured so as to provide for future flexibility in such options. + +**Syntax** + +```xml + + + + +``` + +> +> +> Parents: [displays](#element-displays) +> +> Children: _none_ +> +> Occurrence: optional, single +> +> + +_Attribute:_ `baseCharacter` (optional) + +**Note:** At present, this is the only option settable in the `displayOptions`. + +> Some scripts/languages may prefer a different base than U+25CC. +> For Lao for example, `x` is often used as a base instead of `◌`. +> Setting `baseCharacter="x"` (for example) is a _hint_ to the implementation which +> requests U+25CC to be substituted with `x` on display. +> As a hint, the implementation may ignore this option. +> +> **Note** that not all base characters will be suitable as bases for combining marks. + +This attribute may be escaped with `\u` notation, see [Escaping](#escaping). + +* * * + ### Element: keys This element defines the properties of all possible keys via [`` elements](#element-key) used in all layouts. @@ -901,12 +1144,12 @@ This element defines a mapping between an abstract key and its output. This elem id="…keyId" flickId="…flickId" gap="true" + output="…string" longPressKeyIds="…list of keyIds" longPressDefaultKeyId="…keyId" multiTapKeyIds="…listId" stretch="true" layerId="…layerId" - output="…string" width="…number" /> ``` @@ -937,11 +1180,18 @@ _Attribute:_ `flickId="…flickId"` (optional) _Attribute:_ `gap="true"` (optional) > The `gap` attribute indicates that this key does not have any appearance, but causes a "gap" of the specified number of key widths. Can be used with `width` to set a width. +> Such elements may not be referred to by `display` elements, nor may they have any of the following attributes: `flickId`, `longPressKeyId`, `longPressDefaultKeyId`, `multiTapKeyIds`, `layerId`, or `output`. ```xml ``` +_Attribute:_ `output` + +> The `output` attribute value contains the sequence of characters that is emitted when pressing this particular key. Control characters, whitespace (other than the regular space character) and combining marks in this attribute are escaped using the `\u{…}` notation. More than one key may output the same output. +> +> The `output` attribute may also contain the `\m{…markerId}` syntax to insert a marker. See the definition of [markers](#markers). + _Attribute:_ `longPressKeyIds="…list of keyIds"` (optional) > A space-separated ordered list of `key` element ids, which keys which can be emitted by "long-pressing" this key. This feature is prominent in mobile devices. @@ -960,13 +1210,13 @@ _Attribute:_ `longPressKeyIds="…list of keyIds"` (optional) > > ```xml > -> +> > > > > > -> +> > > > ``` @@ -1016,12 +1266,6 @@ _Attribute:_ `layerId="shift"` (optional) > In the future, this attribute’s definition is expected to be updated to align with [UAX#31](https://www.unicode.org/reports/tr31/). -_Attribute:_ `output` - -> The `output` attribute value contains the sequence of characters that is emitted when pressing this particular key. Control characters, whitespace (other than the regular space character) and combining marks in this attribute are escaped using the `\u{…}` notation. More than one key may output the same output. -> -> The `output` attribute may also contain the `\m{…markerId}` syntax to insert a marker. See the definition of [markers](#markers). - _Attribute:_ `width="1.2"` (optional, default "1.0") > The `width` attribute indicates that this key has a different width than other keys, by the specified number of key widths. @@ -1073,7 +1317,7 @@ Thus, the implied keys behave as if the following import were present. * * * -#### Element: flicks +### Element: flicks The `flicks` element is a collection of `flick` elements. @@ -1097,7 +1341,7 @@ The `flick` element is used to generate results from a "flick" of the finger on ```xml - + @@ -1123,8 +1367,9 @@ _Attribute:_ `id` (required) > The `id` attribute identifies the flicks. It can be any NMTOKEN. > -> The `flick` elements do not share a namespace with the `key`s, so it would also be allowed -> to have `` +> The `id` attribute on `flick` elements are distinct from the `id` attribute on `key` elements. +> For example, it is permissible to have both `` and +> `` which are two unrelated elements. > > In the future, this attribute’s definition is expected to be updated to align with [UAX#31](https://www.unicode.org/reports/tr31/). @@ -1171,250 +1416,6 @@ where a flick to the Northeast then South produces `Å`. * * * -### Element: import - -The `import` element is used to reference another xml file so that elements are imported from -another file. The use case is to be able to import a standard set of `transform`s and similar -from the CLDR repository, especially to be able to share common information relevant to a particular script. -The intent is for each single XML file to contain all that is needed for a keyboard layout, other than required standard import data from the CLDR repository. - -`` can be used as a child of a number of elements (see the _Parents_ section immediately below). Multiple `` elements may be used, however, `` elements must come before any other sibling elements. -If two identical elements are defined, the later element will take precedence, that is, override. - -**Note:** imported files do not have any indication of their normalization mode. For this reason, the keyboard author must verify that the imported file is of a compatible normalization mode. See the [`settings` element](#element-settings) for further details. - -**Syntax** -```xml - -``` -> -> -> Parents: [displays](#element-displays), [keyboard3](#element-keyboard3), [keys](#element-keys), [flicks](#element-flicks), [layers](#element-layers), [transformGroup](#element-transformgroup), [transforms](#element-transforms), [variables](#element-variables) -> Children: _none_ -> -> Occurrence: optional, multiple -> -> - -_Attribute:_ `base` - -> The base may be omitted (indicating a local import) or have the value `"cldr"`. - -**Note:** `base="cldr"` is required for all `` statements within keyboard files in the CLDR repository. - -_Attribute:_ `path` (required) - -> If `base` is `cldr`, then the `path` must start with a CLDR major version (such as `45`) representing the CLDR version to pull imports from. The imports are located in the `keyboard/import` subdirectory of the CLDR source repository. -> Implementations are not required to have all CLDR versions available to them. -> -> If `base` is omitted, then `path` is an absolute or relative file path. - - -**Further Examples** - -```xml - -… - - - - - -… - - - - - - - - - - - - - - -``` - -**Note:** The DOCTYPE and root element, here `transforms`, is the same as -the _parent_ of the `` element. It is an error to import an XML file -whose root element is different than the parent element of the `` element. - -After loading, the above example will be the equivalent of the following. - -```xml - - - - - - - - - - - - - -``` - -* * * - -### Element: displays - -The `displays` element consists of a list of [`display`](#element-display) subelements. - -**Syntax** - -```xml - - - - … - -``` - -> -> -> Parents: [keyboard3](#element-keyboard3) -> -> Children: [display](#element-display), [displayOptions](#element-displayoptions), [_special_](tr35.md#special) -> -> Occurrence: optional, single -> -> - -* * * - -### Element: display - -The `display` elements can be used to describe what is to be displayed on the keytops for various keys. For the most part, such explicit information is unnecessary since the `@to` element from the `keys/key` element will be used for keytop display. - -- Some characters, such as diacritics, do not display well on their own. -- Another useful scenario is where there are doubled diacritics, or multiple characters with spacing issues. -- Finally, the `display` element provides a way to specify the keytop for keys which do not otherwise produce output. Keys which switch layers using the `@layerId` attribute typically do not produce output. - -> Note: `displays` elements are designed to be shared across many different keyboard layout descriptions, and imported with `` where needed. - -#### Non-spacing marks on keytops - -For non-spacing marks, U+25CC `◌` is used as a base. It is an error to use a nonspacing character without a base in the `display` attribute. For example, `display="\u{0303}"` would produce an error. - -A key which outputs a combining tilde (U+0303) could be represented as either of the following: - -```xml - - -``` - -This way, a key which outputs a combining tilde (U+0303) will be represented as `◌̃` (a tilde on a dotted circle). - -Users of some scripts/languages may prefer a different base than U+25CC. See [``](#element-displayoptions). - - -**Syntax** - -```xml - -``` - -> -> -> Parents: [displays](#element-displays) -> -> Children: _none_ -> -> Occurrence: required, multiple -> -> - -One of the `output` or `id` attributes is required. - -**Note**: There is currently no way to indicate a custom display for a key without output (i.e. without a `to=` attribute), nor is there a way to indicate that such a key has a standardized identity (e.g. that a key should be identified as a “Shift”). These may be addressed in future versions of this standard. - - -_Attribute:_ `output` (optional) - -> Specifies the character or character sequence from the `keys/key` element that is to have a special display. -> This attribute may be escaped with `\u` notation, see [Escaping](#escaping). -> The `output` attribute may also contain the `\m{…}` syntax to reference a marker. See [Markers](#markers). Implementations may highlight a displayed marker, such as with a lighter text color, or a yellow highlight. -> String variables may be substituted. See [String variables](#element-string) - -_Attribute:_ `id` (optional) - -> Specifies the `key` id. This is useful for keys which do not produce any output (no `output=` value), such as a shift key. -> -> This attribute must match `[A-Za-z0-9][A-Za-z0-9-]*` - -_Attribute:_ `display` (required) - -> Required and specifies the character sequence that should be displayed on the keytop for any key that generates the `@output` sequence or has the `@id`. (It is an error if the value of the `display` attribute is the same as the value of the `output` attribute, this would be an extraneous entry.) - -> String variables may be substituted. See [String variables](#element-string) - -This attribute may be escaped with `\u` notation, see [Escaping](#escaping). - -**Example** - -```xml - - - - - - - - - - - - -``` - -To allow `displays` elements to be shared across keyboards, there is no requirement that `@output` in a `display` element matches any `@output`/`@id` in any `keys/key` element in the keyboard description. - -* * * - -### Element: displayOptions - -The `displayOptions` is an optional singleton element providing additional settings on this `displays`. It is structured so as to provide for future flexibility in such options. - -**Syntax** - -```xml - - - - -``` - -> -> -> Parents: [displays](#element-displays) -> -> Children: _none_ -> -> Occurrence: optional, single -> -> - -_Attribute:_ `baseCharacter` (optional) - -**Note:** At present, this is the only option settable in the `displayOptions`. - -> Some scripts/languages may prefer a different base than U+25CC. -> For Lao for example, `x` is often used as a base instead of `◌`. -> Setting `baseCharacter="x"` (for example) is a _hint_ to the implementation which -> requests U+25CC to be substituted with `x` on display. -> As a hint, the implementation may ignore this option. -> -> **Note** that not all base characters will be suitable as bases for combining marks. - -This attribute may be escaped with `\u` notation, see [Escaping](#escaping). - -* * * - ### Element: forms This element contains a set of `form` elements which define the layout of a particular hardware form. @@ -1492,7 +1493,7 @@ There is an implied set of `
` elements corresponding to the default forms, ``` -Here is a summary of the implied form elements. Keyboards included in the CLDR Repository must only use these `form=` values and may not override the scanCodes. +Here is a summary of the implied form elements. Keyboards included in the CLDR Repository must only use these `formId=` values and may not override the scanCodes. > - `touch` - Touch (non-hardware) layout. > - `abnt2` - Brazilian 103 key ABNT2 layout (iso + extra key near right shift) @@ -1546,34 +1547,34 @@ hardware or touch layout. - At least one `layers` element is required. -_Attribute:_ `form` (required) +_Attribute:_ `formId` (required) > This attribute specifies the physical layout of a hardware keyboard, > or that the form is a `touch` layout. > -> When using an on-screen touch keyboard, if the keyboard does not specify a `` -> element, a `` element can be used as an fallback alternative. +> When using an on-screen touch keyboard, if the keyboard does not specify a `` +> element, a `` element can be used as an fallback alternative. > If there is no `hardware` form, the implementation may need > to choose a different keyboard file, or use some other fallback behavior when using a > hardware keyboard. > > Because a hardware keyboard facilitates non-trivial amounts of text input, > and many touch devices can also be connected to a hardware keyboard, it -> is recommended to always have at least one hardware (non-touch) form. +> is recommended to always have a hardware (non-touch) form. > -> Multiple `` elements are allowed with distinct `minDeviceWidth` values. -> At most one hardware (non-`touch`) `` element is allowed. If a different key arrangement is desired between, for example, `us` and `iso` formats, these should be separated into two different keyboards. +> Multiple `` elements are allowed with distinct `minDeviceWidth` values. +> At most one hardware (non-`formId="touch"`) `` element is allowed. If a different key arrangement is desired between, for example, `us` and `iso` formats, these should be separated into two different keyboards. > -> The typical keyboard author will be designing a keyboard based on their circumstances and the hardware that they are using. So, for example, if they are in South East Asia, they will almost certainly be using an 101 key hardware keyboard with US key caps. So we want them to be able to reference that (``) in their design, rather than having to work with an unfamiliar form. +> The typical keyboard author will be designing a keyboard based on their circumstances and the hardware that they are using. So, for example, if they are in South East Asia, they will almost certainly be using an 101 key hardware keyboard with US key caps. So we want them to be able to reference that (``) in their design, rather than having to work with an unfamiliar form. > -> A mismatch between the hardware layout in the keyboard file, and the actual hardware used by the user could result in some keys being inaccessible to the user if their hardware cannot generate the scancodes corresponding to the layout specified by the `form=` attribute. Such keys could be accessed only via an on-screen keyboard utility. Conversely, a user with hardware keys that are not present in the specified `form=` will result in some hardware keys which have no function when pressed. +> A mismatch between the hardware layout in the keyboard file, and the actual hardware used by the user could result in some keys being inaccessible to the user if their hardware cannot generate the scancodes corresponding to the layout specified by the `formId=` attribute. Such keys could be accessed only via an on-screen keyboard utility. Conversely, a user with hardware keys that are not present in the specified `formId=` will result in some hardware keys which have no function when pressed. > -> The value of the `form=` attribute may be `touch`, or correspond to a `form` element. See [`form`](#element-form). +> The value of the `formId=` attribute may be `touch`, or correspond to a `form` element. See [`form`](#element-form). > _Attribute:_ `minDeviceWidth` -> This attribute specifies the minimum required width, in millimeters (mm), of the touch surface. The `layers` entry with the greatest matching width will be selected. This attribute is intended for `form="touch"`, but is supported for hardware forms. +> This attribute specifies the minimum required width, in millimeters (mm), of the touch surface. The `layers` entry with the greatest matching width will be selected. This attribute is intended for `formId="touch"`, but is supported for hardware forms. > > This must be a whole number between 1 and 999, inclusive.