Address issues raised by recent reviews #89

aphillips · 2023-01-27T18:39:39Z

editor's copy locations include the fragment reference and are linked to @aphillips's repo version, since that displays more nicely than the diff/preview)

Addresses #88
Add guidance for generating bidirectional labels/descriptions
Caused by w3c/i18n-activity#1638
editor's copy location #strcat

Addresses #83
Add guidance on Unicode code point order
editor's copy location #char_sort

Addresses #69
Add information about constituent parts of BCP47 (specifically 4647)
editor's copy location #lang_bcp_not_rfc
editor's copy location #lang_matching_bcp

Addresses #14
Add guidance on using the ILSTR instead of making your own list of subtags
editor's copy location #use_lstr

Preview | Diff

labels/descriptions. Addresses w3c#88

Add guidance on Unicode code point order.

@r12a

Add a reference to 4647 when talking about BCP47 Also moved requirements above explanation per our standard (thanks @r12a)

Mention of using the language subtag registry instead of making your own list. Also some cleanup of the language tagging of the Arabic examples.

index.html

This resulted in a bit of a rewrite. In addition, I added links to the "choosing a language tag" article, Richard's language subtag lookup tool, and the registry itself.

A couple of browsers don't seem to display the "fixed" bidi example correctly, at least when respec runs on it. Switching to markup, which is effective. Also rewrite the "notice how" paragraph to be (hopefully) clearer.

- made the example text larger to make the color mixing clearer - simplified the description of the mixing problem

- Removed the charmod reqs altogether - Added a "warning" box about find being hard and linking our string-search doc

xfq · 2023-02-07T07:16:45Z

I noticed that Netlify wasn't working. It seems like someone revoked access to all W3C repos (not just the i18n ones). I'll try to add it back.

- Removed extreneous link to specdev? - Described matching in terms of ranges rather than subtags (4647 is not about matching subtags) - Cleaned up description of 5656, including mentioning the LSTR

Made the example clear that the code units are in the UTF-16 character encoding.

@r12a

- Added a requirement not to concat strings! - Added a "seealso" suggested by @r12a - Added explanation of the Note example - Minor wording changes in the colorful example.

netlify · 2023-02-09T16:58:48Z

✅ Deploy Preview for bp-i18n-specdev ready!

Name	Link
🔨 Latest commit	`6ce0aea`
🔍 Latest deploy log	https://app.netlify.com/sites/bp-i18n-specdev/deploys/64135070ca95a60008fc72d0
😎 Deploy Preview	https://deploy-preview-89--bp-i18n-specdev.netlify.app/
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

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

The example note should be preceeded by the explanation.

- add exampleChar style (borrowed from our other specs) - renamed bidi_gen to strcat - clarified further the concat section - added links to uts10 and icu user guide for sorting - moved langtag matching to its own section and fixed label

local.css

aphillips · 2023-03-24T19:26:57Z

@r12a Could you look at this for merging-readiness? I'd like to include these changes when pushing to TR...

r12a · 2023-03-29T15:26:41Z

index.html


+<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Astrcat" target="_blank">See related review comments.</a></p>
+
+<div class="req" id="strcat_anti_pattern">


I don't think people will find this general advice about composite messages, that has nothing to do with text direction.

I think it is best to move the section "Composite Strings" under 'Text-processing" and then add a 'see also' to the text direction section 3.6.

pending telecon discuss

r12a · 2023-03-29T15:31:10Z

index.html

+</div>
+
+<div class="req" id="bidi_gen_advice">
+	<p class="advisement">Specifications SHOULD provide guidance to implementers on avoiding problems with text directionality for any field(s) that the specification requires an implementation to create or generate for display to users.</p>


Rather a complicated and long sentence.

How about:
When a specification requires an implementation to create or generate text which will be displayed to users, the specification should provide implementers with guidance on
how to avoid potential problems related to text direction.

r12a · 2023-03-29T15:43:09Z

index.html

+	<p class="advisement">Specifications SHOULD provide guidance to implementers on avoiding problems with text directionality for any field(s) that the specification requires an implementation to create or generate for display to users.</p>
+</div>
+
+<p>Specifications for APIs, protocols, or document formats sometimes require an implementation to create or provide a field containing a display name or description. When such a string is assembled from separate parts, it can result in problems with presentation or understanding due to the way that the <cite>Unicode Bidirectional Algorithm</cite> [[UAX9]] processes the assembled string. In such cases, the specification should guide implementers about how to create values that will display properly.</p>


Several things are unclear to me here, and rather than provide text suggestions that may be barking up the wrong tree, we should perhaps discuss during our telecon. Questions include:

do you mean bidrectional text or text that generally runs in a particular direction (eg. RTL)?

i suspect, but i'm not sure, that we are talking solely about strings that contain bidirectional text within them, or about correctly displaying any string that is inserted into a target location by the consumer?

if the latter, we're focusing on what producers need to do, we should mention dirname or using other metadata

Basically, i think we need a little more clarity about the role of producers vs consumers, and in-string direction vs how a string will be inserted into a target location. It seems a little vague at the moment. The section title, Concatenation of Strings, doesn't make it sound like we're concerned with string internal direction, but rather strings being inserted into the target location. The example shows one scenario that fits the section title, but the preceding text needs to be clearer before we get to the example, and needs to clarify whether we are also talking about string-internals.

added to the agenda for 2023-03-30

r12a · 2023-03-29T15:45:15Z

index.html

 </ul>
 </aside>

-
-    <p>Applications often need to organize sets of information or content. Frequently this involves sorting the content so that users can find what they are looking for. Many data types, such as numbers or dates, are easily sorted by comparing the values. When it comes to textual information, however, the nature of character encodings brings some additional complexity.</p>
+    <p>Applications often need to organize sets of information or content. Frequently this involves sorting the content. Many data types, such as numbers or dates, are easily sorted by comparing the values. When it comes to textual information, however, the nature of character encodings and user expectations regarding "alphabetical" order brings some additional complexity.</p>


Numbers and dates are only easy to sort if you compare internal representations of the data.

Done with:

Suggested change

<p>Applications often need to organize sets of information or content. Frequently this involves sorting the content. Many data types, such as numbers or dates, are easily sorted by comparing the values. When it comes to textual information, however, the nature of character encodings and user expectations regarding "alphabetical" order brings some additional complexity.</p>

Many non-textual data types, such as numbers or dates, can be easily sorted using the internal data representation.

r12a · 2023-03-29T15:52:12Z

index.html

@@ -2828,6 +2948,12 @@ <h3>Specifying sort and search functionality</h3>
 	<p><a href="https://www.w3.org/TR/charmod/#sec-CollationUnits">Units of collation, C008</a>, in <cite>Character Model for the World Wide Web: Fundamentals</cite></p>
 	</details>
 	</div>
+-->
+
+	<aside class="warning" id="find-is-hard" title="String search is hard">


As a warning about string searching this seems a little oddly placed here. I think that similar difficulties apply to matching strings for sorting, but i think it would be useful to couch this warning in those terms.

This section is (and has historically been) called "specifying sort and search functionality". All of the prose in the section is about sorting. This is the only mention of "search"--I added it so that we wouldn't have a gap. I think maybe a subsection div above it would help. I also retitled as "under construction". See the new PR

r12a · 2023-03-29T15:53:29Z

local.css

@@ -431,3 +431,9 @@ table.whitespace caption {
  background-color: #04AA6D;
  color: white;
 }
+
+td.exampleChar {
+  font-size: 36pt;


Can we use a rem or, if necessary, an em unit rather than pt? If you really want to fix the size, perhaps use px rather than pt.

Done. Made it 300%

- Fix style to relative size - Reword guidance to implementers - Reword about sorting numbers and dates to say "internal representation" - Added a subsection for "searching" and put up the "under construction" banner

Add guidance for generating bidirectional text from substrings or for

de6fe7f

labels/descriptions. Addresses w3c#88

aphillips requested review from xfq and r12a January 27, 2023 18:39

aphillips self-assigned this Jan 27, 2023

Address w3c#83

7b24ade

Add guidance on Unicode code point order.

aphillips changed the title ~~Add guidance for generating bidirectional labels/descriptions~~ Address issues raised by recent reviews Jan 27, 2023

aphillips added 3 commits January 27, 2023 14:56

Address w3c#69

85fc0dc

Add a reference to 4647 when talking about BCP47 Also moved requirements above explanation per our standard (thanks @r12a)

Corrections and minor cleanup for the bidi example.

b73b570

Addresses w3c#14

d0c0799

Mention of using the language subtag registry instead of making your own list. Also some cleanup of the language tagging of the Arabic examples.

r12a requested changes Jan 30, 2023

View reviewed changes

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

aphillips added 2 commits January 30, 2023 08:42

Address @r12a's comment about language tags.

57e9fb5

This resulted in a bit of a rewrite. In addition, I added links to the "choosing a language tag" article, Richard's language subtag lookup tool, and the registry itself.

Address @r12a's comment about "isolating bidi controls"

3910539

aphillips requested a review from r12a January 30, 2023 16:46

aphillips added 5 commits January 31, 2023 09:55

Fixed bidi example by using markup.

7825d50

A couple of browsers don't seem to display the "fixed" bidi example correctly, at least when respec runs on it. Switching to markup, which is effective. Also rewrite the "notice how" paragraph to be (hopefully) clearer.

Address teleconference comments.

bb58dfa

Improve color contrast in example 3

54d1b8b

Further simplified bidi example.

1a2991b

- made the example text larger to make the color mixing clearer - simplified the description of the mixing problem

Additional work on sorting section.

cc2f39e

- Removed the charmod reqs altogether - Added a "warning" box about find being hard and linking our string-search doc

aphillips added 4 commits February 7, 2023 08:48

Fix description of BCP47 and of matching

e16100d

- Removed extreneous link to specdev? - Described matching in terms of ranges rather than subtags (4647 is not about matching subtags) - Cleaned up description of 5656, including mentioning the LSTR

Minor tweak to ascending code unit sort.

6da1a39

Made the example clear that the code units are in the UTF-16 character encoding.

Added text to description of the matching BP

2244c70

Address comments on #bidi_gen section from telecon of 2023-02-09

676694b

- Added a requirement not to concat strings! - Added a "seealso" suggested by @r12a - Added explanation of the Note example - Minor wording changes in the colorful example.

aphillips added 5 commits February 9, 2023 09:01

Move explanation under mustard.

a54cf2f

The example note should be preceeded by the explanation.

Ensure all parts of 639 are dealt with, minor edits

48fa92a

Further rephrasing based on @r12a's comments in telecon

a7a3897

Further edits to make reqs refer to string values.

f64e6d2

Address telecon 2023-02-16 comments

1caf816

- add exampleChar style (borrowed from our other specs) - renamed bidi_gen to strcat - clarified further the concat section - added links to uts10 and icu user guide for sorting - moved langtag matching to its own section and fixed label

xfq reviewed Feb 28, 2023

View reviewed changes

local.css Outdated Show resolved Hide resolved

Address @xfq's comment about vertical-align

07cbc60

aphillips requested a review from xfq February 28, 2023 15:31

Update bidi recommendation from telecon of 2023-03-09 [I18N-ACTION-1253]

6ce0aea

aphillips merged commit de5bee9 into w3c:gh-pages Mar 28, 2023
5 checks passed

r12a reviewed Mar 29, 2023

View reviewed changes

r12a mentioned this pull request Mar 29, 2023

Review comments on merged PR #91

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Address issues raised by recent reviews #89

Address issues raised by recent reviews #89

aphillips commented Jan 27, 2023 •

edited by pr-preview bot

xfq commented Feb 7, 2023

netlify bot commented Feb 9, 2023 •

edited

aphillips commented Mar 24, 2023

r12a Mar 29, 2023

aphillips Mar 29, 2023

r12a Mar 29, 2023

aphillips Mar 29, 2023

r12a Mar 29, 2023

aphillips Mar 29, 2023

r12a Mar 29, 2023

aphillips Mar 29, 2023

r12a Mar 29, 2023

aphillips Mar 29, 2023

r12a Mar 29, 2023

aphillips Mar 29, 2023


		<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Astrcat" target="_blank">See related review comments.</a></p>

		<div class="req" id="strcat_anti_pattern">

	<p>Applications often need to organize sets of information or content. Frequently this involves sorting the content. Many data types, such as numbers or dates, are easily sorted by comparing the values. When it comes to textual information, however, the nature of character encodings and user expectations regarding "alphabetical" order brings some additional complexity.</p>
	Many non-textual data types, such as numbers or dates, can be easily sorted using the internal data representation.

Address issues raised by recent reviews #89

Address issues raised by recent reviews #89

Conversation

aphillips commented Jan 27, 2023 • edited by pr-preview bot

xfq commented Feb 7, 2023

netlify bot commented Feb 9, 2023 • edited

✅ Deploy Preview for bp-i18n-specdev ready!

aphillips commented Mar 24, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aphillips commented Jan 27, 2023 •

edited by pr-preview bot

netlify bot commented Feb 9, 2023 •

edited