Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Address @r12a's comments plus add spillover definition #27

Merged
merged 8 commits into from
Mar 28, 2023

Conversation

aphillips
Copy link
Collaborator

@aphillips aphillips commented Mar 22, 2023

@aphillips aphillips requested a review from r12a March 22, 2023 16:59
@netlify
Copy link

netlify bot commented Mar 22, 2023

Deploy Preview for i18n-glossary ready!

Name Link
🔨 Latest commit b5ab234
🔍 Latest deploy log https://app.netlify.com/sites/i18n-glossary/deploys/6421f58385c88b0008739ce4
😎 Deploy Preview https://deploy-preview-27--i18n-glossary.netlify.app/
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@aphillips aphillips changed the title Address @r12a's comments Address @r12a's comments plus add spillover definition Mar 22, 2023
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
- remove spillover example in favor of bidi isolation
- add right-to-left and left-to-right to RTL and LTR dfns
- Tweak wording of spillover
- Link bidi isolation to spillover
@aphillips aphillips requested a review from r12a March 23, 2023 17:08
The current definition of bidi isolation is not written like a
definition. Making it into a definition was easier by introducing the
concept of a bidi isolate and then referring to it.
@aphillips
Copy link
Collaborator Author

@r12a I added 822b7b7 because the term bidi isolation wasn't written like a definition. Please have a look at that part of the change and make comments.

@aphillips aphillips merged commit bcf4819 into w3c:gh-pages Mar 28, 2023
@r12a
Copy link
Contributor

r12a commented Mar 29, 2023

I finally found some time to look at this. I have a couple of concerns that i'll raise as inline comments.

@@ -164,7 +164,9 @@ <h2>Glossary</h2>

<p><dfn data-lt="basic language range|Basic language range" class="lint-ignore export">Basic language range</dfn>. A [=language range=] consisting of a sequence of subtags separated by hyphens. That is, it is identical in appearance to a language tag.</p>

<p><dfn class="lint-ignore export">Bidi isolation</dfn>. Isolation often needs to be applied to a range of text in order to prevent the automatic rules of the Unicode Bidirectional Algorithm incorrectly ordering that content in relation to the surrounding text. For example, numbers following right-to-left text in memory are automatically positioned to the left of that text by the Bidi Algorithm, but sometimes need to appear to the right. Another example occurs when lists of RTL items occur in a LTR sentence: the Bidi Algorithm will automatically assume that the order of items in the list should be "3 ,2 ,1", but actually what's needed is "1, 2, 3". In HTML, bidi isolation can be applied to a range of text by enclosing it in an element with a <code class="kw" translate="no">dir</code> attribute. In plain text there are Unicode formatting characters that can do the job. These mechanisms remove unwanted 'spillover effects'.</p>
<p><dfn class="lint-ignore export" data-lt="bidi isolate">Bidirectional isolate</dfn>. Defined by the [=Unicode Bidirectional Algorithm=] [[UAX9]], an <em>isolate</em> is a range of text whose contents do not participate in the embedding and reordering of the surrounding text the range appears in, which prevents the bidi algorithm from incorrectly ordering that content in relation to the surrounding text.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a tricky definition to pin down, and is one we're inventing rather than something explicitly defined in UAX#9.

In UAX#9 the concept of 'isolate' appears to be defined in terms of text that is bounded by specific formatting characters, namely LRI, RLI, or FSI. I don't see any 'definition' of isolate – only a description of isolate formatting characters that in only a small handful of places refers to the term isolate when referring to the text itself.

'Isolates' as described here do in fact participate in the reordering of surrounding text, but do so as a neutral unit.

Also, the sentence is very long.

Suggestion:
A range of text, bounded by formatting characters or markup, such that the contents do not interact with the surrounding text per the rules of the [=Unicode Bidirectional Algorithm=] [[UAX9]]. In certain circumstances, isolation prevents the incorrect ordering of content by the bidi algorithm.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed about the complexity here.

I like the suggestion okay, but the "certain circumstances" part made me nervous. I went back to UAX9 and harvested text found in https://www.unicode.org/reports/tr9/#Explicit_Directional_Isolates to make this:

Suggested change
<p><dfn class="lint-ignore export" data-lt="bidi isolate">Bidirectional isolate</dfn>. Defined by the [=Unicode Bidirectional Algorithm=] [[UAX9]], an <em>isolate</em> is a range of text whose contents do not participate in the embedding and reordering of the surrounding text the range appears in, which prevents the bidi algorithm from incorrectly ordering that content in relation to the surrounding text.</p>
<p><dfn class="lint-ignore export" data-lt="bidi isolate">Bidirectional isolate</dfn>. A range of text, bounded by formatting characters or markup, that is treated by the [=Unicode Bidirectional Algorithm=] [[UAX9]] as directionally isolated from its surroundings. The entire range of text inside the isolate is treated by the surrounding text as if it were a single neutral character (such as <span class="codepoint" translate="no"><bdi lang="en">&#xFFFC;</bdi> [<span class="uname">U+FFFC OBJECT REPLACEMENT CHARACTER</span>])</span>, and is assigned the corresponding display position in the surrounding text. Furthermore, the text inside the isolate has no effect on the ordering of the text outside it, and vice versa.</p>

See #34 for this as part of a PR. Please comment on it!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this has become a tutorial rather than a definition.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough, although it is quoting UAX9.

<p><dfn class="lint-ignore export">Bidi isolation</dfn>. Isolation often needs to be applied to a range of text in order to prevent the automatic rules of the Unicode Bidirectional Algorithm incorrectly ordering that content in relation to the surrounding text. For example, numbers following right-to-left text in memory are automatically positioned to the left of that text by the Bidi Algorithm, but sometimes need to appear to the right. Another example occurs when lists of RTL items occur in a LTR sentence: the Bidi Algorithm will automatically assume that the order of items in the list should be "3 ,2 ,1", but actually what's needed is "1, 2, 3". In HTML, bidi isolation can be applied to a range of text by enclosing it in an element with a <code class="kw" translate="no">dir</code> attribute. In plain text there are Unicode formatting characters that can do the job. These mechanisms remove unwanted 'spillover effects'.</p>
<p><dfn class="lint-ignore export" data-lt="bidi isolate">Bidirectional isolate</dfn>. Defined by the [=Unicode Bidirectional Algorithm=] [[UAX9]], an <em>isolate</em> is a range of text whose contents do not participate in the embedding and reordering of the surrounding text the range appears in, which prevents the bidi algorithm from incorrectly ordering that content in relation to the surrounding text.</p>

<p><dfn class="lint-ignore export">Bidi isolation</dfn>. The use of [=bidi isolates=] in text in order to prevent the automatic rules of the Unicode Bidirectional Algorithm incorrectly ordering that content in relation to the surrounding text. For example, numbers following right-to-left text in memory are automatically positioned to the left of that text by the Bidi Algorithm, but sometimes need to appear to the right. Another example occurs when lists of RTL items occur in a LTR sentence: the Bidi Algorithm will automatically assume that the order of items in the list should be "3 ,2 ,1", but actually what's needed is "1, 2, 3". In HTML, bidi isolation can be applied to a range of text by enclosing it in an element with a <code class="kw" translate="no">dir</code> attribute. In plain text there are Unicode formatting characters that can do the job. These mechanisms remove unwanted [=spillover effects=].</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

positioned to the left of that text -> positioned to the left of RTL text

lists of RTL items occur in a LTR sentence -> a list of RTL items occur in a LTR sentence (and vice versa)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

occur -> occurs

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done (in #34)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not quite.
lists of RTL items occurs -> a list of RTL items occurs

aphillips added a commit to aphillips/i18n-glossary that referenced this pull request Mar 29, 2023
<p>If you are writing a W3C specification, you can use the terminology in this document directly by importing this document as a cross-reference source. This may be especially helpful when using <a>character encoding</a> or <a>locale</a>-related terms found here. Such terms are common to the needs of many specifications and often refer to other definitions found in this glossary. In most cases, though, copying these definitions into your specification won't add value to your readers.</p>
<p>If you are writing a W3C specification, you can use the terminology in this document directly by importing this document as a cross-reference source. This may be especially helpful when using <a>character encoding</a> or <a>locale</a>-related terms found here. Such terms are common to the needs of many specifications and often refer to other definitions found in this glossary.</p>

<p>This glossary is a Working Group NOTE, which means that the definitions found in it are, by definition, non-normative. In most cases, most specifications do not need the definition of terms found here to be formally normative. Using the definitions found here lends clarity when using specialized terminology, but doesn't affect requirements directly and in those cases copying these definitions into your specification won't add value to your readers.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to the MOS, 'Note' should be used instead of 'NOTE'.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants