Re: Updated article: Unicode Bidirectional Algorithm basics

On 7/25/2016 1:09 PM, ishida@w3.org wrote:
> thanks for the suggestions, Asmus. Getting a bit late here,
Probably best if you give your text another pass, before we continue 
much, but here are a few more:
> so some quick answers below.
>
Don't miss the suggestions in a separate message on how to improve the 
flow of the opening paragraphs.

> On 25/07/2016 20:41, Asmus Freytag (c) wrote:
>> I think that an unstated goal of your text is to tell people "how to
>> manage" bidi texts in a very high-level way.
>
> Actually, teaching how to 'manage' bidi was deliberately not on my 
> agenda for this article.

"how to" is perhaps too strong. But you point out that there are things 
that need to be managed. And give some names for HMTL attributes and 
values (e.g. dir, ltr, etc.). Tha's not a detailed prescription, but a 
teaser. All I'm suggesting is that you parallel that in the discussion 
on the need for isoaltion.

Overall I think it is more useful to people to come away with some 
understanding of what *they* must do, even if the article is otherwise a 
high-level summary of the algorithm. The take-away is what makes that 
high-level info relevant.

> It was initially intended simply as an initial can-opener, to give 
> newcomers a sufficient peek at the miniumum amount of most basic 
> concepts involved in the UBA so that they could then understand the 
> other articles we have that do get into the actual managing aspects 
> (eg. the ones mentioned in the very last para). The latter are the 
> ones we really need people to read if they are going to be working 
> with bidi content.

Agreed. If they come away understanding the need to for them to learn 
how to do the detailed management, that's the best outcome.
>
> By the addition of the final section i have today extended the purpose 
> of the article so that i can also point to it for people developing 
> linked data, csv, annotations, and other such markup-resistent formats 
> and who have no clue (understandably) about why they should make it 
> possible to identify the base direction for the strings they are 
> passing around, and why the UBA isn't sufficient unto itself. (The key 
> message is stated in the first para: "...it is necessary to use 
> additional markup, metadata or special approaches to establish the 
> correct base direction for a range of text").

Sure, but move it to the place in the article and merge it with existing 
text of the two paragraphs "Again...." and "The markup lang...."
Might break out a section on "base direction and web specifications" or 
something.
>
>> To that end, I would move the trailing exclamation mark example up into
>> the discussion of base direction.
>
> In fact, that example is indeed used higher up in the section at
> http://w3c.github.io/i18n-drafts/articles/inline-bidi-markup/uba-basics.en#embeddedbd 
>

That example shows the issue with embedding. The Hebrew example shows 
the issue WITHOUT embeddings - I think it's a key point and the 
discussion of these examples wants to be merged and reorganized a bit.

In a way, you want to _show_ that base direction is a fundamental 
concept, rather than merely _telling _people that it is.

By the way, in the section you linked, the part of the sentence "on the 
bottom line, without a definition of the base direction" is really 
perplexing in its vagueness. What you mean is that you need to specify 
the base direction _for the inside of the quote_ and that the way to do 
that is via a <span> or other inline element. Being a bit more specific 
would help, I think.

>
>> I would then change the "Beyond the algorithm..." section to "Isolating
>> text passages" and make it explicitly about how isolation works by
>> mentioning how to achieve it in HTML in the same general way you
>> explained how to set base direction.
>
> See above. I actually only added isolation as an afterthought. The 
> main message of that section is that the UBA is not sufficient on its 
> own. Isolation is just one aspect of that issue.

But the article is better for it.

A basic understanding of the UBA means also having a high level 
understanding of what types of shortcomings must be managed. It's not 
enough to know that there's "at least one", but it should cover all the 
"biggies". Base direction is one, but isolation is definitely another.
>
>> After "numbers", I would have a (short) section on paired punctuation
>> with an example or two. Handling pairs, and nested pairs, is now a
>> function of the UBA.
>
> That's at 
> https://www.w3.org/International/articles/inline-bidi-markup/index#mirrored

The example in that article should no longer occur, if the paired bidi 
brackets part of the UBA is implemented.
(I tried to make it happen in an online CSS tutorial and could not get 
the parens to come out mismtached.

But mirroring is a really basic aspect of the UBA - so your "can-opener" 
needs to introduce the concept in some high-level form. I think of it as 
a not creating a surprise for the reader.
>
>> Finally, the very last paragraph points to other resources, it needs a
>> header of its own, unless you want to make it part of "Further Reading".
>
> Yes, that's probably a good idea. I'll look at it tomorrow.
>
> ri
>
>
>