search

whatwg / html

HTML Standard
https://html.spec.whatwg.org/multipage/
Other
8.07k stars 2.65k forks source link

Add an example for bdo #4468

Open domenic opened 5 years ago

domenic commented 5 years ago

Porting from https://www.w3.org/Bugs/Public/show_bug.cgi?id=27475. I will quote comment 3 in full:

A quick search of the web turns up a number of people confused about what bdo does. The text in 4.5.26 and 4.5.27 are good enough for experts but do not provide the necessary information for users to understand how to use these special purpose elements. The links provided for bidi are to the UAX, which is not a particularly accessible reference.

I would suggest:

  1. Add a short example to 4.5.27 showing bdo being used to override text direction. The text says what it does, but "override text direction" has a very different meaning in this context than the casual reader would infer.

  2. Include a link to the I18N WG's authoring guidelines in the section on @dir (3.2.5.6 in 5.0). Cluttering up HTML with a complete reference on how to use bidi seems out of scope. Have an explicit pointer to @dir in bdo and bdi.

  3. Consider a revision to the example in the @dir section to match the guidelines (richard: thoughts?)

A later comment pointed out that https://www.w3.org/International/articles/inline-bidi-markup/ is nice and comprehensive and easy to comprehend. I still think adding at least one inline example is a good idea, but we should probably also point to that.

r12a commented 5 years ago

I seem to remember creating some text of this kind for the W3C HTML spec. I think this is the PR: https://github.com/w3c/html/pull/1267/files

r12a commented 5 years ago

Actually, this one seems to have got into HTML 5.3 https://github.com/w3c/html/pull/1334/files

See https://www.w3.org/TR/html53/textlevel-semantics.html#the-bdo-element