From 4db337a7352b47d7f19243650935f753787b6008 Mon Sep 17 00:00:00 2001 From: "Steven R. Loomis" Date: Fri, 29 Mar 2024 09:27:22 -0500 Subject: [PATCH] CLDR-17485 kbd: remove keyboard testdata (techpreview) from tr35 - moves to keyboards/test subdirectory - also, update ToC - also, update ToC generator to support out-of-dir tables of contents --- docs/ldml/tr35-keyboards.md | 388 ----------------------------------- keyboards/test/README.md | 395 ++++++++++++++++++++++++++++++++++++ 2 files changed, 395 insertions(+), 388 deletions(-) create mode 100644 keyboards/test/README.md diff --git a/docs/ldml/tr35-keyboards.md b/docs/ldml/tr35-keyboards.md index 4c559eb1499..d221ab48a5f 100644 --- a/docs/ldml/tr35-keyboards.md +++ b/docs/ldml/tr35-keyboards.md @@ -132,19 +132,6 @@ The LDML specification is divided into the following parts: * [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) - * [Test Element: info](#test-element-info) - * [Test Element: repertoire](#test-element-repertoire) - * [Test Element: tests](#test-element-tests) - * [Test Element: test](#test-element-test) - * [Test Element: startContext](#test-element-startcontext) - * [Test Element: keystroke](#test-element-keystroke) - * [Test Element: emit](#test-element-emit) - * [Test Element: backspace](#test-element-backspace) - * [Test Element: check](#test-element-check) - * [Test Examples](#test-examples) ## Keyboards @@ -2877,381 +2864,6 @@ The following are the design principles for the IDs. * * * -## Keyboard Test Data - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - -Keyboard Test Data allows the keyboard author to provide regression test data to validate the repertoire and behavior of a keyboard. Tooling can run these regression tests against an implementation, and can also be used as part of the development cycle to validate that keyboard changes do not deviate from expected behavior. In the interest of complete coverage, tooling could also indicate whether all keys and gestures in a layout are exercised by the test data. - -Test data files have a separate DTD, named `ldmlKeyboardTest3.dtd`. Note that multiple test data files can refer to the same keyboard. Test files should be named similarly to the keyboards which they test, such as `fr_test.xml` to test `fr.xml`. - -Sample test data files are located in the `keyboards/test` subdirectory. - -The following describes the structure of a keyboard test file. - -### Test Doctype - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - -```xml - - -``` - -The top level element is named `keyboardTest`. - -### Test Element: keyboardTest - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - -> -> -> Children: [info](#test-element-info), [repertoire](#test-element-repertoire), [_special_](tr35.md#special), [tests](#test-element-tests) -> - -This is the top level element. - -_Attribute:_ `conformsTo` (required) - -The `conformsTo` attribute value here is a fixed value of `techpreview`, because the test data is a Technical Preview. - -```xml - - - - … - -``` - -### Test Element: info - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - -> -> -> Parents: [keyboardTest](#test-element-keyboardtest) ->> -> Occurrence: Required, Single -> - -_Attribute:_ `author` - -This freeform attribute value allows for description of the author or authors of this test file. - -_Attribute:_ `keyboard` (required) - -This attribute value specifies the keyboard’s file name, such as `fr-t-k0-azerty.xml`. - -_Attribute:_ `name` (required) - -This attribute value specifies a name for this overall test file. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. - -**Example** - -```xml - -``` - -### Test Element: repertoire - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - -> -> -> Parents: [keyboardTest](#test-element-keyboardtest) -> -> Children: _none_ -> -> Occurrence: Optional, Multiple -> - -This element contains a repertoire test, to validate the available characters and their reachability. This test ensures that each of the specified characters is somehow typeable on the keyboard, after transforms have been applied. The characters in the repertoire will be matched against the complete set of possible generated outputs, post-transform, of all keys on the keyboard. - -_Attribute:_ `name` (required) - -This attribute value specifies a unique name for this repertoire test. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. - -_Attribute:_ `type` - -This attribute value is one of the following: - -| type | Meaning | -|-----------|----------------------------------------------------------------------------------------------------------| -| default | This is the default, indicates that _any_ gesture or keystroke may be used to generate each character | -| simple | Each of the characters must be typeable by simple single keystrokes without needing any gestures. | -| gesture | The characters are typeable by use of any gestures such as flicks, long presses, or multiple taps. | -| flick | The characters are typeable by use of any `flick` element. | -| longPress | The characters are typeable by use of any `longPress` value. | -| multiTap | The characters are typeable by use of any `multiTap` value. | -| hardware | The characters are typeable by use of any simple keystrokes on any hardware layout. | - -_Attribute:_ `chars` (required) - -This attribute value specifies a list of characters in UnicodeSet format, which is specified in [UTS #35 Part One](tr35.md#Unicode_Sets). - -**Example** - -```xml - - - - - - - - -``` - -Note: CLDR’s extensive [exemplar set](tr35-general.md#Character_Elements) data may be useful in validating a language’s repertoire against a keyboard. Tooling may wish to make use of this data in order to suggest recommended repertoire values for a language. - -### Test Element: tests - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - - -> -> -> Parents: [keyboardTest](#test-element-keyboardtest) -> -> Children: [_special_](tr35.md#special), [test](#test-element-test) -> -> Occurrence: Optional, Multiple -> - -This element specifies a particular suite of `` elements. - -_Attribute:_ `name` (required) - -This attribute value specifies a unique name for this suite of tests. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. - -**Example** - -```xml - - - … - - - … - - - - - … - - -``` - -### Test Element: test - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - - -> -> -> 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) -> -> Occurrence: Required, Multiple -> - -This attribute value specifies a specific isolated regression test. Multiple test elements do not interact with each other. - -The order of child elements is significant, with cumulative effects: they must be processed from first to last. - -_Attribute:_ `name` (required) - -This attribute value specifies a unique name for this particular test. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. - -**Example** - -```xml - -``` - -### Test Element: startContext - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - -This element specifies pre-existing text in a document, as if prior to the user’s insertion point. This is useful for testing transforms and reordering. If not specified, the startContext can be considered to be the empty string (""). - -> -> -> Parents: [test](#test-element-test) -> -> Children: _none_ -> -> Occurrence: Optional, Single -> - -_Attribute:_ `to` (required) - -Specifies the starting context. This text may be escaped with `\u` notation, see [Escaping](#escaping). - -**Example** - -```xml - -``` - - -### Test Element: keystroke - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - - -> -> -> Parents: [test](#test-element-test) -> -> Children: _none_ -> -> Occurrence: Optional, Multiple -> - -This element contains a single keystroke or other gesture event, identified by a particular key element. - -Optionally, one of the gesture attributes, either `flick`, `longPress`, or `tapCount` may be specified. If none of the gesture attribute values are specified, then a regular keypress is effected on the key. It is an error to specify more than one gesture attribute. - -If a key is not found, or a particular gesture has no definition, the output should be behave as if the user attempted to perform such an action. For example, an unspecified `flick` would result in no output. - -When a key is found, processing continues with the transform and other elements before updating the test output buffer. - -_Attribute:_ `key` (required) - -This attribute value specifies a key by means of the key’s `id` attribute. - -_Attribute:_ `flick` - -This attribute value 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 value of the [``](#element-flicksegment) element. - -_Attribute:_ `longPress` - -This attribute value 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 value 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** - -```xml - - - - - -``` - -### Test Element: emit - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - - -> -> -> Parents: [test](#test-element-test) -> -> Children: _none_ -> -> Occurrence: Optional, Multiple -> - -This element also contains an input event, except that the input is specified in terms of textual value rather than key or gesture identity. This element is particularly useful for testing transforms. - -Processing of the specified text continues with the transform and other elements before updating the test output buffer. - -_Attribute:_ `to` (required) - -This attribute value 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 value does not match at least one keystroke or gesture. Note that the specified text is not injected directly into the output buffer. - -This attribute value may be escaped with `\u` notation, see [Escaping](#escaping). - -**Example** - -```xml - -``` - - -### Test Element: backspace - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - - -> -> -> Parents: [test](#test-element-test) -> -> Children: _none_ -> -> Occurrence: Optional, Multiple -> - -This element contains a backspace action, as if the user typed the backspace key - -**Example** - -```xml - -``` - -### Test Element: check - -> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. - - -> -> -> Parents: [test](#test-element-test) -> -> Children: _none_ -> -> Occurrence: Optional, Multiple -> - -This element contains a check on the current output buffer. - -_Attribute:_ `result` (required) - -This attribute value 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** - -```xml - -``` - - -### Test Examples - -```xml - - - - - - - - - - - - - - - - - - - -``` - -* * * - Copyright © 2001–2024 Unicode, Inc. All Rights Reserved. The Unicode Consortium makes no expressed or implied warranty of any kind, and assumes no liability for errors or omissions. No liability is assumed for incidental and consequential damages in connection with or arising out of the use of the information or programs contained or accompanying this technical report. The Unicode [Terms of Use](https://www.unicode.org/copyright.html) apply. Unicode and the Unicode logo are trademarks of Unicode, Inc., and are registered in some jurisdictions. diff --git a/keyboards/test/README.md b/keyboards/test/README.md new file mode 100644 index 00000000000..d0ff8308ca6 --- /dev/null +++ b/keyboards/test/README.md @@ -0,0 +1,395 @@ +# Technical Preview: CLDR Keyboard Test Data + +## Contents of CLDR Keyboard Test Data + +* [Keyboard Test Data](#keyboard-test-data) + * [Test Doctype](#test-doctype) + * [Test Element: keyboardTest](#test-element-keyboardtest) + * [Test Element: info](#test-element-info) + * [Test Element: repertoire](#test-element-repertoire) + * [Test Element: tests](#test-element-tests) + * [Test Element: test](#test-element-test) + * [Test Element: startContext](#test-element-startcontext) + * [Test Element: keystroke](#test-element-keystroke) + * [Test Element: emit](#test-element-emit) + * [Test Element: backspace](#test-element-backspace) + * [Test Element: check](#test-element-check) + * [Test Examples](#test-examples) +* [Copyright and License](#copyright-and-license) + +## Keyboard Test Data + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + +Keyboard Test Data allows the keyboard author to provide regression test data to validate the repertoire and behavior of a keyboard. Tooling can run these regression tests against an implementation, and can also be used as part of the development cycle to validate that keyboard changes do not deviate from expected behavior. In the interest of complete coverage, tooling could also indicate whether all keys and gestures in a layout are exercised by the test data. + +Test data files have a separate DTD, named `ldmlKeyboardTest3.dtd`. Note that multiple test data files can refer to the same keyboard. Test files should be named similarly to the keyboards which they test, such as `fr_test.xml` to test `fr.xml`. + +Sample test data files are located in the `keyboards/test` subdirectory. + +The following describes the structure of a keyboard test file. + +### Test Doctype + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + +```xml + + +``` + +The top level element is named `keyboardTest`. + +### Test Element: keyboardTest + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + +> +> +> Children: [info](#test-element-info), [repertoire](#test-element-repertoire), [_special_](tr35.md#special), [tests](#test-element-tests) +> + +This is the top level element. + +_Attribute:_ `conformsTo` (required) + +The `conformsTo` attribute value here is a fixed value of `techpreview`, because the test data is a Technical Preview. + +```xml + + + + … + +``` + +### Test Element: info + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + +> +> +> Parents: [keyboardTest](#test-element-keyboardtest) +>> +> Occurrence: Required, Single +> + +_Attribute:_ `author` + +This freeform attribute value allows for description of the author or authors of this test file. + +_Attribute:_ `keyboard` (required) + +This attribute value specifies the keyboard’s file name, such as `fr-t-k0-azerty.xml`. + +_Attribute:_ `name` (required) + +This attribute value specifies a name for this overall test file. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. + +**Example** + +```xml + +``` + +### Test Element: repertoire + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + +> +> +> Parents: [keyboardTest](#test-element-keyboardtest) +> +> Children: _none_ +> +> Occurrence: Optional, Multiple +> + +This element contains a repertoire test, to validate the available characters and their reachability. This test ensures that each of the specified characters is somehow typeable on the keyboard, after transforms have been applied. The characters in the repertoire will be matched against the complete set of possible generated outputs, post-transform, of all keys on the keyboard. + +_Attribute:_ `name` (required) + +This attribute value specifies a unique name for this repertoire test. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. + +_Attribute:_ `type` + +This attribute value is one of the following: + +| type | Meaning | +|-----------|----------------------------------------------------------------------------------------------------------| +| default | This is the default, indicates that _any_ gesture or keystroke may be used to generate each character | +| simple | Each of the characters must be typeable by simple single keystrokes without needing any gestures. | +| gesture | The characters are typeable by use of any gestures such as flicks, long presses, or multiple taps. | +| flick | The characters are typeable by use of any `flick` element. | +| longPress | The characters are typeable by use of any `longPress` value. | +| multiTap | The characters are typeable by use of any `multiTap` value. | +| hardware | The characters are typeable by use of any simple keystrokes on any hardware layout. | + +_Attribute:_ `chars` (required) + +This attribute value specifies a list of characters in UnicodeSet format, which is specified in [UTS #35 Part One](tr35.md#Unicode_Sets). + +**Example** + +```xml + + + + + + + + +``` + +Note: CLDR’s extensive [exemplar set](tr35-general.md#Character_Elements) data may be useful in validating a language’s repertoire against a keyboard. Tooling may wish to make use of this data in order to suggest recommended repertoire values for a language. + +### Test Element: tests + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + + +> +> +> Parents: [keyboardTest](#test-element-keyboardtest) +> +> Children: [_special_](tr35.md#special), [test](#test-element-test) +> +> Occurrence: Optional, Multiple +> + +This element specifies a particular suite of `` elements. + +_Attribute:_ `name` (required) + +This attribute value specifies a unique name for this suite of tests. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. + +**Example** + +```xml + + + … + + + … + + + + + … + + +``` + +### Test Element: test + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + + +> +> +> 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) +> +> Occurrence: Required, Multiple +> + +This attribute value specifies a specific isolated regression test. Multiple test elements do not interact with each other. + +The order of child elements is significant, with cumulative effects: they must be processed from first to last. + +_Attribute:_ `name` (required) + +This attribute value specifies a unique name for this particular test. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components. + +**Example** + +```xml + +``` + +### Test Element: startContext + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + +This element specifies pre-existing text in a document, as if prior to the user’s insertion point. This is useful for testing transforms and reordering. If not specified, the startContext can be considered to be the empty string (""). + +> +> +> Parents: [test](#test-element-test) +> +> Children: _none_ +> +> Occurrence: Optional, Single +> + +_Attribute:_ `to` (required) + +Specifies the starting context. This text may be escaped with `\u` notation, see [Escaping](#escaping). + +**Example** + +```xml + +``` + + +### Test Element: keystroke + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + + +> +> +> Parents: [test](#test-element-test) +> +> Children: _none_ +> +> Occurrence: Optional, Multiple +> + +This element contains a single keystroke or other gesture event, identified by a particular key element. + +Optionally, one of the gesture attributes, either `flick`, `longPress`, or `tapCount` may be specified. If none of the gesture attribute values are specified, then a regular keypress is effected on the key. It is an error to specify more than one gesture attribute. + +If a key is not found, or a particular gesture has no definition, the output should be behave as if the user attempted to perform such an action. For example, an unspecified `flick` would result in no output. + +When a key is found, processing continues with the transform and other elements before updating the test output buffer. + +_Attribute:_ `key` (required) + +This attribute value specifies a key by means of the key’s `id` attribute. + +_Attribute:_ `flick` + +This attribute value 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 value of the [``](#element-flicksegment) element. + +_Attribute:_ `longPress` + +This attribute value 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 value 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** + +```xml + + + + + +``` + +### Test Element: emit + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + + +> +> +> Parents: [test](#test-element-test) +> +> Children: _none_ +> +> Occurrence: Optional, Multiple +> + +This element also contains an input event, except that the input is specified in terms of textual value rather than key or gesture identity. This element is particularly useful for testing transforms. + +Processing of the specified text continues with the transform and other elements before updating the test output buffer. + +_Attribute:_ `to` (required) + +This attribute value 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 value does not match at least one keystroke or gesture. Note that the specified text is not injected directly into the output buffer. + +This attribute value may be escaped with `\u` notation, see [Escaping](#escaping). + +**Example** + +```xml + +``` + + +### Test Element: backspace + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + + +> +> +> Parents: [test](#test-element-test) +> +> Children: _none_ +> +> Occurrence: Optional, Multiple +> + +This element contains a backspace action, as if the user typed the backspace key + +**Example** + +```xml + +``` + +### Test Element: check + +> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR. + + +> +> +> Parents: [test](#test-element-test) +> +> Children: _none_ +> +> Occurrence: Optional, Multiple +> + +This element contains a check on the current output buffer. + +_Attribute:_ `result` (required) + +This attribute value 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** + +```xml + +``` + + +### Test Examples + +```xml + + + + + + + + + + + + + + + + + + + +``` + +## Copyright and License + +See the top level [README.md](../../README.md#copyright--licenses)