<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE technique
  SYSTEM "../../xmlspec.dtd">
<technique id="H62">
   <short-name>Using the ruby element</short-name>
   <applicability>
      <p>XHTML 1.1 and HTML5</p>
   </applicability>
   <applies-to>
      <success-criterion idref="meaning-pronunciation" relationship="sufficient"/>
   </applies-to>
   <ua-issues>
      <ua-issue name="" version="">
         <p>Ruby markup includes the <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                 href="http://www.w3.org/TR/1998/WD-ruby-19981221/#a2-4">
								       <el>rp</el> element</loc> as a fallback mechanism for user agents that do not
              support XHTML 1.1 or HTML5. Although ruby markup is only defined in XHTML 1.1 and HTML5, IE 5.0 and later
              supports the <el>ruby</el>, <el>rt</el>, and <el>rp</el> elements even if they are
              used in HTML 4.01 or XHTML 1.0.</p>
      </ua-issue>
   </ua-issues>
   <description>
      <p>The objective of this technique is to use ruby annotation to provide information about
            the pronunciation and meaning of a run of text where meaning is determined by
            pronunciation.</p>
      <p>There are many languages in which a run of text may mean different things depending on
            how the text is pronounced. This is common in East Asian languages as well as Hebrew,
            Arabic, and other languages; it also occurs in English and other Western European
            languages. </p>
      <p>Ruby Annotation allows the author to annotate a "base text," providing a guide to
            pronunciation and, in some cases, a definition as well. Ruby is commonly used for text
            in Japanese and other East Asian languages. Ruby Annotation is defined as a module for
            XHTML 1.1 or HTML5. </p>
      <p>There are two types of Ruby markup: simple and complex. Simple Ruby markup applies to a
            run of text such as a complete word or phrase. This is known as the "base" text
            (<el>rb</el> element). The Ruby annotation that indicates how to pronounce the term (the
              <el>rt</el> element, or Ruby text) is shown in a smaller font. (The term "Ruby" is
            derived from a small font used for this purpose in printed texts.) The Ruby text is
            usually rendered above or immediately before the base text, that is, immediately above
            horizontal text or immediately to the right of vertical text. Sometimes Japanese uses
            Ruby to provide the meaning of text on the other side of the base text (visually) from
            the phonetic annotation. Simple Ruby markup also provides a "fallback" option for user
            agents that do not support Ruby markup (that is, user agents that do not support XHTML
            1.1 or HTML5). </p>
      <p>Complex Ruby markup makes it possible to divide the base text into smaller units, each
            of which may be associated with a separate Ruby annotation. Complex Ruby markup does not
            support the fallback option. </p>
      <p>Ruby annotation is uncommon in languages such as Hebrew, where Unicode fonts can
            include diacritical marks that convey pronunciation. It is also uncommon in English and
            European languages. </p>
      <p>Note: The primary reason for indicating pronunciation through Ruby or any other means
            is to make the content accessible to people with disabilities who could read and
            understand the language of the content if information about pronunciation were provided.
            It is not necessary to provide information about pronunciation for use by people who are
            not familiar with the language of the content. </p>
   </description>
   <examples>
      <eg-group>
         <head> Ruby markup providing pronunciation information for an initialism </head>
         <description>
            <p> This example uses Ruby annotation to give the pronunciation of the initialism
                (acronym) formed by the first letters of the words Web Content Accessibility
                Guidelines. The letters WCAG are the base (the rb element), and the pronunciation
                information is shown by the Ruby text (the rt element). The Ruby parenthesis element
                  <el>rp</el> is used for user agents that do not support Ruby annotations to
                indicate that the text in the <el>rt</el> element provides the pronunciation
                information. The pronunciation information is rendered in parentheses immediately
                following the base text. (User agents that support Ruby do not show the
                parentheses.) </p>
         </description>
         <code role="html401"><![CDATA[<p>When we talk about these guidelines, we often just call them
  <ruby>
    <rb>WCAG</rb>
    <rp>(</rp>
      <rt>Wuh-KAG</rt>
    <rp>)</rp>
  </ruby>.
</p>]]></code>
      </eg-group>
      <eg-group>
         <head> Ruby annotation for Japanese </head>
         <description>
            <p> The following is an example in Japanese. For Japanese, the Ruby is used to give
                the reading of Han characters(Kanji). the Ruby parenthesis element <el>rp</el> is
                used for user agents that do not support Ruby annotations to indicate that the text
                in the <el>rt</el> element provides the pronunciation information. The pronunciation
                information is rendered in parentheses immediately following the base text. (User
                agents that support Ruby do not show the parentheses.) </p>
         </description>
         <code role="html401"><![CDATA[<p>
  <ruby>
    <rb>慶應大学</rb>
    <rp>(</rp>
    <rt>けいおうだいがく</rt>
    <rp>)</rp>
  </ruby>
</p>    ]]></code>
      </eg-group>
   </examples>
   <resources>
      <see-also>
         <ulist>
            <item>
               <p>
									         <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                       href="http://www.w3.org/TR/ruby/">Ruby Annotation</loc>
								       </p>
            </item>
            <item>
               <p>
									         <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                       href="http://www.imsglobal.org/accessibility/accessiblevers/sec11.html">IMS Guidelines for
                    Topic-Specific Accessibility</loc>
								       </p>
            </item>
            <item>
               <p>
									         <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                       href="http://www.w3.org/TR/css3-ruby/">CSS 3 Ruby</loc>
								       </p>
            </item>
            <item>
               <p>
									         <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                       href="http://www.w3.org/International/techniques/markup#ruby">W3C I18N
                    Techniques: Markup and text, "Using Ruby"</loc>
								       </p>
            </item>
            <item>
               <p>
									         <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                       href="https://www.w3.org/TR/html5/text-level-semantics.html#the-ruby-element">HTML5 ruby element</loc>
								       </p>
            </item>
            <item>
               <p>
									         <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                       href="https://www.w3.org/TR/html/text-level-semantics.html#the-rb-element">HTMl5 rb element</loc>
								       </p>
            </item>
            <item>
               <p>
									         <loc xmlns:xlink="http://www.w3.org/1999/xlink"
                       href="https://www.w3.org/TR/html/text-level-semantics.html#the-rt-element">HTML5 rt element</loc>
								       </p>
            </item>
         </ulist>
      </see-also>
   </resources>
   <related-techniques>
      <relatedtech idref="G102"/>
   </related-techniques>
   <tests>
      <procedure>
         <p>For each run of text where a Ruby annotation is used to provide pronunciation
              information: </p>
         <olist>
            <item>
               <p>Check that a <el>rt</el> element contains pronunciation information for each
                  run of text defined by the <el>rb</el> element.</p>
            </item>
            <item>
               <p>If simple Ruby markup is used, check that the <el>rp</el> element is present
                  to indicate to user agents that do not support Ruby annotations that the text in
                  the rt element provides the pronunciation information. .</p>
            </item>
         </olist>
      </procedure>
      <expected-results>
         <ulist>
            <item>
               <p>Checks #1 and #2 are true.</p>
            </item>
         </ulist>
      </expected-results>
   </tests>
</technique>
