Skip to content

Commit

Permalink
CLDR-00000 Automated Build of Pages
Browse files Browse the repository at this point in the history
  • Loading branch information
srl295 committed Oct 11, 2023
1 parent 3ce7c0e commit f821817
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 107 deletions.
78 changes: 31 additions & 47 deletions ldml/tr35-keyboards.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1036,7 +1036,6 @@
<span class="hljs-attr">stretch</span>=<span class="hljs-string">"true"</span>
<span class="hljs-attr">layerId</span>=<span class="hljs-string">"{switch layer id}"</span>
<span class="hljs-attr">output</span>=<span class="hljs-string">"{the output}"</span>
<span class="hljs-attr">transform</span>=<span class="hljs-string">"no"</span>
<span class="hljs-attr">width</span>=<span class="hljs-string">"{key width}"</span>
/&gt;</span>
</code></pre><blockquote>
Expand Down Expand Up @@ -1108,51 +1107,7 @@
</blockquote><p><em>Attribute:</em> <code>output</code></p><blockquote>
<p>The <code>output</code> attribute 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 <code>\u{...}</code> notation. More than one key may output the same output.</p>
<p>The <code>output</code> attribute may also contain the <code>\m{…}</code> syntax to insert a marker. See the definition of <a href="#markers">markers</a>.</p>
</blockquote><p><em>Attribute:</em> <code>transform="no"</code> (optional)</p><blockquote>
<p>The <code>transform</code> attribute is used to define a key that does not participate in a transform (until the next keystroke). This attribute value must be <code>"no"</code> if the attribute is present.
This attribute is useful where it is desired to output where two different keys could output the same characters (with different key or modifier combinations) but only one of them is intended to participate in a transform.
When the next keystroke is pressed, the prior output may then combine using other transforms.</p>
<p>Note that a more flexible way of solving this problem may be to use special markers which would inhibit matching.</p>
<p>For example, suppose there are the following keys, their output and one transform:</p>
</blockquote><pre><code class="language-xml"><span class="hljs-tag">&lt;<span class="hljs-name">keys</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"X"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^"</span> <span class="hljs-attr">transform</span>=<span class="hljs-string">"no"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"OptX"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">keys</span>&gt;</span>
…
<span class="hljs-tag">&lt;<span class="hljs-name">transforms</span> …&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transform</span> <span class="hljs-attr">from</span>=<span class="hljs-string">"^e"</span> <span class="hljs-attr">to</span>=<span class="hljs-string">"ê"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">transforms</span>&gt;</span>
</code></pre><ul>
<li><strong>X</strong> outputs <code>^</code> (caret)</li>
<li>Option-<strong>X</strong> outputs <code>^</code> but is intended to be the first part of a transform.</li>
<li>Option-<strong>X</strong> + <code>e</code> → <code>ê</code></li>
</ul><blockquote>
<p>Without the <code>transform="no"</code> on the base key <strong>X</strong>, it would not be possible to
type the sequence <code>^e</code> (caret+e) as it would turn into <code>ê</code> per the transform.
However, since there is <code>transform="no</code>" on <strong>X</strong>, if the user types <strong>X</strong> + <code>e</code> the sequence remains <code>^e</code>.</p>
</blockquote><ul>
<li><strong>X</strong> + <code>e</code> → <code>^e</code></li>
</ul><blockquote>
<p>Using markers, the same results can be obtained without need of <code>transform="no"</code> using:</p>
</blockquote><pre><code class="language-xml"><span class="hljs-tag">&lt;<span class="hljs-name">keys</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"X"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^\m{no_transform}"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"OptX"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">keys</span>&gt;</span>
…
<span class="hljs-tag">&lt;<span class="hljs-name">transforms</span> …&gt;</span>
<span class="hljs-comment">&lt;!-- this wouldn't match the key X output because of the marker --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transform</span> <span class="hljs-attr">from</span>=<span class="hljs-string">"^e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"ê"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">transforms</span>&gt;</span>
</code></pre><p>Even better is to use a marker to indicate where transforms are desired:</p><pre><code class="language-xml"><span class="hljs-tag">&lt;<span class="hljs-name">keys</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"X"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"OptX"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^\m{transform}"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">keys</span>&gt;</span>
…
<span class="hljs-tag">&lt;<span class="hljs-name">transforms</span> …&gt;</span>
<span class="hljs-comment">&lt;!-- again, this wouldn't match the key X output because of the missing marker --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transform</span> <span class="hljs-attr">from</span>=<span class="hljs-string">"^\m{transform}e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"ê"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">transforms</span>&gt;</span>
</code></pre><p><em>Attribute:</em> <code>width="1.2"</code> (optional, default "1.0")</p><blockquote>
</blockquote><p><em>Attribute:</em> <code>width="1.2"</code> (optional, default "1.0")</p><blockquote>
<p>The <code>width</code> attribute indicates that this key has a different width than other keys, by the specified number of key widths.</p>
</blockquote><pre><code class="language-xml"><span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"wide-a"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"a"</span> <span class="hljs-attr">width</span>=<span class="hljs-string">"1.2"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"wide-gap"</span> <span class="hljs-attr">gap</span>=<span class="hljs-string">"true"</span> <span class="hljs-attr">width</span>=<span class="hljs-string">"2.5"</span>/&gt;</span>
Expand Down Expand Up @@ -1676,7 +1631,36 @@
<li>character <code>ê</code></li>
</ul>
</li>
</ol><p><strong>Effect of markers on final text</strong></p><p>All markers must be removed before text is returned to the application from the input context.
</ol><p><strong>Using markers to inhibit other transforms</strong></p><p>Sometimes it is desirable to prevent transforms from having an effect.
Perhaps two different keys output the same characters, with different key or modifier combinations, but only one of them is intended to participate in a transform.</p><p>Consider the following case, where pressing the keys <code>X</code>, <code>e</code> results in <code>^e</code>, which is transformed into <code>ê</code>.</p><pre><code class="language-xml"><span class="hljs-tag">&lt;<span class="hljs-name">keys</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"X"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"e"</span> /&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">keys</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transforms</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transform</span> <span class="hljs-attr">from</span>=<span class="hljs-string">"^e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"ê"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">transforms</span>&gt;</span>
</code></pre><p>However, what if the user wanted to produce <code>^e</code> without the transform taking effect?
One strategy would be to use a marker, which won’t be visible in the output, but will inhibit the transform.</p><pre><code class="language-xml"><span class="hljs-tag">&lt;<span class="hljs-name">keys</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"caret"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^\m{no_transform}"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"X"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^"</span> /&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"e"</span> /&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">keys</span>&gt;</span>
…
<span class="hljs-tag">&lt;<span class="hljs-name">transforms</span>&gt;</span>
<span class="hljs-comment">&lt;!-- this wouldn't match the key X output because of the marker --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transform</span> <span class="hljs-attr">from</span>=<span class="hljs-string">"^e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"ê"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">transforms</span>&gt;</span>
</code></pre><p>Pressing <code>caret</code> <code>e</code> will result in <code>^e</code> (with an invisible <em>no_transform</em> marker — note that any name could be used). The <code>^e</code> won’t have the transform applied, at least while the marker’s context remains valid.</p><p>Another strategy might be to use a marker to indicate where transforms are desired, instead of where they aren't desired.</p><pre><code class="language-xml"><span class="hljs-tag">&lt;<span class="hljs-name">keys</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"caret"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"X"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"^\m{transform}"</span>/&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">key</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"e"</span> /&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">keys</span>&gt;</span>
…
<span class="hljs-tag">&lt;<span class="hljs-name">transforms</span> …&gt;</span>
<span class="hljs-comment">&lt;!-- Won't match ^e without marker. --&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">transform</span> <span class="hljs-attr">from</span>=<span class="hljs-string">"^\m{transform}e"</span> <span class="hljs-attr">output</span>=<span class="hljs-string">"ê"</span>/&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">transforms</span>&gt;</span>
</code></pre><p>In this way, only the <code>X</code>, <code>e</code> keys will produce <code>^e</code> with a <em>transform</em> marker (again, any name could be used) which will cause the transform to be applied. One benefit is that clicking or using the arrow key to navigate existing text with <code>^e</code> will never be affected by the transform, because the marker is not or no longer present.</p><p><strong>Effect of markers on final text</strong></p><p>All markers must be removed before text is returned to the application from the input context.
If the input context changes, such as if the cursor or mouse moves the insertion point somewhere else, all markers in the input context are removed.</p><p><strong>Implementation Notes</strong></p><p>Ideally, markers are implemented entirely out-of-band from the normal text stream. However, implementations <em>may</em> choose to map each marker to a <a href="https://www.unicode.org/glossary/#private_use_character">Unicode private-use character</a> for use only within the implementation’s processing and temporary storage in the input context.</p><p>For example, the first marker encountered could be represented as U+E000, the second by U+E001 and so on. If a regex processing engine were used, then those PUA characters could be processed through the existing regex processing engine. <code>[^\u{E000}-\u{E009}]</code> could be used as an expression to match a character that is not a marker, and <code>[Ee]\u{E000}</code> could match <code>E</code> or <code>e</code> followed by the first marker.</p><p>Such implementations must take care to remove all such markers (see prior section) from the resultant text. As well, implementations must take care to avoid conflicts if applications themselves are using PUA characters, such as is often done with not-yet-encoded scripts or characters.</p><hr><h3 id="Element_transformGroup"><a name="element-transformgroup" href="#Element_transformGroup">Element: transformGroup</a></h3><blockquote>
<small>

Expand Down
112 changes: 52 additions & 60 deletions ldml/tr35-keyboards.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -625,7 +625,6 @@ This element defines a mapping between an abstract key and its output. This elem
stretch="true"
layerId="{switch layer id}"
output="{the output}"
transform="no"
width="{key width}"
/>
```
Expand Down Expand Up @@ -741,65 +740,6 @@ _Attribute:_ `output`
>
> The `output` attribute may also contain the `\m{…}` syntax to insert a marker. See the definition of [markers](#markers).
_Attribute:_ `transform="no"` (optional)
> The `transform` attribute is used to define a key that does not participate in a transform (until the next keystroke). This attribute value must be `"no"` if the attribute is present.
> This attribute is useful where it is desired to output where two different keys could output the same characters (with different key or modifier combinations) but only one of them is intended to participate in a transform.
> When the next keystroke is pressed, the prior output may then combine using other transforms.
>
> Note that a more flexible way of solving this problem may be to use special markers which would inhibit matching.
>
> For example, suppose there are the following keys, their output and one transform:
```xml
<keys>
<key id="X" output="^" transform="no"/>
<key id="OptX" output="^"/>
</keys>
…
<transforms …>
<transform from="^e" to="ê"/>
</transforms>
```
* **X** outputs `^` (caret)
* Option-**X** outputs `^` but is intended to be the first part of a transform.
* Option-**X** + `e` → `ê`

> Without the `transform="no"` on the base key **X**, it would not be possible to
> type the sequence `^e` (caret+e) as it would turn into `ê` per the transform.
> However, since there is `transform="no`" on **X**, if the user types **X** + `e` the sequence remains `^e`.
* **X** + `e` → `^e`

> Using markers, the same results can be obtained without need of `transform="no"` using:
```xml
<keys>
<key id="X" output="^\m{no_transform}"/>
<key id="OptX" output="^"/>
</keys>
…
<transforms …>
<!-- this wouldn't match the key X output because of the marker -->
<transform from="^e" output="ê"/>
</transforms>
```

Even better is to use a marker to indicate where transforms are desired:

```xml
<keys>
<key id="X" output="^"/>
<key id="OptX" output="^\m{transform}"/>
</keys>
…
<transforms …>
<!-- again, this wouldn't match the key X output because of the missing marker -->
<transform from="^\m{transform}e" output="ê"/>
</transforms>
```

_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.
Expand Down Expand Up @@ -1764,6 +1704,58 @@ Consider the following abbreviated example:
- …
- character `ê`

**Using markers to inhibit other transforms**

Sometimes it is desirable to prevent transforms from having an effect.
Perhaps two different keys output the same characters, with different key or modifier combinations, but only one of them is intended to participate in a transform.

Consider the following case, where pressing the keys `X`, `e` results in `^e`, which is transformed into `ê`.

```xml
<keys>
<key id="X" output="^"/>
<key id="e" output="e" />
</keys>
<transforms>
<transform from="^e" output="ê"/>
</transforms>
```

However, what if the user wanted to produce `^e` without the transform taking effect?
One strategy would be to use a marker, which won’t be visible in the output, but will inhibit the transform.

```xml
<keys>
<key id="caret" output="^\m{no_transform}"/>
<key id="X" output="^" />
<key id="e" output="e" />
</keys>
…
<transforms>
<!-- this wouldn't match the key X output because of the marker -->
<transform from="^e" output="ê"/>
</transforms>
```

Pressing `caret` `e` will result in `^e` (with an invisible _no_transform_ marker — note that any name could be used). The `^e` won’t have the transform applied, at least while the marker’s context remains valid.

Another strategy might be to use a marker to indicate where transforms are desired, instead of where they aren't desired.

```xml
<keys>
<key id="caret" output="^"/>
<key id="X" output="^\m{transform}"/>
<key id="e" output="e" />
</keys>
…
<transforms …>
<!-- Won't match ^e without marker. -->
<transform from="^\m{transform}e" output="ê"/>
</transforms>
```

In this way, only the `X`, `e` keys will produce `^e` with a _transform_ marker (again, any name could be used) which will cause the transform to be applied. One benefit is that clicking or using the arrow key to navigate existing text with `^e` will never be affected by the transform, because the marker is not or no longer present.

**Effect of markers on final text**

All markers must be removed before text is returned to the application from the input context.
Expand Down

0 comments on commit f821817

Please sign in to comment.