diff --git a/docs/ldml/tr35-general.md b/docs/ldml/tr35-general.md index a0bc167cbee..27c2e80e1fb 100644 --- a/docs/ldml/tr35-general.md +++ b/docs/ldml/tr35-general.md @@ -99,6 +99,7 @@ The LDML specification is divided into the following parts: * [Conversion Rules](#Conversion_Rules) * [Intermixing Transform Rules and Conversion Rules](#Intermixing_Transform_Rules_and_Conversion_Rules) * [Inverse Summary](#Inverse_Summary) + * [Transform Syntax Characters](#transform-syntax-characters) * [List Patterns](#ListPatterns) * [Gender of Lists](#List_Gender) * [ContextTransform Elements](#Context_Transform_Elements) diff --git a/docs/ldml/tr35-keyboards.anchors.json b/docs/ldml/tr35-keyboards.anchors.json index 7b67b8db84f..1ecfd11f988 100644 --- a/docs/ldml/tr35-keyboards.anchors.json +++ b/docs/ldml/tr35-keyboards.anchors.json @@ -1,93 +1,83 @@ [ + "accessibility", + "additional-features", + "backspace-transforms", + "compatibility-notice", "Contents", "contents-of-part-7-keyboards", - "Data_Sources", - "data-sources", "definitions", - "Definitions", - "Element_backspace", - "Element_backspaces", - "Element_display", - "Element_displayMap", - "Element_final", - "Element_flicks", - "Element_generation", - "Element_hardwareMap", - "Element_hardwareMap_map", - "Element_Heirarchy_Layout_File", - "Element_Heirarchy_Platform_File", - "Element_import", - "Element_info", - "Element_Keyboard", - "Element_keyMap", - "Element_layer", - "Element_map", - "Element_name", - "Element_names", - "Element_platform", - "Element_reorder", - "Element_row", - "Element_settings", - "Element_switch", - "Element_transform", - "Element_transforms", - "Element_version", - "Element_vkey", - "Element_vkeys", - "element-backspace", - "element-backspaces", + "disallowed-regex-features", "element-display", - "element-displaymap", - "element-generation", - "element-hardwaremap", - "element-hierarchy---layout-file", - "element-hierarchy---platform-file", + "element-displayoptions", + "element-displays", + "element-flick", + "element-flicks", + "element-flicksegment", + "element-form", + "element-forms", + "element-hierarchy", "element-import", "element-info", - "element-keyboard", - "element-keymap", + "element-key", + "element-keyboard3", + "element-keys", "element-layer", - "element-map", - "element-map-1", - "element-name", - "element-names", - "element-platform", - "element-reorders-reorder", + "element-layers", + "element-locale", + "element-locales", + "element-reorder", "element-row", + "element-scancodes", + "element-set", "element-settings", - "element-switch", + "element-string", "element-transform", - "element-transform-final", + "element-transformgroup", "element-transforms", + "element-unicodeset", + "element-variables", "element-version", - "element-vkey", - "element-vkeys", - "elements-flicks-flick", "escaping", - "Escaping", - "File_and_Dir_Structure", + "example-post-reorder-transforms", + "example-transformgroup-with-reorder-elements", + "example-transformgroup-with-transform-elements", + "extensibility", "file-and-directory-structure", - "Goals_and_Nongoals", "goals-and-non-goals", + "implied-form-values", + "implied-keys", "important-note", - "Introduction", "invariants", - "Invariants", - "Key_Map_Data_Sources", - "Keyboard_IDs", "keyboard-ids", + "keyboard-test-data", "keyboards", + "layer-modifier-components", + "layer-modifier-matching", + "markers", + "modifier-left--and-right--keys", "parts", "Parts", - "Platform_Behaviors_in_Edge_Cases", "platform-behaviors-in-edge-cases", - "Possible_Modifier_Keys", - "Principles_for_Keyboard_Ids", "principles-for-keyboard-ids", + "regex-like-syntax", + "replacement-syntax", "status", "summary", - "table-key-map-data-sources", - "table-possible-modifier-keys", + "test-doctype", + "test-element-backspace", + "test-element-check", + "test-element-emit", + "test-element-info", + "test-element-keyboardtest", + "test-element-keystroke", + "test-element-repertoire", + "test-element-startcontext", + "test-element-test", + "test-element-tests", + "test-examples", "unicode-locale-data-markup-language-ldmlpart-7-keyboards", - "unicode-technical-standard-35" + "unicode-technical-standard-35-tech-preview", + "unicodeset-escaping", + "using-import-with-reorder-elements", + "uts18-escaping" ] \ No newline at end of file diff --git a/docs/ldml/tr35-keyboards.md b/docs/ldml/tr35-keyboards.md index 4630a36318a..bc9e6d8f868 100644 --- a/docs/ldml/tr35-keyboards.md +++ b/docs/ldml/tr35-keyboards.md @@ -18,7 +18,7 @@ For the full header, summary, and status, see [Part 1: Core](tr35.md). This document describes parts of an XML format (_vocabulary_) for the exchange of structured locale data. This format is used in the [Unicode Common Locale Data Repository](https://www.unicode.org/cldr/). -This is a partial document, describing keyboard mappings. For the other parts of the LDML see the [main LDML document](tr35.md) and the links above. +This is a partial document, describing keyboards. For the other parts of the LDML see the [main LDML document](tr35.md) and the links above. _Note:_ Some links may lead to in-development or older @@ -31,12 +31,8 @@ This document is a draft of a _technical preview_ of the Keyboard standard. This document has _not_ been approved for publication by the Unicode Consortium, and may be substantially altered before any publication. For the latest published version of UTS#35, see -In particular, Element and attribute names are expected to change pending further review. - The CLDR [Keyboard Workgroup](https://cldr.unicode.org/index/keyboard-workgroup) is currently -developing major changes to the CLDR keyboard specification. -For this draft, please see [CLDR-15034](https://unicode-org.atlassian.net/browse/CLDR-15034) for -status, the latest information, or to provide feedback. +developing this technical preview to the CLDR keyboard specification. ## Parts @@ -58,64 +54,65 @@ The LDML specification is divided into the following parts: * [_Status_](#status) * [Parts](#Parts) * [Contents of Part 7, Keyboards](#Contents) -* [Keyboards](#Introduction) -* [Goals and Non-goals](#Goals_and_Nongoals) - * [Compatibility Notice](#Compatibility_Notice) - * [Accessibility](#Accessibility) -* [Definitions](#Definitions) - * [Escaping](#Escaping) +* [Keyboards](#keyboards) +* [Goals and Non-goals](#goals-and-non-goals) + * [Compatibility Notice](#compatibility-notice) + * [Accessibility](#accessibility) +* [Definitions](#definitions) + * [Escaping](#escaping) * [UnicodeSet Escaping](#unicodeset-escaping) * [UTS18 Escaping](#uts18-escaping) -* [File and Directory Structure](#File_and_Dir_Structure) - * [Extensibility](#Extensibility) +* [File and Directory Structure](#file-and-directory-structure) + * [Extensibility](#extensibility) * [Element Hierarchy](#element-hierarchy) - * [Element: keyboard3](#Element_Keyboard) - * [Element: locales](#Element_locales) - * [Element: locale](#Element_locale) - * [Element: version](#Element_version) - * [Element: info](#Element_info) - * [Element: settings](#Element_settings) - * [Element: keys](#Element_keys) - * [Element: key](#Element_key) + * [Element: keyboard3](#element-keyboard3) + * [Element: locales](#element-locales) + * [Element: locale](#element-locale) + * [Element: version](#element-version) + * [Element: info](#element-info) + * [Element: settings](#element-settings) + * [Element: keys](#element-keys) + * [Element: key](#element-key) * [Implied Keys](#implied-keys) - * [Elements: flicks](#Element_flicks) - * [Elements: flick, flickSegment](#Element_flick) - * [Element: import](#Element_import) - * [Element: displays](#Element_displays) - * [Element: display](#Element_display) - * [Element: displayOptions](#Element_displayOptions) - * [Element: forms](#Element_forms) - * [Element: form](#Element_form) + * [Element: flicks](#element-flicks) + * [Element: flick](#element-flick) + * [Element: flickSegment](#element-flicksegment) + * [Element: import](#element-import) + * [Element: displays](#element-displays) + * [Element: display](#element-display) + * [Element: displayOptions](#element-displayoptions) + * [Element: forms](#element-forms) + * [Element: form](#element-form) * [Implied Form Values](#implied-form-values) - * [Element: scanCodes](#Element_scanCodes) - * [Element: layers](#Element_layers) - * [Element: layer](#Element_layer) + * [Element: scanCodes](#element-scancodes) + * [Element: layers](#element-layers) + * [Element: layer](#element-layer) * [Layer Modifier Components](#layer-modifier-components) * [Modifier Left- and Right- keys](#modifier-left--and-right--keys) * [Layer Modifier Matching](#layer-modifier-matching) - * [Element: row](#Element_row) - * [Element: variables](#Element_variables) + * [Element: row](#element-row) + * [Element: variables](#element-variables) * [Element: string](#element-string) * [Element: set](#element-set) * [Element: unicodeSet](#element-unicodeset) - * [Element: transforms](#Element_transforms) + * [Element: transforms](#element-transforms) * [Markers](#markers) - * [Element: transformGroup](#Element_transformGroup) + * [Element: transformGroup](#element-transformgroup) * [Example: `transformGroup` with `transform` elements](#example-transformgroup-with-transform-elements) * [Example: `transformGroup` with `reorder` elements](#example-transformgroup-with-reorder-elements) - * [Element: transform](#Element_transform) + * [Element: transform](#element-transform) * [Regex-like Syntax](#regex-like-syntax) * [Additional Features](#additional-features) * [Disallowed Regex Features](#disallowed-regex-features) * [Replacement syntax](#replacement-syntax) - * [Element: reorder](#Element_reorder) + * [Element: reorder](#element-reorder) * [Using `` with `` elements](#using-import-with-reorder-elements) * [Example Post-reorder transforms](#example-post-reorder-transforms) - * [transform type="backspace"](#Element_backspaces) -* [Invariants](#Invariants) -* [Keyboard IDs](#Keyboard_IDs) - * [Principles for Keyboard IDs](#Principles_for_Keyboard_IDs) -* [Platform Behaviors in Edge Cases](#Platform_Behaviors_in_Edge_Cases) + * [Backspace Transforms](#backspace-transforms) +* [Invariants](#invariants) +* [Keyboard IDs](#keyboard-ids) + * [Principles for Keyboard IDs](#principles-for-keyboard-ids) +* [Platform Behaviors in Edge Cases](#platform-behaviors-in-edge-cases) * [Keyboard Test Data](#keyboard-test-data) * [Test Doctype](#test-doctype) * [Test Element: keyboardTest](#test-element-keyboardtest) @@ -130,7 +127,7 @@ The LDML specification is divided into the following parts: * [Test Element: check](#test-element-check) * [Test Examples](#test-examples) -## Keyboards +## Keyboards The Unicode Standard and related technologies such as CLDR have dramatically improved the path to language support. However, keyboard support remains platform and vendor specific, causing inconsistencies in implementation as well as timeline. @@ -149,11 +146,11 @@ The data can also be used in analysis of the capabilities of different keyboards For complete examples, see the XML files in the CLDR source repository. -Attribute values should be evaluated considering the DTD and [DTD Annotations](#DTD_Annotations). +Attribute values should be evaluated considering the DTD and [DTD Annotations](tr35.md#dtd-annotations). * * * -## Goals and Non-goals +## Goals and Non-goals Some goals of this format are: @@ -175,7 +172,7 @@ Some non-goals (outside the scope of the format) currently are: 1. Adaptation for screen scaling resolution. Instead, keyboards should define layouts based on physical size. Platforms may interpret physical size definitions and adapt for different physical screen sizes with different resolutions. 2. Unification of platform-specific virtual key and scan code mapping tables. 3. Unification of pre-existing platform layouts themselves (e.g. existing fr-azerty on platform a, b, c). -4. Support for prior (pre 3.0) CLDR keyboard files. See [Compatibility Notice](#Compatibility_Notice). +4. Support for prior (pre 3.0) CLDR keyboard files. See [Compatibility Notice](#compatibility-notice). 5. Run-time efficiency. [LDML is explicitly an interchange format](./tr35.md#Introduction), and so it is expected that data will be transformed to a more compact format for use by a keystroke processing engine. ` DTD annotation, see [DTD Annotations](tr35.md#57-dtd-annotations) +Attribute values escaped in this manner are annotated with the `` DTD annotation, see [DTD Annotations](tr35.md#dtd-annotations) * * * -## File and Directory Structure +## File and Directory Structure * New collection of layouts that are prescriptive, and define the common core for a keyboard that can be consumed as data for implementation on different platforms will be included in the CLDR repository. This collection will be in a different location than the existing CLDR keyboard files under main/keyboards. We should remove the existing data files, but keep the old DTD in the same place for compatibility, and also so that conversion tools can use it to read older files. * New layouts will have version metadata to indicate their specification compliance versi​​on number. For this tech preview, the value used must be `techpreview`. @@ -305,7 +302,7 @@ Attribute values escaped in this manner are annotated with the ` @@ -437,7 +434,7 @@ See [Principles for Keyboard IDs](#Principles_for_Keyboard_IDs) for discussion a * * * -### Element: version +### Element: version Element used to keep track of the source data version. @@ -449,7 +446,7 @@ Element used to keep track of the source data version. > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > > Children: _none_ > @@ -477,7 +474,7 @@ _Attribute:_ `cldrVersion` (fixed by DTD) * * * -### Element: info +### Element: info Element containing informative properties about the layout, for displaying in user interfaces etc. @@ -493,7 +490,7 @@ Element containing informative properties about the layout, for displaying in us > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > > Children: _none_ > @@ -537,7 +534,7 @@ _Attribute:_ `indicator` * * * -### Element: settings +### Element: settings An element used to keep track of layout-specific settings by implementations. This element may or may not show up on a layout. These settings reflect the normal practice by the implementation. However, an implementation using the data may customize the behavior. @@ -549,7 +546,7 @@ An element used to keep track of layout-specific settings by implementations. Th > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > > Children: _none_ > @@ -580,9 +577,9 @@ _Attribute:_ `normalization="disabled"` * * * -### Element: keys +### Element: keys -This element defines the properties of all possible keys via [`` elements](#Element_key) used in all layouts. +This element defines the properties of all possible keys via [`` elements](#element-key) used in all layouts. It is a “bag of keys” without specifying any ordering or relation between the keys. There is only a single `` element in each layout. @@ -598,8 +595,8 @@ There is only a single `` element in each layout. > > -> Parents: [keyboard3](#Element_keyboard) -> Children: [key](#Element_key) +> Parents: [keyboard3](#element-keyboard3) +> Children: [key](#element-key) > Occurrence: optional, single > > @@ -608,9 +605,9 @@ There is only a single `` element in each layout. * * * -### Element: key +### Element: key -This element defines a mapping between an abstract key and its output. This element must have the `keys` element as its parent. The `key` element is referenced by the `keys=` attribute of the [`row` element](#Element_row). +This element defines a mapping between an abstract key and its output. This element must have the `keys` element as its parent. The `key` element is referenced by the `keys=` attribute of the [`row` element](#element-row). **Syntax** @@ -631,7 +628,7 @@ This element defines a mapping between an abstract key and its output. This elem > > -> Parents: [keys](#Element_keys) +> Parents: [keys](#element-keys) > > Children: _none_ > @@ -650,7 +647,7 @@ _Attribute:_ `id` _Attribute:_ `flickId="{flick id}"` (optional) -> The `flickId` attribute indicates that this key makes use of a [`flick`](#Element_flick) set with the specified id. +> The `flickId` attribute indicates that this key makes use of a [`flick`](#element-flick) set with the specified id. _Attribute:_ `gap="true"` (optional) @@ -668,7 +665,7 @@ _Attribute:_ `longPressKeyIds="{list of key ids}"` (optional) > > Implementations shall ignore any gestures (such as flick, multiTap, longPress) defined on keys in the `longPressKeyIds` list. > -> For example, if the default key is a key whose [display](#Element_displays) value is `{`, an implementation might render the key as follows: +> For example, if the default key is a key whose [display](#element-displays) value is `{`, an implementation might render the key as follows: > > ![keycap hint](images/keycapHint.png) > @@ -787,26 +784,26 @@ Thus, the implied keys behave as if the following import were present. ``` -**Note:** All implied keys may be overridden, as with all other imported data items. See the [`import`](#Element_import) element for more details. +**Note:** All implied keys may be overridden, as with all other imported data items. See the [`import`](#element-import) element for more details. * * * -#### Elements: flicks +#### Element: flicks The `flicks` element is a collection of `flick` elements. > > -> Parents: [keyboard3](#Element_keyboard3) +> Parents: [keyboard3](#element-keyboard3) > -> Children: [flick](#Element_flick), [import](#Element_import), [_special_](tr35.md#special) +> Children: [flick](#element-flick), [import](#element-import), [_special_](tr35.md#special) > > Occurrence: optional, single > * * * -#### Elements: flick, flickSegment +#### Element: flick The `flick` element is used to generate results from a "flick" of the finger on a mobile device. @@ -829,9 +826,9 @@ The `flick` element is used to generate results from a "flick" of the finger on > > -> Parents: [flicks](#Element_flicks) +> Parents: [flicks](#element-flicks) > -> Children: [flickSegment](#Element_flickSegment), [_special_](tr35.md#special) +> Children: [flickSegment](#element-flicksegment), [_special_](tr35.md#special) > > Occurrence: optional, multiple > @@ -846,16 +843,13 @@ _Attribute:_ `id` (required) > > In the future, this attribute’s definition is expected to be updated to align with [UAX#31](https://www.unicode.org/reports/tr31/). Please see [CLDR-17043](https://unicode-org.atlassian.net/browse/CLDR-17043) for more details. +* * * -**Syntax** - -```xml - -``` +#### Element: flickSegment > > -> Parents: [flick](#Element_flick) +> Parents: [flick](#element-flick) > > Children: _none_ > @@ -892,7 +886,7 @@ where a flick to the Northeast then South produces `Å`. * * * -### Element: import +### 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 @@ -910,7 +904,7 @@ If two identical elements are defined, the later element will take precedence, t ``` > > -> Parents: [displays](#Element_displays), [keyboard3](#Element_keyboard), [keys](#Element_keys), [flicks](#Element_flicks), [layers](#Element_layers), [names](#Element_names), [reorders](#Element_reorders), [transformGroup](#Element_transformGroup), [transforms](#Element_transforms), [variables](#Element_variables) +> 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 @@ -982,7 +976,7 @@ After loading, the above example will be the equivalent of the following. * * * -### Element: displays +### Element: displays The displays 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 can be used. But there are some characters, such as diacritics, that do not display well on their own and so explicit overrides for such characters can help. Another useful scenario is where there are doubled diacritics, or multiple characters with spacing issues. @@ -1002,7 +996,7 @@ For example, a key which outputs a combining tilde (U+0303) can be represented a This way, a key which outputs a combining tilde (U+0303) will be represented as `◌̃` (a tilde on a dotted circle). Some scripts/languages may prefer a different base than U+25CC. -See [``](#Element_displayOptions). +See [``](#element-displayoptions). **Syntax** @@ -1016,9 +1010,9 @@ See [``](#Element_displayOptions). > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > -> Children: [display](#Element_display), [displayOptions](#Element_displayOptions), [_special_](tr35.md#special) +> Children: [display](#element-display), [displayOptions](#element-displayoptions), [_special_](tr35.md#special) > > Occurrence: optional, single > @@ -1026,7 +1020,7 @@ See [``](#Element_displayOptions). * * * -### Element: display +### Element: display The `display` element describes how a character, that has come from a `keys/key` element, should be displayed on a keyboard layout where such display is possible. @@ -1038,7 +1032,7 @@ The `display` element describes how a character, that has come from a `keys/key` > > -> Parents: [displays](#Element_displays) +> Parents: [displays](#element-displays) > > Children: _none_ > @@ -1051,7 +1045,7 @@ One of the `output` or `id` attributes is required. _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). +> 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) @@ -1067,7 +1061,7 @@ _Attribute:_ `display` (required) > String variables may be substituted. See [String variables](#element-string) -This attribute may be escaped with `\u` notation, see [Escaping](#Escaping). +This attribute may be escaped with `\u` notation, see [Escaping](#escaping). **Example** @@ -1090,7 +1084,7 @@ To allow `displays` elements to be shared across keyboards, there is no requirem * * * -### Element: displayOptions +### 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. @@ -1105,7 +1099,7 @@ The `displayOptions` is an optional singleton element providing additional setti > > -> Parents: [displays](#Element_displays) +> Parents: [displays](#element-displays) > > Children: _none_ > @@ -1125,20 +1119,20 @@ _Attribute:_ `baseCharacter` (optional) > > **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). +This attribute may be escaped with `\u` notation, see [Escaping](#escaping). * * * -### Element: forms +### Element: forms This element represents a set of `form` elements which define the layout of a particular hardware form. > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > -> Children: [import](#Element_import), [form](#Element_form), [_special_](tr35.md#special) +> Children: [import](#element-import), [form](#element-form), [_special_](tr35.md#special) > > Occurrence: optional, single > @@ -1159,7 +1153,7 @@ This element represents a set of `form` elements which define the layout of a pa * * * -### Element: form +### Element: form This element represents a specific `form` element which defines the layout of a particular hardware form. @@ -1173,9 +1167,9 @@ See [Implied Form Values](#implied-form-values), below. > > -> Parents: [forms](#Element_forms) +> Parents: [forms](#element-forms) > -> Children: [scanCodes](#Element_scanCodes), [_special_](tr35.md#special) +> Children: [scanCodes](#element-scancodes), [_special_](tr35.md#special) > > Occurrence: optional, multiple > @@ -1217,13 +1211,13 @@ Here is a summary of the implied form elements. Keyboards included in the CLDR R * * * -### Element: scanCodes +### Element: scanCodes This element represents a keyboard row, and defines the scan codes for the non-frame keys in that row. > > -> Parents: [form](#Element_form) +> Parents: [form](#element-form) > > Children: none > @@ -1243,16 +1237,16 @@ This element represents a keyboard row, and defines the scan codes for the non-f * * * -### Element: layers +### Element: layers This element represents a set of `layer` elements with a specific physical form factor, whether hardware or touch layout. > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > -> Children: [import](#Element_import), [layer](#Element_layer), [_special_](tr35.md#special) +> Children: [import](#element-import), [layer](#element-layer), [_special_](tr35.md#special) > > Occurrence: required, multiple > @@ -1292,7 +1286,7 @@ _Attribute:_ `minDeviceWidth` > > This must be a whole number between 1 and 999, inclusive. -### Element: layer +### Element: layer A `layer` element describes the configuration of keys on a particular layer of a keyboard. It contains one or more `row` elements to describe which keys exist in each row. @@ -1306,9 +1300,9 @@ A `layer` element describes the configuration of keys on a particular layer of a > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > -> Children: [row](#Element_row), [_special_](tr35.md#special) +> Children: [row](#element-row), [_special_](tr35.md#special) > > Occurrence: optional, multiple > @@ -1316,7 +1310,7 @@ A `layer` element describes the configuration of keys on a particular layer of a _Attribute_ `id` (required for `touch`) -> The `id` attribute identifies the layer for touch layouts. This identifier specifies the layout as the target for layer switching, as specified by the `switch=` attribute on the [``](#Element_key) element. +> The `id` attribute identifies the layer for touch layouts. This identifier specifies the layout as the target for layer switching, as specified by the `switch=` attribute on the [``](#element-key) element. > Touch layouts must have one `layer` with `id="base"` to serve as the base layer. > > Must match `[A-Za-z0-9][A-Za-z0-9-]*` @@ -1399,7 +1393,7 @@ Keystrokes where there isn’t an explicitly matching layer, and where there is * * * -### Element: row +### Element: row A `row` element describes the keys that are present in the row of a keyboard. @@ -1411,7 +1405,7 @@ A `row` element describes the keys that are present in the row of a keyboard. > > -> Parents: [layer](#Element_layer) +> Parents: [layer](#element-layer) > > Children: _none_ > @@ -1421,9 +1415,9 @@ A `row` element describes the keys that are present in the row of a keyboard. _Attribute:_ `keys` (required) -> This is a string that lists the id of [`key` elements](#Element_key) for each of the keys in a row, whether those are explicitly listed in the file or are implied. See the `key` documentation for more detail. +> This is a string that lists the id of [`key` elements](#element-key) for each of the keys in a row, whether those are explicitly listed in the file or are implied. See the `key` documentation for more detail. > -> For non-`touch` forms, the number of keys in each row may not exceed the number of scan codes defined for that row, and the number of rows may not exceed the defined number of rows for that form. See [`scanCodes`](#Element_scanCodes); +> For non-`touch` forms, the number of keys in each row may not exceed the number of scan codes defined for that row, and the number of rows may not exceed the defined number of rows for that form. See [`scanCodes`](#element-scancodes); **Example** @@ -1435,13 +1429,13 @@ Here is an example of a `row` element: * * * -### Element: variables +### Element: variables > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > -> Children: [import](#Element_import), [_special_](tr35.md#special), [string](#element-string), [set](#element-set), [unicodeSet](#element-unicodeSet) +> Children: [import](#element-import), [_special_](tr35.md#special), [string](#element-string), [set](#element-set), [unicodeSet](#element-unicodeset) > > Occurrence: optional, single > @@ -1466,7 +1460,7 @@ Note that the `id=` attribute must be unique across all children of the `variabl > > -> Parents: [variables](#Element_variables) +> Parents: [variables](#element-variables) > > Children: _none_ > @@ -1485,7 +1479,7 @@ _Attribute:_ `id` (required) _Attribute:_ `value` (required) > Strings may contain whitespaces. However, for clarity, it is recommended to escape spacing marks, even in strings. -> This attribute may be escaped with `\u` notation, see [Escaping](#Escaping). +> This attribute may be escaped with `\u` notation, see [Escaping](#escaping). > Variables may refer to other string variables if they have been previously defined, using `${string}` syntax. > [Markers](#markers) may be included with the `\m{…}` notation. @@ -1523,7 +1517,7 @@ These may be then used in multiple contexts: > > -> Parents: [variables](#Element_variables) +> Parents: [variables](#element-variables) > > Children: _none_ > @@ -1543,7 +1537,7 @@ _Attribute:_ `value` (required) > The `value` attribute is always a set of strings separated by whitespace, even if there is only a single item in the set, such as `"A"`. > Leading and trailing whitespace is ignored. -> This attribute may be escaped with `\u` notation, see [Escaping](#Escaping). +> This attribute may be escaped with `\u` notation, see [Escaping](#escaping). > Sets may refer to other string variables if they have been previously defined, using `${string}` syntax, or to other previously-defined sets using `$[set]` syntax. > Set references must be separated by whitespace: `$[set1]$[set2]` is an error; instead use `$[set1] $[set2]`. > [Markers](#markers) may be included with the `\m{…}` notation. @@ -1581,7 +1575,7 @@ See [transform](#element-transform) for further details and syntax. > > -> Parents: [variables](#Element_variables) +> Parents: [variables](#element-variables) > > Children: _none_ > @@ -1627,7 +1621,7 @@ The `unicodeSet` element may not be referenced by [`key`](#element-key) and [`di * * * -### Element: transforms +### Element: transforms This element defines a group of one or more `transform` elements associated with this keyboard layout. This is used to support features such as dead-keys, character reordering, backspace behavior, etc. using a straightforward structure that works for all the keyboards tested, and that results in readable source data. @@ -1643,9 +1637,9 @@ There can be multiple `` elements, but only one for each `type`. > > -> Parents: [keyboard3](#Element_keyboard) +> Parents: [keyboard3](#element-keyboard3) > -> Children: [import](#Element_import), [_special_](tr35.md#special), [transformGroup](#Element_transformGroup) +> Children: [import](#element-import), [_special_](tr35.md#special), [transformGroup](#element-transformgroup) > > Occurrence: optional, multiple > @@ -1771,13 +1765,13 @@ Such implementations must take care to remove all such markers (see prior sectio * * * -### Element: transformGroup +### Element: transformGroup > > -> Parents: [transforms](#Element_transforms) +> Parents: [transforms](#element-transforms) > -> Children: [import](#Element_import), [reorder](#Element_reorder), [_special_](tr35.md#special), [transform](#Element_transform) +> Children: [import](#element-import), [reorder](#element-reorder), [_special_](tr35.md#special), [transform](#element-transform) > > Occurrence: optional, multiple > @@ -1787,7 +1781,7 @@ A `transformGroup` represents a set of transform elements or reorder elements. Each `transformGroup` is processed entirely before proceeding to the next one. -Each `transformGroup` element, after imports are processed, must have either [reorder](#Element_reorder) elements or [transform](#Element_transform) elements, but not both. The `` element may not be empty. +Each `transformGroup` element, after imports are processed, must have either [reorder](#element-reorder) elements or [transform](#element-transform) elements, but not both. The `` element may not be empty. **Examples** @@ -1822,7 +1816,7 @@ This is a `transformGroup` that consists of one or more [`transform`](#element-t * * * -### Element: transform +### Element: transform This element represents a single transform that may be performed using the keyboard layout. A transform is an element that specifies a set of conversions from sequences of code points into (one or more) other code points. For example, in most French keyboards hitting the `^` dead-key followed by the `e` key produces `ê`. @@ -1842,7 +1836,7 @@ All of the `transform` elements in a `transformGroup` are tested for a match, in > > -> Parents: [transformGroup](#Element_transformGroup) +> Parents: [transformGroup](#element-transformgroup) > Children: _none_ > Occurrence: required, multiple > @@ -1885,7 +1879,7 @@ _Attribute:_ `from` (required) - supported - no Unicode properties such as `\p{…}` - - Warning: Character classes look superficially similar to UnicodeSets as defined in [`unicodeSet`](#element-unicodeSet) elements, but they are different. UnicodeSets must be defined with a `unicodeSet` element, and referenced with the `$[unicodeSet]` notation in transforms. UnicodeSets cannot be used directly in a transform. + - Warning: Character classes look superficially similar to UnicodeSets as defined in [`unicodeSet`](#element-unicodeset) elements, but they are different. UnicodeSets must be defined with a `unicodeSet` element, and referenced with the `$[unicodeSet]` notation in transforms. UnicodeSets cannot be used directly in a transform. - **Bounded quantifier** @@ -2094,7 +2088,7 @@ Used in the `to=` * * * -### Element: reorder +### Element: reorder The reorder transform consists of a [``](#element-transformgroup) element containing `` elements. Multiple such `` elements may be contained in an enclosing `` element. @@ -2139,7 +2133,7 @@ The relative ordering of `` elements is not significant. > > -> Parents: [transformGroup](#Element_transformGroup) +> Parents: [transformGroup](#element-transformgroup) > Children: _none_ > Occurrence: optional, multiple > @@ -2355,7 +2349,7 @@ Another partial example allows a keyboard implementation to prevent people typin * * * -### transform type="backspace" +### Backspace Transforms The `` describe an optional transform that is not applied on input of normal characters, but is only used to perform extra backspace modifications to previously committed text. @@ -2463,7 +2457,7 @@ It is important that implementations do not by default delete more than one non- * * * -## Invariants +## Invariants Beyond what the DTD imposes, certain other restrictions on the data are imposed on the data. Please note the constraints given under each element section above. @@ -2506,11 +2500,11 @@ TODO: Rewrite this? Probably push out to each element's section? * * * -## Keyboard IDs +## Keyboard IDs There is a set of subtags that help identify the keyboards. Each of these are used after the `"t-k0"` subtags to help identify the keyboards. The first tag appended is a mandatory platform tag followed by zero or more tags that help differentiate the keyboard from others with the same locale code. -### Principles for Keyboard IDs +### Principles for Keyboard IDs The following are the design principles for the IDs. @@ -2524,7 +2518,7 @@ The following are the design principles for the IDs. 5. In order to get to 8 letters, abbreviations are reused that are already in [bcp47](https://github.com/unicode-org/cldr/blob/main/common/bcp47/) -u/-t extensions and in [language-subtag-registry](https://www.iana.org/assignments/language-subtag-registry) variants, eg for Traditional use `-trad` or `-traditio` (both exist in [bcp47](https://github.com/unicode-org/cldr/blob/main/common/bcp47/)). 6. Multiple languages cannot be indicated in the locale id, so the predominant target is used. 1. For Finnish + Sami, use `fi-t-k0-smi` or `extended-smi` - 2. The [``](#Element_locales) element may be used to identify additional languages. + 2. The [``](#element-locales) element may be used to identify additional languages. 7. In some cases, there are multiple subtags, like `en-US-t-k0-chromeos-intl-altgr.xml` 8. Otherwise, platform names are used as a guide. @@ -2562,7 +2556,7 @@ The following are the design principles for the IDs. * * * -## Platform Behaviors in Edge Cases +## Platform Behaviors in Edge Cases | Platform | No modifier combination match is available | No map match is available for key position | Transform fails (i.e. if \^d is pressed when that transform does not exist) | |----------|--------------------------------------------|--------------------------------------------|---------------------------------------------------------------------------| @@ -2602,7 +2596,7 @@ This is the top level element. _Attribute:_ `conformsTo` (required) -The `conformsTo` attribute here is the same as on the [``](#Element_Keyboard) element. +The `conformsTo` attribute here is the same as on the [``](#element-keyboard3) element. ```xml @@ -2731,7 +2725,7 @@ This attribute specifies a unique name for this suite of tests. These names coul > > Parents: [tests](#test-element-tests) > -> Children: [startContext](#test-element-startContext), [emit](#test-element-emit), [keystroke](#test-element-keystroke), [backspace](#test-element-backspace), [check](#test-element-check), [_special_](tr35.md#special) +> Children: [startContext](#test-element-startcontext), [emit](#test-element-emit), [keystroke](#test-element-keystroke), [backspace](#test-element-backspace), [check](#test-element-check), [_special_](tr35.md#special) > > Occurrence: Required, Multiple > @@ -2756,7 +2750,7 @@ This element specifies pre-existing text in a document, as if prior to the user > > -> Parents: [test](#Element_test) +> Parents: [test](#test-element-test) > > Children: _none_ > @@ -2765,7 +2759,7 @@ This element specifies pre-existing text in a document, as if prior to the user _Attribute:_ `to` (required) -Specifies the starting context. This text may be escaped with `\u` notation, see [Escaping](#Escaping). +Specifies the starting context. This text may be escaped with `\u` notation, see [Escaping](#escaping). **Example** @@ -2799,15 +2793,15 @@ This attribute specifies a key by means of the key’s `id` attribute. _Attribute:_ `flick` -This attribute specifies a flick gesture to be performed on the specified key instead of a keypress, such as `e` or `nw se`. This value corresponds to the `directions` attribute of the [``](#Element_flickSegment) element. +This attribute specifies a flick gesture to be performed on the specified key instead of a keypress, such as `e` or `nw se`. This value corresponds to the `directions` attribute of the [``](#element-flicksegment) element. _Attribute:_ `longPress` -This attribute specifies that a long press gesture should be performed on the specified key instead of a keypress. For example, `longPress="2"` indicates that the second character in a longpress series should be chosen. `longPress="0"` indicates that the `longPressDefault` value, if any, should be chosen. This corresponds to `longPress` and `longPressDefault` on [``](#Element_key). +This attribute specifies that a long press gesture should be performed on the specified key instead of a keypress. For example, `longPress="2"` indicates that the second character in a longpress series should be chosen. `longPress="0"` indicates that the `longPressDefault` value, if any, should be chosen. This corresponds to `longPress` and `longPressDefault` on [``](#element-key). _Attribute:_ `tapCount` -This attribute specifies that a multi-tap gesture should be performed on the specified key instead of a keypress. For example, `tapCount="3"` indicates that the key should be tapped three times in rapid succession. This corresponds to `multiTap` on [``](#Element_key). The minimum tapCount is 2. +This attribute specifies that a multi-tap gesture should be performed on the specified key instead of a keypress. For example, `tapCount="3"` indicates that the key should be tapped three times in rapid succession. This corresponds to `multiTap` on [``](#element-key). The minimum tapCount is 2. **Example** @@ -2839,7 +2833,7 @@ _Attribute:_ `to` (required) This attribute specifies a string of output text representing a single keystroke or gesture. This string is intended to match the output of a `key`, `flick`, `longPress` or `multiTap` element or attribute. Tooling should give a hint if this attribute does not match at least one keystroke or gesture. Note that the specified text is not injected directly into the output buffer. -This attribute may be escaped with `\u` notation, see [Escaping](#Escaping). +This attribute may be escaped with `\u` notation, see [Escaping](#escaping). **Example** @@ -2882,7 +2876,7 @@ This element represents a check on the current output buffer. _Attribute:_ `result` (required) -This attribute specifies the expected resultant text in a document after processing this event and all prior events, and including any `startContext` text. This text may be escaped with `\u` notation, see [Escaping](#Escaping). +This attribute specifies the expected resultant text in a document after processing this event and all prior events, and including any `startContext` text. This text may be escaped with `\u` notation, see [Escaping](#escaping). **Example** diff --git a/docs/ldml/tr35.md b/docs/ldml/tr35.md index 729734cd6ec..ae7b6da7994 100644 --- a/docs/ldml/tr35.md +++ b/docs/ldml/tr35.md @@ -56,6 +56,7 @@ The LDML specification is divided into the following parts: * [Introduction](#Introduction) * [Conformance](#Conformance) + * [EBNF](#ebnf) * [What is a Locale?](#Locale) * [Unicode Language and Locale Identifiers](#Unicode_Language_and_Locale_Identifiers) * _[Unicode Language Identifier](#Unicode_language_identifier)_ @@ -3733,30 +3734,7 @@ Part 1 Links: Core (this document): No redirects needed. ###### Table: Part 7 Links: [Keyboards](tr35-keyboards.md) (keyboard mappings) -| Old section | Section in new part | -| -------------------------------------------------------------------------------------------------------------------------- | ------------------- | -| S Keyboards | 1 [Introduction](tr35-keyboards.md#Introduction) | -| S Goals and Nongoals | [Goals and Nongoals](tr35-keyboards.md#Goals_and_Nongoals) | -| S File and Directory Structure | [File and Directory Structure](tr35-keyboards.md#File_and_Dir_Structure) | -| S Element Hierarchy - Layout File | [Element Hierarchy - Layout File](tr35-keyboards.md#Element_Heirarchy_Layout_File) | -| S Element Hierarchy - Platform File | [Element Hierarchy - Platform File](tr35-keyboards.md#Element_Heirarchy_Platform_File) | -| S Invariants | [Invariants](tr35-keyboards.md#Invariants) | -| S Data Sources | [Data Sources](tr35-keyboards.md#Data_Sources) | -| S Keyboard IDs | [Keyboard IDs](tr35-keyboards.md#Keyboard_IDs) | -| S Platform Behaviors in Edge Cases | [Platform Behaviors in Edge Cases](tr35-keyboards.md#Platform_Behaviors_in_Edge_Cases) | -| S Element: keyboard | [Element: keyboard](tr35-keyboards.md#Element_Keyboard) | -| S Element: version | [Element: version](tr35-keyboards.md#Element_version) | -| S Element: generation | [Element: generation](tr35-keyboards.md#Element_generation) | -| S Element: names | [Element: names](tr35-keyboards.md#Element_names) | -| S Element: name | [Element: name](tr35-keyboards.md#Element_name) | -| S Element: settings | [Element: settings](tr35-keyboards.md#Element_settings) | -| S Element: keyMap | [Element: keyMap](tr35-keyboards.md#Element_keyMap) | -| S Element: map | [Element: map](tr35-keyboards.md#Element_map) | -| S Element: transforms | [Element: transforms](tr35-keyboards.md#Element_transforms) | -| S Element: transform | [Element: transform](tr35-keyboards.md#Element_transform) | -| S Element: platform | [Element: platform](tr35-keyboards.md#Element_platform) | -| S Element: hardwareMap | [Element: hardwareMap](tr35-keyboards.md#Element_hardwareMap) | -| S Principles for Keyboard Ids | [Principles for Keyboard Ids](tr35-keyboards.md#Principles_for_Keyboard_Ids) | +[Part 7](tr35-keyboards.md) has been extensively rewritten. The prior link anchors within this file are no longer valid. * * *