Re: Updated article: Unicode Bidirectional Algorithm basics

On 7/25/2016 9:33 AM, ishida@w3.org wrote:
> PS: Please don't suggest additions that will complicate this more – 
> it's meant to be a simple, accessible article for newbies, to give 
> them the gist of things.  Other articles, such as those listed at the 
> bottom, carry greater detail. 

Richard,

I was going to comment on the fact that I find it too hard for newbies 
in some ways.
I think the issue is fixable by rewriting the first five paragraphs of 
the document to do a better job of setting the scene.


------------------------------------------------------------------------

[old]

It is important to understand from the outset that, in all major web 
browsers, the order of characters in memory (logical) is not the same as 
the order in which they are displayed (visual).

The set of rules applied by the browser to produce the correct order at 
the time of display are described by the Unicode Bidirectional 
Algorithm. We'll generally refer to this as 'the bidi algorithm'.

[new]

    ==> Words in some languages may be written from right to left, while
    numbers and other languages may be written from left to right.
    However, browsers and apps usually store all characters in the some
    order which, generally the order as they were typed (logical order),
    which is not the order in which they are displayed (visual order).

    To display them, they apply a  set of rules that will produce the
    correct order at the time of display, These rules are described by
    the Unicode Bidirectional Algorithm, or 'bidi algorithm' for short.

[keep]

The rest of this section introduces basic concepts of the bidi algorithm 
that will help you understand how to manage bidirectional inline text.


      Base direction (direction of the context)
      <http://w3c.github.io/i18n-drafts/articles/inline-bidi-markup/uba-basics.en#context>

[old]

The order in which text is displayed depends on the base direction 
assigned to the phrase, paragraph or block that contains it. The base 
direction is a fundamentally important concept. It establishes a 
directional context that the bidi algorithm refers to at various points 
to decide how to handle the text.

[new]

==> In some situations, especially where languages of a different 
directionality are mixed, the result can depend on the intended overall 
direction of the text. For example: is it an Arabic text that happens to 
contain words or phrases in French, or is it a French text that includes 
some Arabic.

[examples]

In resolving this and other ambiguous situations, the bidi algorithm 
uses a fundamental concept, the /base direction. /The base direction is 
assigned to the phrase, paragraph or block that contains the text to be 
displayed. It establishes a directional context that the bidi algorithm 
refers to at various points to decide how to handle the text

[keep]

In HTML the base direction is either set explicitly by the nearest 
parent element that uses the |dir| attribute, or, in the absence of any 
such attribute, is inherited from the default direction of the document, 
which is left-to-right.

------------------------------------------------------------------------

Now, I think that even after editing these five paragraphs, there's a 
flow issue in your document, made visible by the need of having a whole 
sentence in bold face.

I would fix that issue by moving the reworded Base Direction paragraph 
to the place where you have the highlighted sentence. (As you already 
have an example, ignore the suggested example, and reword the line about 
French/Arabic to instead refer to the example that you already have. The 
sentence about HTML would go before the "If you change..." paragraph)

------------------------------------------------------------------------

[new, if moved to past "Note that..happen]

==> In situations like this where languages of a different 
directionality are mixed, the result can depend on the intended overall 
direction of the text.

[old]

In the example above, which has an overall context (ie. base direction) 
of |ltr|, you would read 'bahrain', then 'مصر', then 'kuwait'.

==>

[new]In the example above, assuming the base direction (overall context) 
was |ltr|, you would read 'bahrain', then 'مصر', then 'kuwait'.

------------------------------------------------------------------------

I believe making these changes provides a better flow and avoids 
introducing a concept before it is needed, which is always difficult for 
a beginner.

A./