Skip to content

Commit

Permalink
Merge pull request #82 from daisy/add/dir
Browse files Browse the repository at this point in the history 
Add base direction pages for epub and html
  • Loading branch information
@mattgarrish
mattgarrish authored Mar 22, 2024
2 parents 6e4e39c + 3ada802 commit 3b31924
Show file tree
Hide file tree
Showing 7 changed files with 477 additions and 190 deletions.
12 changes: 12 additions & 0 deletions js/topics/en.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,12 @@ var topic_list = [
'href': 'language.html',
'title': 'Setting the Language',
'subtitle': 'Language identification in the package document and in content documents.'
},
{
'id': 'epub-dir',
'href': 'dir.html',
'title': 'Text Direction',
'subtitle': 'Specifying whether metadata text direction is left-to-right or right-to-left.'
}
]
},
Expand Down Expand Up @@ -413,6 +419,12 @@ var topic_list = [
'title': 'Sections',
'subtitle': 'The <code>section</code> element'
},
{
'id': 'html-dir',
'href': 'dir.html',
'title': 'Text Direction',
'subtitle': 'The <code>dir</code> attribute'
},
{
'id': 'html-svg',
'href': 'svg.html',
Expand Down
169 changes: 169 additions & 0 deletions publishing/docs/epub/dir.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Text Direction</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Guidelines for using the dir attribute in the EPUB package document">
<script>
var page_info = {
'category': ['EPUB'],
'appliesTo': ['EPUB3','EPUB2']
};
</script>
<script src="/js/init.js"></script>
</head>
<body>
<main>
<section id="summary">
<h3>Summary</h3>

<p>Set the base direction for metadata in the package document to ensure that it is rendered correctly.</p>
</section>

<section id="tech">
<h3>Techniques</h3>

<ul>
<li>Set the <code>dir</code> attribute on the <code>package</code> element [[WCAG-1.3.2]]</li>
<li>Set the <code>dir</code> attribute on <code>meta</code> elements whenever the base direction changes [[WCAG-1.3.2]]</li>
</ul>
</section>

<section id="ex">
<h3>Examples</h3>

<figure id="ex-01">
<figcaption>
<div class="label">Example 1 &#8212; Declaring the default base direction</div>
</figcaption>
<pre id="ex-01-src" class="prettyprint linenums"><code>&lt;package &#8230; xml:lang="he" dir="rtl">
&#8230;
&lt;/package></code></pre>
</figure>

<figure id="ex-02">
<figcaption>
<div class="label">Example 2 &#8212; Overriding the default base direction</div>
</figcaption>
<pre id="ex-02-src" class="prettyprint linenums"><code>&lt;package &#8230; xml:lang="ar" dir="rtl">
&lt;metadata>
&#8230;
&lt;dc:subject dir="ltr">POETRY / Middle Eastern&lt;/dc:subject>
&#8230;
&lt;/metadata>
&#8230;
&lt;/package></code></pre>
</figure>
</section>

<section id="faq">
<h3>Frequently Asked Questions</h3>

<dl>
<dt id="faq-001">Can I set the language of the text instead?</dt>
<dd>
<p>No. The language declaration does not affect the display directionality. <a
href="lang.html">Setting the language</a> is important for text-to-speech rendering.</p>
</dd>

<dt>Why do I need to declare a default left-to-right base direction in EPUB 3 but not HTML?</dt>
<dd>
<p>HTML defaults to left-to-right in the absence of a <code>dir</code> attribute.</p>

<p>EPUB 3 did not define the default directionality for package document metadata prior to EPUB
3.3, or require support for both left-to-right and right-to-left text ranges, so reading
systems often only support a single direction regardless of what is authored. Adding the
<code>dir</code> attribute to set the default text direction, and to indicate changes on
individual metadata elements <a href="#faq-002">may help with rendering</a> in
these older reading systems, but is not guaranteed. Regardless, it is recommended to set
the attribute going forward to ensure the correct base direction is applied.</p>

<p>If a base direction is not specified, reading systems are expected to default to using the
Unicode Bidi Algorithm to determine it. As there was initially no default base direction,
one could not be added when the requirements for the attribute were improved. Too many
publications were authored assuming their local base direction would be applied.</p>
</dd>

<dt id="faq-002">Why is the attribute labelled "under-implemented" in EPUB 3.3?</dt>
<dd>
<p>Most reading systems only support display of a single default text directionality, which
leads to text in another direction being incorrectly displayed to users. Features like this
typically have to be removed from W3C standards, but it is hoped the support situation will
improve moving forward because of the attribute's importance for internationalization.</p>

<p>W3C allowed existing EPUB features that did not meet the minimum support threshold to be
retained provided they offered essential functionality and were marked "under-implemented".
The label will be removed in the future when support increases.</p>
</dd>
</dl>
</section>

<section id="desc">
<h3>Explanation</h3>

<p>It is important to set the base direction for text in the package document to help ensure that it is
displayed properly by reading systems and read properly by assistive technologies.</p>

<div class="note" role="note" aria-labelledby="html-dir">
<p id="html-dir" class="label">Note</p>
<p>The <code>dir</code> attribute only affects text content in the <code>metadata</code> section;
it does not affect how EPUB content documents are rendered. For information about setting the
base direction in EPUB content documents, refer to the Knowledge Base's <a
href="../html/dir.html">HTML Text Direction</a> page.</p>
</div>

<p>There are three ways to set the base direction in the package document:</p>

<dl>
<dt>Globally</dt>
<dd>
<p>To set the base direction for all text content, set a <code>dir</code> attribute
on the root <code>package</code> element.</p>

<pre id="desc-01-src" class="prettyprint linenums"><code>&lt;package &#8230; xml:lang="he" dir="rtl"></code></pre>

<div class="note" role="note" aria-labelledby="epub2-support">
<p id="epub2-support" class="label">Note</p>
<p>EPUB 2 does not support the <code>dir</code> attribute in the package document,
so this technique does not apply.</p>
</div>
</dd>

<dt>Per-element</dt>
<dd>
<p>To override the default base direction on the <code>package</code> element, add a
<code>dir</code> attribute to each metadata element with a different base direction.</p>

<pre id="desc-02-src" class="prettyprint linenums"><code>&lt;dc:creator &#8230; xml:lang="ar" dir="rtl">&#8230;&lt;/dc:creator></code></pre>

<div class="note" role="note" aria-labelledby="epub2-support">
<p class="label">Note</p>
<p>EPUB 2 does not support the <code>dir</code> attribute in the package document,
so this technique does not apply.</p>
</div>
</dd>

<dt>Inline</dt>
<dd>
<p id="unicode-ctrl">It is not possible to identify inline changes in the base direction in the
package document. Although using markup to set the base direction is preferred, in these
cases you can use Unicode control characters to identify the changes. For an
introduction to the control characters and how to use them, refer to the W3C article <a
href="https://www.w3.org/International/questions/qa-bidi-unicode-controls">How to use
Unicode controls for bidi text</a>.</p>
</dd>
</dl>
</section>

<section id="refs">
<h3>Related Links</h3>

<ul>
<li>EPUB 3 &#8212; <a href="https://www.w3.org/TR/epub-33/#attrdef-dir">The <code>dir</code> attribute</a></li>
<li>W3C &#8212; <a href="https://www.w3.org/International/articles/inline-bidi-markup/uba-basics">Unicode Bidirectional Algorithm basics</a></li>
</ul>
</section>
</main>
</body>
</html>
143 changes: 143 additions & 0 deletions publishing/docs/html/dir.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Text Direction</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Guidelines for using the dir attribute in HTML">
<script>
var page_info = {
'category': ['HTML'],
'appliesTo': ['EPUB3','EPUB2','Audiobooks*']
};
</script>
<script src="/js/init.js"></script>
</head>
<body>
<main>
<section id="summary">
<h3>Summary</h3>

<p>Set the base direction for right-to-left text to ensure that it is rendered correctly.</p>
</section>

<section id="tech">
<h3>Techniques</h3>

<ul>
<li>Set the <code>dir</code> attribute on the <code>html</code> element [[WCAG-1.3.2]]</li>
<li>Set the <code>dir</code> attribute whenever the default direction changes [[WCAG-1.3.2]]</li>
</ul>
</section>

<section id="ex">
<h3>Examples</h3>

<figure id="ex-01">
<figcaption>
<div class="label">Example 1 &#8212; Declaring the default base direction</div>
</figcaption>
<pre id="ex-01-src" class="prettyprint linenums"><code>&lt;html xmlns="http://www.w3.org/1999/xhtml"
xml:lang="he"
lang="he"
dir="rtl"></code></pre>
</figure>
</section>

<section id="faq">
<h3>Frequently Asked Questions</h3>

<dl>
<dt id="faq-001">Do I need to declare the <code>dir</code> attribute for left-to-right documents?</dt>
<dd>
<p>No. HTML defaults to left-to-right directionality for text, so it is not necessary to set
the <code>dir</code> attribute for left-to-right documents. Only left-to-right text
embedded in a right-to-left document needs to be specified.</p>
</dd>

<dt id="faq-002">Can I just set the language of the text?</dt>
<dd>
<p>No. The language declaration does not affect the display directionality. <a
href="lang.html">Setting the language</a> is important for text-to-speech rendering.</p>
</dd>

<dt id="faq-003">Can I use CSS to set the direction instead?</dt>
<dd>
<p>No. CSS is not always available or respected in reading systems. Both the HTML and CSS
specifications recommend using markup to set the text direction.</p>
<p>Refer to <a href="https://www.w3.org/International/questions/qa-bidi-css-markup">CSS vs.
markup for bidi support</a> for more information.</p>
</dd>

<dt id="faq-004">What if I have forms that accept text input?</dt>
<dd>
<p>Set the <code>dir</code> attribute to <code>auto</code> on forms and inputs to allow the
reading system to determine the text direction at run-time.</p>
</dd>

<dt id="faq-005">When do I use the <code>bdi</code> and <code>bdo</code> elements?</dt>
<dd>
<p>It is not common to need these elements in publications.</p>

<p>The <code>bdi</code> element is used to insert user-generated text into a document. As you
cannot be sure the directionality of the text, it allows the reading system to examine the
content and adjust the base direction as needed.</p>

<p>The <code>bdo</code> element is used to override the base directionality of the text. It can
be used, for example, to force right-to-left text to render in left-to-right form.</p>
</dd>
</dl>
</section>

<section id="desc">
<h3>Explanation</h3>

<p>It is important to set the base text direction for right-to-left text in HTML and SVG documents
to ensure that it is displayed properly by reading systems and read properly by assistive
technologies.</p>

<p>The way that right-to-left text is encoded in the markup and stored in memory is not the same as
how it is displayed or read. If the correct base direction is not specified, the contents of a
page may be read out of order. This is particularly problematic when left-to-right text is embedded
in a right-to-left document. Weakly typed characters such as numbers and punctuation may be
rendered in the wrong place, for example, or list entries could be placed out of order.</p>

<p>To indicate that a document's base direction is right-to-left, simply add a <code>dir</code>
attribute to the root <code>html</code> or <code>svg</code> element:</p>

<pre id="desc-ex-01" class="prettyprint linenums"><code>&lt;html &#8230; dir="rtl">

&lt;svg &#8230; dir="rtl"></code></pre>

<p>If text with a left-to-right base direction is embedded in a right-to-left document, add a
<code>dir</code> attribute to its enclosing element. For example, if the document contained a quote
with a left-to-right base direction, you would add the <code>dir</code> attribute to the enclosing
<code>blockquote</code>:</p>

<pre id="desc-ex-02" class="prettyprint linenums"><code>&lt;blockquote dir="ltr">
&lt;p>It was the best of times, it was the worst of times, &#8230;&lt;/p>
&lt;/blockquote></code></pre>

<p>If the base direction changes within a run of text, add a <code>span</code> element with a
<code>dir</code> attribute:</p>

<pre id="desc-ex-03" class="prettyprint linenums"><code>&lt;p>
&lt;!-- right-to-left text --&gt;
&lt;span dir="ltr">Accessible EPUB 3&lt;/span>
&lt;!-- right-to-left text --&gt;
&lt;/p></code></pre>
</section>

<section id="refs">
<h3>Related Links</h3>

<ul>
<li>W3C &#8212; <a href="https://www.w3.org/International/questions/qa-html-dir">Structural markup and right-to-left text in HTML</a></li>
<li>W3C &#8212; <a href="https://www.w3.org/International/articles/inline-bidi-markup/">Inline markup and bidirectional text in HTML</a></li>
<li>W3C &#8212; <a href="https://www.w3.org/International/articles/inline-bidi-markup/uba-basics">Unicode Bidirectional Algorithm basics</a></li>
<li>W3C &#8212; <a href="https://www.w3.org/International/tutorials/bidi-xhtml/">Creating HTML Pages in Arabic, Hebrew and Other Right-to-left Scripts (tutorial)</a></li>
</ul>
</section>
</main>
</body>
</html>
4 changes: 2 additions & 2 deletions publishing/docs/new/2022.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<meta charset="utf-8">
<title>2022 Updates Archive</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Archive of updates to the Accessible Publishing Knowledge Base from 2021">
<meta name="description" content="Archive of updates to the Accessible Publishing Knowledge Base from 2022">
<script>
var page_info = {
'nav': false
Expand All @@ -13,7 +13,7 @@
</head>
<body>
<main>
<section id="new" aria-label="2021 List of Updates">
<section id="new" aria-label="2022 List of Updates">
<p>This page is an archive of changes to the knowledge base made in 2022. For the latest changes
to the site, refer to the site <a href="index.html">what's new</a> page.</p>

Expand Down
Loading

0 comments on commit 3b31924

Please sign in to comment.