Implementing the Ruby Module (original) (raw)

Abstract

Ruby Annotation specification [Ruby] defines an abstract definition of ruby annotation markup. This Note describes sample module implementations of this abstract definition in several schemas —DTD,RELAX[RELAX],TREX[TREX] and the XML Schema [XMLSchema]. Familiarity with those schema languages as well as Ruby Annotation and theXHTMLModularization framework [XHTMLMOD] is assumed.

Status of This Document

This document is a Note made available by the World Wide Web Consortium (W3C) for your information only. Publication of this Note by W3C does not imply endorsement by W3C, including the Team and Membership, nor that the W3C has, is, or will be allocating any resources to the issues addressed by this Note.

This Note just describes the author's personal experiments. Implementations found in this document are informative only, and may contain errors. This is a draft document and may or may not be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use this Note as reference material or to cite this as other than "personal experiments".

While the author welcomes comments on this document, author does not guarantee a reply or any further action. Comments on this document should be sent to the author.

A list of current W3C technical reports and publications, including Working Drafts and Notes, can be found at http://www.w3.org/TR/.

Table of Contents

1. Introduction

Ruby Annotation specification [Ruby] defines an abstract definition of ruby annotation markup, and provides a RubyDTD Module for XHTMLwhich is used inXHTML 1.1 [XHTML11] as a module implementation. But DTD is just an implementation method, and other implementations are also possible.

In this Note, module implementations of the Ruby abstract definition in several schemas are explored —DTD,RELAX[RELAX],TREX[TREX] and the XML Schema [XMLSchema].

2. Abstract definition of ruby markup

The following is the abstract definition of ruby markup, found in section 2.1of Ruby Annotation [Ruby]. This abstract definition is consistent with the XHTMLModularization framework [XHTMLMOD]. Further definitions ofXHTMLabstract modules can be found in Modularization ofXHTML[XHTMLMOD].

Elements Attributes Minimal Content Model
ruby Common (rb, (rt | (rp, rt, rp)))
rbc Common rb+
rtc Common rt+
rb Common (PCDATA | Inline - ruby)*
rt Common, rbspan (CDATA) (PCDATA | Inline - ruby)*
rp Common PCDATA*

The maximal content model for the ruby element is as follows:

((rb, (rt | (rp, rt, rp))) | (rbc, rtc, rtc?))

3. Implementing the Ruby Module inDTD

3.1 RubyDTD Module

The following is an implementation of the Ruby Module inDTD, found inAppendix A ofRuby Annotation [Ruby]. This module is designed to be a conforming full ruby module implementation.

<![%Ruby.fallback;[ <![%Ruby.fallback.mandatory;[ <!ENTITY % Ruby.content.simple "( %rb.qname;, %rp.qname;, %rt.qname;, %rp.qname; )"

]]> <!ENTITY % Ruby.content.simple "( %rb.qname;, ( %rt.qname; | ( %rp.qname;, %rt.qname;, %rp.qname; ) ) )"

]]>

<![%Ruby.complex;[ <!ENTITY % Ruby.content.complex "| ( %rbc.qname;, %rtc.qname;, %rtc.qname;? )"

]]>

<![%ruby.element;[ <!ENTITY % ruby.content "( %Ruby.content.simple; %Ruby.content.complex; )"

]]>

<![%Ruby.complex;[

<![%rbc.element;[ <!ENTITY % rbc.content "(%rb.qname;)+"

]]>

<![%rtc.element;[ <!ENTITY % rtc.content "(%rt.qname;)+"

]]>

]]>

<![%rb.element;[

]]>

<![%rt.element;[

]]>

<![%Ruby.complex;[ <![%rt.attlist;[ <!ATTLIST %rt.qname; rbspan %Number.datatype; "1"

]]>

]]>

<![%Ruby.fallback;[ <![%rp.element;[ <!ENTITY % rp.content "( #PCDATA )"

]]>

]]>

<![%Ruby.common.attlists;[

<![%Ruby.common.attlist;[ <!ATTLIST %ruby.qname; %Ruby.common.attrib;

]]>

<![%Ruby.complex;[

<![%Rbc.common.attlist;[ <!ATTLIST %rbc.qname; %Ruby.common.attrib;

]]>

<![%Rtc.common.attlist;[ <!ATTLIST %rtc.qname; %Ruby.common.attrib;

]]>

]]>

<![%Rb.common.attlist;[ <!ATTLIST %rb.qname; %Ruby.common.attrib;

]]>

<![%Rt.common.attlist;[ <!ATTLIST %rt.qname; %Ruby.common.attrib;

]]>

<![%Ruby.fallback;[

<![%Rp.common.attlist;[ <!ATTLIST %rp.qname; %Ruby.common.attrib;

]]>

]]> ]]>

3.2 Integrating the Ruby DTD Module into markup languages

3.2.1 How to integrate the Ruby DTDModule into markup languages

Unlike its structural complexity, integrating this RubyDTD Module into markup languages is fairly easy. There are four important parameter entities in this Ruby Module that markup language designers should care, which are defined in the Ruby Module as follows:

And there are also two optional non-standard parameter entities:

The function of the above parameter entities is as follows:

%Ruby.complex;

This paremeter entity provides an option whether to include complex ruby markup or not. This is set to 'INCLUDE' by default. By setting it to 'IGNORE', markup language designers can exclude the complex ruby markup. In this case, the rbspan attribute of the rtelement is not included, as it's useless for simple ruby.

%NoRuby.content;

This paremeter entity provides an easy way to redefine the content models of the rb and the rt elements. It's defined as '( #PCDATA )' by default. Basically, these elements will have the same content model, which is intended to allow other inline-level elements of its host markup language, but it should not include ruby descendent elements. By using this paremeter entity, markup language designers can redefine those content models at once, without redefining them separately.

%Ruby.common.attlists;

This paremeter entity provides an easy way to define common attributes for ruby elements. This is set to 'IGNORE' by default. Basically, ruby elements are intended to have common attributes of its host markup language. By setting this paremeter entity to 'INCLUDE', markup language designers can define common attributes for ruby elements at once using the parameter entity%Ruby.common.attrib;, without defining them separately.

%Ruby.common.attrib;

This paremeter entity defines common attributes for ruby elements, which is empty by default. In the case ofXHTML 1.1 [XHTML11], it is defined as follows:

%Ruby.fallback;

This optional paremeter entity provides an option whether to includerp fallback mechanism or not. This is set to 'INCLUDE' by default. By setting it to 'IGNORE' (e.g. in internal subset), authors can exclude this fallback mechanism.

Note that setting it to 'IGNORE' further restricts the minimal content model of the ruby element, thus makes that usage nonconformant to [Ruby], though, the resultant document still conforms to [Ruby]. This option is provided only for authors' convenience should they really wish to exclude rp fallback from their contents. Markup language designers should not alter this paremeter entity to define their markup languages.

%Ruby.fallback.mandatory;

This optional paremeter entity provides an option whether to enforcerp fallback mechanism or not. This is set to 'IGNORE' by default. By setting it to 'INCLUDE' (e.g. in internal subset), authors can enforce this fallback mechanism.

This option is provided only for authors' convenience should they really wish to enforce rp fallback in their contents. Markup language designers should not alter this paremeter entity to define their markup languages.

In addition to redefining the above parameter entities (if necessary), markup language designers have to add the ruby element to some elements' content models where inline-level elements may appear.

In any case, markup language designers would have to redefine%NoRuby.content;, %Ruby.common.attlists;and %Ruby.common.attrib; as appropriate, when integrating the Ruby Module into their markup languages. There's no magic here. But %Ruby.complex; (and %Ruby.fallback;) can be used to choose the preferred structure of ruby markup. The following examples illustrate how markup language designers and authors can choose the preferred structure by just modifying%Ruby.complex; (and %Ruby.fallback;).

Case 1: using the full ruby markup

When markup language designers want to use the full ruby markup, namely, with support for both simple ruby and complex ruby, they don't have to redefine %Ruby.complex;.

In this case, the structure of ruby markup is the same as the one used inXHTML 1.1a [XHTML11].

Case 2: using the simple ruby markup

When markup language designers want to use the the simple ruby markup, namely, without support for complex ruby, they can redefine%Ruby.complex; as follows:

In this case, the structure of ruby markup is the same as the one currently supported in Microsoft Internet Explorer 5.0 and later.

Case 3: using the full ruby markup, without fallback

Note. Though the resultant document still conforms to [Ruby], using this structure for defining a markup language is nonconforming to [Ruby].

When authors want to use the full ruby markup, namely with support for both simple ruby and complex ruby but don't want to userp fallback mechanism, they can redefine%Ruby.fallback; (e.g. in internal subset) as follows:

In this case, the structure of ruby markup is the same as the one developed for JISX 4052:2000 "Exchange format for Japanese documents with composition markup" [JISX4052].

Case 4: using the simple ruby markup, without fallback

Note. Though the resultant document still conforms to [Ruby], using this structure for defining a markup language is nonconforming to [Ruby].

When authors want to use the the simple ruby markup, namely without support for complex ruby and rp fallback mechanism, they can redefine %Ruby.complex; and %Ruby.fallback;(e.g. in internal subset) as follows:

In this case, the structure of ruby markup is the same as the one used in the JepaX format [JepaX].

After redefining these parameter entities, the Ruby Module may be integrated into markup languages. The following is an excerpt from the XHTML 1.1 [XHTML11]DTD driver.

<![%xhtml-ruby.module;[ %xhtml-ruby.mod;]]>

3.2.2 Example of integrating the Ruby DTDModule (1): XML SpecificationDTD

As shown above, the RubyDTD Module can be readily integrated into [XHTML11]. It's natual that it works, as the Ruby Module is primarily designed for that purpose.

But it also works with otherDTDs as well, so long as those are properly parameterized. The following is an exampleDTD driver to integrate the Ruby Module into the XML SpecificationDTD[XMLspec]. Thanks to its fine parameterization, the XML SpecificationDTD can easily integrate the Ruby Module with minimum effort. Of course, by controlling %Ruby.complex;, markup language designers can choose preferred structure.

Note. At the time of writing, the latest version of [XMLspec] is Version 2.1, but here Version 2.0 is used because a rewrite inRELAXis based on Version 2.0, so it is more consistent to use Version 2.0 for comparison purpose.

%xmlspec;

%xhtml-ruby.mod;

Note. In the above example, %NoRuby.content; is NOT redefined so the content model of the rb and the rtelements is '( #PCDATA )'.

Note that since the [XMLspec] is not designed to be namespace-aware, the above example doesn't deal with namespace issues. An example of namespace-aware integration is shown in section 3.2.3.

3.2.3 Example of integrating the Ruby DTDModule(2): SVG DTD

SVG(Scalable Vector Graphics) [SVG] is a language for describing two-dimensional vector and mixed vector/raster graphics in XML, with a defined namespace. The Ruby Module is part of theXHTMLnamespace, so adding ruby annotation markup toSVGconcerns mixing multiple markup vocabularies from different namespaces.

Modularization of XHTML [XHTMLMOD] provides a way to deal with namespaces, using theXHTML Qname (Qualified Name) Module. The following DTDdriver defines a hybrid document type which allows ruby annotation markup inside the desc, title, text,tspan, textPath and a elements in SVG, in a namespace-aware way. See [XHTMLMOD] for more details.

%xhtml-qname.mod;

%SVG;

%xhtml-ruby.mod;

Note. In the above example, the id and xml:langattributes are defined for ruby elements.%NoRuby.content; is NOT redefined so the content model of the rb and the rtelements is '( #PCDATA )'.

By using this DTDdriver, by default, ruby elements can be used like this:

...

If prefixing ruby elements is preferred, one can set%NS.prefixed; parameter entity to "INCLUDE", and can define arbitrary namespace prefix with %XHTML.prefix;parameter entity inside the internal subset of an instance.An example instance would be something like this:

]> Example SVG with ruby annotation

Example of ruby: <xhtml:ruby xmlns:xhtml="" title="undefined" rel="noopener noreferrer">http://www.w3.org/1999/xhtml"> xhtml:rbAAxhtml:rtaaa

4. Implementing the Ruby Module inRELAX

RELAXCore [RELAX] allows definingRELAX grammars as XML instances, and provides the same datatypes as the XML Schema Part 2 [XMLSchema] (with a few extensions —none and emptyString). In addition, it allows to describe constraints not expressible by other schemas likeDTD andXML Schema, e.g. the rbspan attribute of the rt element should not be allowed in simple ruby markup. Each RELAXCore module defines a single namespace grammar.

RELAXNamespace [RELAX-NS] allows mixing grammars from different namespaces. RELAX Namespace divides mixed-namespace instance into "islands", where each island consists of a single namespace, and each island can be validated by the RELAXCore processor. A module defining a single namespace may use schema languages other than RELAX Core, such asTREX[TREX].

4.1 RubyRELAXModules

In section 4.1.1, an implementation of the Ruby Module in RELAXis defined. This module defines all the necessary grammars for the Ruby Module, and allows simple ruby markup by default. In section 4.1.2, another RELAXmodule that allows full ruby markup is defined, by including and extending the Ruby RELAXModule defined in section 4.1.1.

4.1.1 Ruby RELAX Module

Note. In the following grammar, "Ruby.common.attrib" is assumed to be defined in other module.

Download thisRELAXgrammar

XHTML Ruby Module in RELAX 
    Ruby Elements

      ruby, rbc, rtc, rb, rt, rp

  This module defines grammars to support ruby annotation markup.
  This module is based on the W3C Ruby Annotation Specification:

    http://www.w3.org/TR/ruby
</documentation>
hedgeRules for the content model of the ruby element 
<hedgeRule label="Ruby.content.simple">
  <annotation>
    <documentation>Content model of simple ruby</documentation>
  </annotation>

  <sequence>
    <ref label="rb"/>
    <choice>
      <ref label="rt-simple"/>
      <sequence>
        <ref label="rp"/>
        <ref label="rt-simple"/>
        <ref label="rp"/>
      </sequence>
    </choice>
  </sequence>
</hedgeRule>

<hedgeRule label="Ruby.content.complex">
  <annotation>
    <documentation>Content model of complex ruby</documentation>
  </annotation>

  <sequence>
    <ref label="rbc"/>
    <ref label="rtc"/>
    <ref label="rtc" occurs="?"/>
  </sequence>
</hedgeRule>

<hedgeRule label="Ruby.content">
  <annotation>
    <documentation>Simple ruby is used by default</documentation>
  </annotation>

  <hedgeRef label="Ruby.content.simple"/>
</hedgeRule>
ruby element 
<elementRule role="ruby">
  <hedgeRef label="Ruby.content"/>
</elementRule>

<tag name="ruby">
  <ref role="Ruby.common.attrib"/>
</tag>
rbc (ruby base component) element 
<elementRule role="rbc">
  <ref label="rb" occurs="+"/>
</elementRule>

<tag name="rbc">
  <ref role="Ruby.common.attrib"/>
</tag>
rtc (ruby text component) element 
<elementRule role="rtc">
  <ref label="rt-complex" occurs="+"/>
</elementRule>

<tag name="rtc">
  <ref role="Ruby.common.attrib"/>
</tag>
rb (ruby base) element 
<elementRule role="rb">
  <mixed>
    <hedgeRef label="NoRuby.content" occurs="*"/>
  </mixed>
</elementRule>

<tag name="rb">
  <ref role="Ruby.common.attrib"/>
</tag>
rt (ruby text) element 
<elementRule label="rt-simple">
  <annotation>
    <documentation>
      elementRule for simple ruby

      rbspan attribute is not allowed in simple ruby
    </documentation>
  </annotation>

  <tag name="rt">
    <ref role="Ruby.common.attrib"/>
    <attribute name="rbspan" type="none"/>
  </tag>

  <mixed>
    <hedgeRef label="NoRuby.content" occurs="*"/>
  </mixed>
</elementRule>

<elementRule label="rt-complex">
  <annotation>
    <documentation>
      elementRule for complex ruby
    </documentation>
  </annotation>

  <tag name="rt">
    <ref role="Ruby.common.attrib"/>
    <attribute name="rbspan" type="positiveInteger"/>
  </tag>

  <mixed>
    <hedgeRef label="NoRuby.content" occurs="*"/>
  </mixed>
</elementRule>
rp (ruby parenthesis) element 
<elementRule role="rp" type="string"/>

<tag name="rp">
  <ref role="Ruby.common.attrib"/>
</tag>
Ruby Common Attributes 
    Ruby elements are intended to have common attributes of its
    parent markup language. An attPool "Ruby.common.attrib" MUST
    be defined to integrate this module.
  </documentation>
</annotation>
Content models of the rb and the rt elements are intended to allow other inline-level elements of its parent markup language, but it should not include ruby descendent elements. The hedgeRule 'NoRuby.content' can be used to redefine those content models. It's defined as 'empty' by default. 
<empty/>

4.1.2 RubyRELAXModule for full ruby markup

Download this RELAXgrammar

XHTML Ruby Module in RELAX for full ruby markup Allow complex ruby markup in addition to simple ruby markup 
<hedgeRef label="Ruby.content.complex"/>

4.2 Integrating the Ruby RELAXModule into markup languages

4.2.1 How to integrate the Ruby RELAXModule into markup languages

In RELAX, multiple hedgeRules may share the same label. A hedgeRef element referencing to some labels will be expanded by the following procedure:

  1. Locate all hedgeRules for this label.
  2. Group hedge models of these hedgeRules with a choice element.
  3. Copy the occurs attribute of the hedgeRefto this choice element.
  4. Replace the hedgeRef with this choice element.

This feature may be used to extend the content model. An example of using this feature is the Ruby RELAX Module shown insection 4.1.2, which extends the hedgeRule"Ruby.content" to allow complex ruby markup. Namely, the following hedgeRule:

and the following hedgeRule:

share the same label, so these hedgeRules will be merged as:

and will be expanded to:

which allows both the simple and the full ruby markup.

Similarly, the following hedgeRule is used to define the content models of the rb and the rtelements.

This hedgeRule is referred inside elementRules for rb and rt as:

so by default the content models of the rb and the rt elements are effectively the same as:

which approximates '( #PCDATA )' inDTD. When integrating the Ruby RELAX Module, another hedgeRule(s) which share the same label may be defined to allow inline-level elements inside the rb and the rt elements. For example, if em andstrong are allowed as inline-level elements, the following hedgeRule could be defined:

This hedgeRule will be merged with the abovehedgeRule and will be expanded to:

so the content models of the rb and the rtelements will effectively become:

The hedgeRule "NoRuby.content" MUST not include the ruby element.

Note. RELAXhas ability to disallow the ruby element to appear as a direct or indirect subordinate of the rb or the rt elements. However, while it's possible, writing a RELAX grammar to prohibit indirect nesting of ruby is not quite easy.

In order to integrate the Ruby RELAX Module, an attPool "Ruby.common.attrib" MUST also be defined. This attPool will define common attributes for ruby-related elements. For example, if common attributes are defined in an attPool "Common.attrib", "Ruby.common.attrib" could be defined like this:

If there's no common attribute, "Ruby.common.attrib" may be empty:

4.2.2 Example of integrating the RubyRELAXModule: XML SpecificationDTD rewritten inRELAX

Like section 3.2.2, the [XMLspec]rewritten in RELAXby Murata Makoto, is used as an example. In the rewritten [XMLspec]RELAX grammar, the following hedgeRule is defined:

In order to add ruby, new hedgeRule with the same label can be defined like this:

Thus, the following hedgeRule:

will be expanded to:

which is effectively the same as:

So integrating the RubyRELAX Module into the [XMLspec] rewritten inRELAXwill be done like this:

Note that strictly speaking, [XMLspec] and [Ruby] are in different namespace ([XMLspec] doesn't belong to any namespace, while [Ruby] belongs to the XHTML namespace), so the above example will not work. The above example is only to illustrate the basic idea, in comparison with the DTD-based integration.

To mix vocabularies from different namespaces, RELAX Namespace [RELAX-NS] can be used. In order to allow the ruby element in [XMLspec] using RELAX Namespace, the namespace attribute can be aded to the refelement:

So by using RELAX Namespace, the above example could be rewritten like this:

  <include moduleLocation="xmlspec-v20.rxm"/>

  <hedgeRule label="local.annot.class">
    <ref label="ruby" namespace="http://www.w3.org/1999/xhtml"/>
  </hedgeRule>

</module>
  <interface>
    <export label="ruby"/>
  </interface>

  <include moduleLocation="xhtml-ruby-1.rxm"/>

  <attPool role="Ruby.common.attrib"/>

</module>

Note. Common attributes for ruby-related elements are not defined in the above example.

Ruby RELAX Module for full ruby markup can also be integrated just like the same way.

5. Implementing the Ruby Module inTREX

Like RELAX,TREX[TREX] allows defining TREX patterns asXML instances, and a TREXpattern specifies a pattern for the structure and content of anXML document. Among other things, TREX makes it easiter to describe exclusion-like constraint, such as disallowing the nesting of the ruby element.

TREXdoes not have built-in datatypes, and may be used with the datatyping vocabularies such as XMLSchema Part 2 [XMLSchema]. Note that the following example uses [XMLSchema] for datatyping, but TREX implementations may differ in the datatyping vocabularies they support, e.g. an implementation might support older version of [XMLSchema] identified by the namespaceURI http://www.w3.org/2000/10/XMLSchema, or might support another datatyping vocabulary, or might not support datatyping at all.

5.1 RubyTREXModules

In section 5.1.1, an implementation of the Ruby TREX Module is defined. This module defines all the necessary patterns for the Ruby Module, and allows simple ruby markup by default. In section 5.1.2, another Ruby TREX Module that allows full ruby markup is defined, by including and extending the Ruby TREX Module defined insection 5.1.1.

Note that the following modules include annotations using facilities from XML Schema, but elements and attributes from other than the TREX namespace will be ignored, so you can use arbitrary elements and attributes from a separate namespace for annotations.

5.1.1 Ruby TREX Module

Download this TREXpattern

xsd:annotation xsd:documentation Ruby TREX Module Revision: Id:xhtml−ruby−1.trex,v1.12001/05/2922:13:14mimasaExpId: xhtml-ruby-1.trex,v 1.1 2001/05/29 22:13:14 mimasa Exp Id:xhtml−ruby−1.trex,v1.12001/05/2922:13:14mimasaExp

  Ruby Elements

    ruby, rbc, rtc, rb, rt, rp

  This module defines patterns to support ruby annotation markup.
  This module is based on the W3C Ruby Annotation Specification:

    http://www.w3.org/TR/ruby
</xsd:documentation>

xsd:annotation xsd:documentationruby element

xsd:annotation xsd:documentationrbc (ruby base component) element

xsd:annotation xsd:documentationrtc (ruby text component) element

xsd:annotation xsd:documentationrb (ruby base) element

xsd:annotation xsd:documentationrt (ruby text) element

xsd:annotation xsd:documentationrp (ruby parenthesis) element

xsd:annotation xsd:documentation Fragments for the content model of the ruby element

Support simple ruby by default 
<choice>
  <ref name="Ruby.content.simple"/>
  <ref name="Ruby.content.simple.fallback"/>
</choice>
Ruby Common Attributes 
    Content models of the rb and the rt elements are intended to
    allow other inline-level elements of its parent markup language,
    but it should not include ruby descendent elements. The following
    pattern NoRuby.content can be used to redefine those content models
    with minimum effort.
  </xsd:documentation>
</xsd:annotation>

<ref name="Common.attrib"/>
Content models of the rb and the rt elements are intended to allow other inline-level elements of its parent markup language, but it should not include ruby descendent elements. This pattern implements these constraints. "Inline.model" has to be defined in other module. 
<concur>
  <ref name="Inline.model"/>
  <ref name="Ruby.concur"/>
</concur>
Prohibit nesting of ruby 
<grammar>
  <start name="not.excluded">
    <zeroOrMore>
      <choice>
        <element>
          <not>
            <name>ruby</name>
          </not>
          <zeroOrMore>
            <attribute>
              <anyName/>
            </attribute>
          </zeroOrMore>
          <ref name="not.excluded"/>
        </element>
        <anyString/>
      </choice>
    </zeroOrMore>
  </start>
</grammar>

xsd:annotation xsd:documentation Add ruby into inline elements class; "Inline.class" has to be defined in other module.

5.1.2 RubyTREX Module for full ruby markup

Download this TREXpattern

xsd:annotation xsd:documentation Ruby TREX Module for full ruby markup Revision: Id:xhtml−full−ruby−1.trex,v1.12001/05/2922:13:45mimasaExpId: xhtml-full-ruby-1.trex,v 1.1 2001/05/29 22:13:45 mimasa Exp Id:xhtml−full−ruby−1.trex,v1.12001/05/2922:13:45mimasaExp

Add complex ruby support 
 <ref name="Ruby.content.complex"/>
Add the rbspan attribute as one of attributes of the rt element 
<ref name="rbspan.attrib"/>

5.2 Integrating the Ruby TREXModule into markup languages

5.2.1 How to integrate the Ruby TREX Module into markup languages

The modules defined in section 5.1.1 andsection 5.1.2 are primarily designed to be used with other XHTML modules, to build XHTMLFamily document types. UnlikeDTD-based modularization, the modules take care of redefining the content models appropriately, so you don't have to define the content model for a collection of modules. Such an example is shown in section 5.2.2.

When you integrate the Ruby Module into other markup languages, the patterns "Core.attrib", "Inline.model" and "Inline.class" have to be defined in other module(s). "Core.attrib" would include patterns of commons attributes that may be used on ruby-related elements. Such attributes may be taken from a module implementing the XHTML Attribute Collections.

"Inline.model" would be defined like the following, where "Inline.class" defines a list of inline-level elements.

This corresponds to '( PCDATA | Inline )*' in the abstract definition. The "Ruby.concur" pattern defines a pattern to exclude a ruby at any depth, so the following pattern "NoRuby.content" corresponds to '( PCDATA | Inline -ruby )*' in the abstract definition.

Note that in TREX, order of including modules is not irrelevant. For example, if two duplicated definitions come from different modules, the latter definition can be combined with the former, and if the latter specifies the combine attribute with the valuereplace, then the former definition will be replaced by the latter. This is different from DTD, where the former wins, or RELAX, where order of inclusion is irrelevant.

5.2.2 Example of integrating the Ruby TREXa Module: TREX pattern for XHTML Basic

The following is an example of adding simple ruby markup intoTREX pattern for XHTML Basic[XHTMLBasic], written by James Clark. If you would like to use full ruby markup, just replacexhtml-ruby-1.trex with xhtml-full-ruby-1.trex.

6. Implementing the Ruby Module inXML Schema

Note. This experiment is based on an XML Schema module implementation of Ruby in "Modularization of XHTML inXML Schema" [XHTMLMODSchema], although the experiment itself predated the publication of [XHTMLMODSchema]. Sample XML Schema module implementations shown below are NOT intended to supersede that one, rather to explore how simple and complex ruby module implementations should be, so that it will be properly modularized in the future. It is expected that future draft of "Modularization of XHTML inXML Schema" will address this issue.

6.1 RubyXML Schema Modules

In section 6.1.1, an XML Schema module implementation that supports full ruby markup is defined. In section 6.1.2, another XML Schema module that supports simple ruby markup is defined.

6.1.1 RubyXML Schema Module

Download this XML Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.w3.org/1999/xhtml" xmlns="http://www.w3.org/1999/xhtml" version="1.1">

xsd:annotation xsd:documentation /**

/** *

/**

6.1.2 Simple Ruby XML Schema Module

Download this XML Schema

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.w3.org/1999/xhtml" xmlns="http://www.w3.org/1999/xhtml" version="1.1">

xsd:annotation xsd:documentation /**

/** *

/**

6.2 Integrating the Ruby XML Schema Module into markup languages

The way to integrate XML Schema Modules into markup languages will be explained in "Modularization of XHTML inXML Schema" [XHTMLMODSchema].

7. SampleCSS2 /XSLstyle sheets for Ruby

Although the primary purpose of this Note is to explore module implementaitions of ruby, it is of course preferable that instances that use ruby could be rendered in some way. This section briefly explores how ruby could be rendered using style sheets.

7.1 SampleCSS2style sheets for Ruby

The following is a sampleCSS2style sheet fragment for ruby.

ruby, rbc, rtc, rb, rt { display: inline } rp { display: none } ruby > rt:before { content: "(" } ruby rtc:before { content: "(" } ruby rtc + rtc:before { content: "; " } ruby:after { content: ")" }

An example rendering of an XHTML 1.1 documentby Mozilla 0.9, withstyle sheets that include the above fragments, is shown in Figure 1.

example ruby rendering in Mozilla

Figure 1: Example ruby rendering in Mozilla

Note. The above example XHTML 1.1 document is served as "text/xml", and rendering is controlled byCSS. SomeXML user agents might not be able to render this document.

Note that as shown in Figure 1, the above style sheets render ruby text as inline annotation, rather than interlinear annotation (i.e. ruby annotation). Formatting properties for styling ruby are under development, see "CSS3Module: Ruby" [CSS3-Ruby] for more details. Ruby may also be used in vertical layout, see "CSS3 module: text" [CSS3-Text] (work in progress) for relevant properties.

Although the rendering of ruby should be controlled by style sheets, when appropriate style information is not provided, user agents could still try to render ruby in some meaningful way. The following examples illustrate how a user agent could support ruby.

W3C'sAmaya browser/editor implements ruby as part of XHTML 1.1 support.Figure 2 is an example rendering ofsample XHTML 1.1 documentin its main view, and Figure 3 is another example rendering of the same document in alternate view. It is of course possible to apply style properties like "color" to ruby-related elements.

example ruby rendering in Amaya, main view

Figure 2: Example ruby rendering in Amaya (main view)

example ruby rendering in Amaya, alternate view

Figure 3: Example ruby rendering in Amaya (alternate view)

Note. At the time of this publication, ruby support is only available from the CVS base. It will be included in the next release.

7.2 SampleXSLstyle sheets for Ruby

XSL 1.0 [XSL] doesn't provide formatting objects for ruby yet. However, some work-around is possible with inline-container. The following is a sample XSL style sheet fragment for ruby.

<xsl:template match="ruby"> <fo:inline-container text-indent="0mm" last-line-end-indent="0mm" start-indent="0mm" end-indent="0mm"> <fo:block font-size="0.5em" text-align="center" line-height="1.3" space-before.conditionality="retain" wrap-option="no-wrap"> <xsl:apply-templates select="rt|rtc[1]"/> <fo:block text-align="center" line-height="1" wrap-option="no-wrap"> <xsl:apply-templates select="rb|rbc"/> <fo:block font-size="0.5em" text-align="center" line-height="1.3" space-before.conditionality="retain" wrap-option="no-wrap"> <xsl:apply-templates select="rtc[2]"/>

An example rendering by Antenna House'sXSLFormatter is shown in Figure 4.

example ruby rendering in XSL Formatter

Figure 4: Example ruby rendering inXSL Formatter

Note that the above style sheets don't handle baseline adjustment.

References

[CSS3-Ruby]

"CSS3 Module: Ruby",W3C Working Draft

M. Suignard, ed., 16 February 2001.
Available at: http://www.w3.org/TR/2001/WD-css3-ruby-20010216
The latest version is available at: http://www.w3.org/TR/css3-ruby

[CSS3-Text]

"CSS3 module: text",W3C Working Draft

M. Suignard, C. Lilley, eds., 17 May 2001.
Available at: http://www.w3.org/TR/2001/WD-css3-text-20010517
The latest version is available at: http://www.w3.org/TR/css3-text

[JepaX]

"JepaX —JEPAelectronic publishing exchange format" (in Japanese)

Japanese Electronic Publishing Association,work in progress
Available at: http://x.jepa.or.jp/jepax/

[JISX4052]

"Exchange format for Japanese documents with composition markup" (in Japanese)

JISX 4052:2000, Japanese Standards Association

[RELAX]

"Regular Language Description for XML:RELAXCore" (in Japanese; English translation is also available)

JIS TR X 0029:2000, Japanese Standards Association
"RELAX Core" was submitted to ISO as "ISO/IEC DTR 22250-1:2000, Document Description and Processing Languages -- Regular Language Description forXML (RELAX) -- Part 1:RELAXCore" in October 2000, and has been approved as an ISO/IEC TR in May 2001 (to be published).
Information aboutRELAXcan be available at:http://www.xml.gr.jp/relax/

[RELAX-NS]

"Regular Language Description for XML(RELAX) Namespace" (in Japanese)

JIS TR X 0044:2001, Japanese Standards Association

[Ruby]

"Ruby Annotation",W3C Recommendation

M. Sawicki, M. Suignard, M. Ishikawa, M. Dürst, T. Texin,eds., 31 May 2001.
Available at: http://www.w3.org/TR/2001/REC-ruby-20010531
The latest version is available at: http://www.w3.org/TR/ruby

[SVG]

"Scalable Vector Graphics (SVG) 1.0 Specification",W3CCandidate Recommendation

J. Ferraiolo, ed., work in progress
Available at: http://www.w3.org/TR/2000/CR-SVG-20001102
The latest version is available at: http://www.w3.org/TR/SVG

[TREX]

"TREX - Tree Regular Expressions for XML"

J. Clark (Thai Open Source Software Center), 2001.
Information aboutTREXcan be available at:http://www.thaiopensource.com/trex/

[XHTML11]

"XHTML™1.1 — Module-basedXHTML",W3C Recommendation

M. Altheim, S. McCarron, eds., 31 May 2001
Available at: http://www.w3.org/TR/2001/REC-xhtml11-20010531
The latest version is available at: http://www.w3.org/TR/xhtml11

[XHTMLBasic]

"XHTML™ Basic",W3C Recommendation

M. Baker, M. Ishikawa, S. Matsui, P. Stark, T. Wugofski, T. Yamakami,eds., 19 December 2000.
Available at: http://www.w3.org/TR/2000/REC-xhtml-basic-20001219
The latest version is available at: http://www.w3.org/TR/xhtml-basic

[XHTMLMOD]

"Modularization of XHTML™",W3C Recommendation

S. P. McCarron et al., 10 April 2001.
Available at: http://www.w3.org/TR/2001/REC-xhtml-modularization-20010410
The latest versionis available at: http://www.w3.org/TR/xhtml-modularization

[XHTMLMODSchema]

"Modularization of XHTML™ in XML Schema",W3C Working Draft

D. Austin, S. P. McCarron, eds., 22 March 2001.
Available at: http://www.w3.org/TR/2001/WD-xhtml-m12n-schema-20010322
The latest versionis available at: http://www.w3.org/TR/xhtml-m12n-schema

[XMLSchema]

"XML Schema Part 1: Structures",W3C Recommendation

H. S. Thompson, D. Beech, M. Maloney, N. Mendelsohn, eds., 2 May 2001.
Available at: http://www.w3.org/TR/2001/REC-xmlschema-1-20010502
The latest versionis available at: http://www.w3.org/TR/xmlschema-1

See also "XML Schema Part 2: Datatypes", available at: http://www.w3.org/TR/2001/REC-xmlschema-2-20010502
The latest versionis available at: http://www.w3.org/TR/xmlschema-2

[XMLspec]

"Guide to the W3C XML Specification ("XMLspec")DTD"

E. Maler, ed., the latest version is available at: http://www.w3.org/XML/1998/06/xmlspec-report.htm
The latest version of the DTD is available at: http://www.w3.org/XML/1998/06/xmlspec.dtd

[XSL]

"Extensible Stylesheet Language (XSL) Version 1.0",W3CCandidate Recommendation

S. Adler et al., 21 November 2001.
Available at: http://www.w3.org/TR/2000/CR-xsl-20001121
The latest version is available at: http://www.w3.org/TR/xsl