STEP 2: Migration from XML DTD (with parameter entities)

$Id: step2.sdoc 1.10 2000/11/01 13:41:12 murata Exp $

Often, you have to write the same thing many times. Features in STEP 2 allow you to create a description once and reference to it repeatedly. These features mimic parameter entities of XML.

Parameter entities used in content models

hedgeRuleallows you to write a hedge model once, name it, and reference to it repeatedly. In other words, hedgeRule mimics parameter entities referenced from content models in DTD.

Overview

The syntax of hedgeRule is shown below. foo is a name assigned to the hedge model of this hedgeRule.

<hedgeRule label="foo">
  ...element content model...
</hedgeRule>

To reference to such a hedgeRule, we write <hedgeRef label="foo"/>. This hedgeRef is replaced with the element hedge model specified in the hedgeRule.

In the following example, the hedge model of the elementRule for the element type doc references to a hedgeRule. This elementRule is borrowed from the module in the beginning of STEP 1, and the hedge model minus title is rewritten by a hedgeRule.

<hedgeRule label="doc.body">
  <ref label="para" occurs="*"/>
</hedgeRule>

<elementRule role="doc">
  <sequence>
    <ref label="title"/>
    <hedgeRef label="doc.body"/>
  </sequence>
</elementRule>

The reference to doc.body is expanded as below:

<elementRule role="doc">
  <sequence>
    <ref label="title"/>
    <ref label="para" occurs="*"/>
  </sequence>
</elementRule>

In this example, a hedgeRule is referenced from an elementRule. But a hedgeRule may reference to another hedgeRule.

Permissible hedge models

hedgeRulecan have element hedge models only. Datatype references or mixed hedge models are not permitted. For example, the following rules are not permitted.

<hedgeRule label="mixed.param">
  <mixed>
    <choice occurs="*">
      <ref label="em"/>
      <ref label="strong"/>
    <choice>
  </mixed>
</hedgeRule>

<hedgeRule label="string.param" type="string"/>

If you want to use hedgeRef in conjunction with a mixed hedge model, you have to surround the hedgeRef with mixed in an elementRule element, rather than using the mixed element inside a hedgeRule element. An example is shown below. The mixed hedge model references to phrase, and phrase is described by a hedgeRule.

<hedgeRule label="phrase">
  <choice>
    <ref label="em"/>
    <ref label="strong"/>
  <choice>
</hedgeRule>

<elementRule role="p">
  <mixed>
    <hedgeRef label="phrase" occurs="*"/>
  </mixed>
</elementRule>

The occurs attribute

hedgeRefthat references to a parameter entity can have occurs, and an element hedge model specified in hedgeRule can also have occurs. In the following example, both have occurs.

<hedgeRule label="bar">
  <sequence occurs="+" >
    <ref label="foo1"/>
    <ref label="foo2"/>
  </sequence>
</hedgeRule>

<elementRule role="foo">
  <hedgeRef label="bar" occurs="*"/>
</elementRule>

If this example is recaptured in DTD, expansion of the parameter entity bar is obvious.

<!ENTITY % bar "(foo1, foo2)+">
<!-- original --> <!ELEMENT foo (%bar;)*>
<!-- expanded --> <!ELEMENT foo ((foo1, foo2)+)*>

The following shows expansion of the above example. Observe that a choice element containing a single child is introduced during expansion. This choice element inherits occurs="*" from the ref.

<elementRule role="foo">
  <choice occurs="*">
    <sequence occurs="+" >
      <ref label="foo1"/>
      <ref label="foo2"/>
    </sequence>
  </choice>
</elementRule>

Occurrence order of hedgeRef and hedgeRule

Unlike parameter entities of DTD, hedgeRule does not have to precede ref that reference to it. For example, the following is not an error.

<elementRule role="doc">
  <sequence>
    <ref label="title"/>
    <hedgeRef label="doc.body"/>
  </sequence>
</elementRule>

<hedgeRule label="doc.body">
  <ref label="para" occurs="*"/>
</hedgeRule>

Illegal reference to itself

hedgeRulemay not reference to itself directly or indirectly. The follow is an error since the hedge model for bar references to bar itself.

<hedgeRule label="bar">
  <choice>
    <ref label="title"/>
    <hedgeRef label="bar" occurs="*"/>
  </choice>
</hedgeRule>

In the following example, the hedge model for bar1 references to bar2 and the hedge model for bar2 references to bar1. Thus, there is an error.

<hedgeRule label="bar1">
  <hedgeRef label="bar2" occurs="*"/>
</hedgeRule>

<hedgeRule label="bar2">
  <choice>
    <ref label="title"/>
    <hedgeRef label="bar1"/>
  </choice>
</hedgeRule>

Use of empty

empty, shown in STEP 1, is typically used in hedgeRule. An example is as below:

<hedgeRule label="frontMatter">
  <empty/>
</hedgeRule>

<elementRule role="section">
  <sequence>
    <ref label="title"/>
    <hedgeRef label="frontMatter"/>
    <ref label="para" occurs="*"/>
  </sequence>
</elementRule>

Users of this module can change the structure of section by customizing the description of frontMatter.

Use of none

none, shown in STEP 1, is also used in hedgeRule. An example is as below:

<hedgeRule label="local-block-class">
  <none/>
</hedgeRule>

<hedgeRule label="block-class">
  <choice>
    <ref label="para"/>
    <ref label="fig"/>  
    <hedgeRef label="local-black-class"/>  
  </choice>
</hedgeRule>

Users of this module can change the structure of block-class by customizing the description of local-block-class.

Parameter entities used in attribute-list declarations

attPoolallows you to declare attributes once and reference to the declarations repeatedly. In other words, attPool mimics parameter entities referenced from attribute-list declarations.

Overview

The syntax of attPool is shown below. foo is a name of a parameter entity.

<attPool role="foo">
  ...attribute definitions...
</attPool>

To reference to such an attPool, we write <ref role="foo"/> before attribute declarations. This ref is replaced with attribute declarations specified in the attPool.

In the following example, a tag for the element type title references to attPool. This tag is borrowed from the module in the beginning of STEP 1 and rewritten. The role attribute, which is common to many element types, is described by attPool named common.att.

<attPool role="common.att">
  <attribute name="class" type="NMTOKEN"/>
</attPool>

<tag name="title">
  <ref role="common.att"/>
  <attribute name="number" required="true" type="integer"/>
</tag>

This ref is expanded as below:

<tag name="title">
  <attribute name="class" type="NMTOKEN"/>
  <attribute name="number" required="true" type="integer"/>
</tag>

In this example, attPool is referenced from tag, but it can also be referenced from attPool.

Occurrence order of ref and attPool

Unlike parameter entities of DTD, attPool does not have to precede ref that reference to it. For example, the following is not an error.

<tag name="title">
  <ref role="common.att"/>
  <attribute name="number" required="true" type="integer"/>
</tag>

<attPool role="common.att">
  <attribute name="role" type="NMTOKEN"/>
</attPool>

Multiple ref elements

A single tag or attPool may contain more than one ref element. In the following example, an attPool element references to more than one ref element. Required attributes are grouped as common-req.att and optional attributes are grouped as common-opt.att. These two are referenced from the attPool element for common.att.

<attPool role="common.att">
  <ref role="common-req.att"/>
  <ref role="common-opt.att"/>
</attPool>

<attPool role="common-req.att">
  <attribute name="role" type="NMTOKEN" required="true"/>
</attPool>

<attPool role="common-opt.att">
  <attribute name="id" type="NMTOKEN"/>
</attPool>

Illegal reference to itself

As in the case of hedgeRule, a direct or indirect reference to itself is an error. For example, the following is an error.

<attPool role="bar1">
  <ref role="bar2"/>
  <attribute name="id" type="NMTOKEN"/>
</attPool>

<attPool role="bar2">
  <ref role="bar1"/>
</attPool>

Summary

STEP 2 covers almost all features of XML DTD. Enjoy and RELAX!