relax-ng-textbook/src/reference-manual/elements-meta.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="elements.xsl"?>
<!DOCTYPE chapter [
<!ENTITY ns-att "The <this/> attribute defines the default namespace for the elements defined in a portion of schema. The value of <this/> is inherited.">
<!ENTITY dl-att "The <this/> attribute defines the default datatype library. The value of <this/> is inherited.">
<!ENTITY dl-att-nc "&dl-att; Note that although <this/> is allowed in <thisElement/> to maintain a coherence with other Relax NG elements, it has no direct consequence on <thisElement/> itself nor on the name class definitions which might be embedded.">
]>
<chapter xmlns:rng="http://relaxng.org/ns/structure/1.0" id="elements.xml">
  <title>Elements reference guide</title>
  <simplesect>
    <para>This short reference guide to Relax NG elements presents each of the elements composing the XML syntax for Relax NG by alphabetical order. Note that the synopsis given for each element is generated from the Relax NG schema for Relax NG and dooesn't capture the restrictions applied after simplification. The simplification process and restrictions are detailed in "Chapter 15: Simplification And Restrictions". The main restrictions are also mentioned for each element in this chapter in the section titled "Restrictions".</para>
  </simplesect>
  <sect1>
    <title>Elements</title>
    <refentry id="ch15-anyName">
      <name>anyName</name>
      <purpose>Name class accepting any name.</purpose>
      <restrictions>Within the scope of an element, the name classes of attributes cannot overlap. The same restriction applies to name classes of elements when these elements are combined by <literal>interleave</literal>.</restrictions>
      <description><para>The <thisName/> name class matches any name from any namespace. This wild spectrum may be restricted by embedding <literal>except</literal> name classes.</para></description>
      <example><![CDATA[
       <element>
        <anyName/>
        <ref name="anything"/>
       </element>
        
       <element>
        <anyName>
          <except>
            <nsName ns=""/>
            <nsName ns="http://eric.van-der-vlist.com/ns/library"/>
            <nsName ns="http://eric.van-der-vlist.com/ns/person"/>
          </except>
        </anyName>
        <ref name="anything"/>
       </element>
      
       <attribute>
         <anyName/>
       </attribute>]]></example>
      <compact>*-nameClass</compact>
      <compact-description>
      	<this path="description"/>
	<para>The set of these names can be restricted using the optional <literal>exceptNameClass</literal> production.</para>
      </compact-description>
      <compact-example><![CDATA[
 foreign-elements = element * - (local:* | lib:* | hr:*) { anything }*
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att; Note that although <this/> is allowed in <thisElement/> it has no direct consequence on <thisElement/> itself which does always allow any name from any namespace and may only have a consequence on name class definitions embedded in this one."</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att-nc;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-attribute">
      <name>attribute</name>
      <purpose>Pattern matching an attribute.</purpose>
      <description><para>The <this/> pattern matches an attribute. The name of the attribute may be defined either through a <literal>name</literal> attribute or through a name class.</para></description>
      <restrictions><itemizedList>
      	<listItem><para>After simplification, attributes patterns can only contain patterns relevant for text nodes.</para></listItem>
	<listItem><para>Attributes cannot be duplicated, either directly or through overlaping name classes.</para></listItem>
	<listItem><para>Attributes which have an infinite name class (<literal>anyName</literal> or <literal>nsName</literal>) must be enclosed in a <literal>oneOrMore</literal> (or <literal>zeroOrMore</literal> before simplification) pattern.</para></listItem>
     </itemizedList></restrictions>
      <example><![CDATA[
        <attribute name="id"/>
        
        <attribute name="xml:lang">
          <data type="language"/>
         </attribute>

        <attribute>
          <anyName/>
        </attribute>
      ]]></example>
      <compact>attribute</compact>
      <compact-description><para>The <this/> pattern matches an attribute. The name of the attribute is defined through a nameClass which may be either a single name or name class. Note unlike that, for the XML syntax, the content of an attribute is not defaulted to <literal>text</literal> and must always be explicitly defined.</para></compact-description>
      <compact-example><![CDATA[

attribute available { text }

attribute xml:lang { xsd:language }

attribute * - (local:* | lib:* | hr:*) { text }

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>The ns attribute defines the namespace of the attribute. Note that in the context of the <this/> pattern, the ns attribute is not inherited.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>name</literal>
          </term>
          <listitem>
            <para>When <this/> is specified, the  <thisElement/> pattern matches only attributes with this name (<this/> is a shortcut to define a single name as a name class for the <thisElement/> pattern).</para>
            <para>Both <this/> and the definition of a name class cannot be specified (they are exclusive options).</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-choice1">
      <name>choice</name>
      <purpose><thisName/> pattern</purpose>
      <description><para>The <thisName/> pattern defines a choice between different patterns: it matches a node if and only if at least one of its sub-pattern matches this node.</para></description>
      <example><![CDATA[
   <element name="name">
    <choice>
     <text/>
     <group>
      <element name="first"><text/></element>
      <optional>
        <element name="middle"><text/></element>
      </optional>
      <element name="last"><text/></element>
     </group>
    </choice>
   </element>

   <attribute name="available">
     <choice>
      <value>true</value>
      <value>false</value>
      <value>who knows?</value>
     </choice>
    </attribute>

    <start>
      <ref name="libraryElement"/>
      <ref name="bookElement"/>
    </start>
      ]]></example>
      <compact>pattern|pattern</compact>
      <compact-description>
      	<this path="description"/>
	<para>Any number of patterns may be combine through the <literal>|</literal> operator using this construct, but one should note that different operators (<literal>,</literal>, <literal>|</literal> and <literal>&amp;</literal>) cannot be mixed at the same level.</para>
      </compact-description>
      <compact-example><![CDATA[

 element name {
  text|(
   element first{text},
   element middle{text}?,
   element last{text}
  )}
 
   attribute available {"true"|"false"|"who knows?"}
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-choice2">
      <name>choice</name>
      <purpose>Choice between name classes</purpose>
      <description><para>The <this/> name class performs a choice between several name classes: a name will match <this/> if and only if it matches at least one of the sub-name classes.</para></description>
      <example><![CDATA[
 <element>
   <choice>
     <nsName ns="http://eric.van-der-vlist.com/ns/library"/>
     <nsName ns="http://eric.van-der-vlist.com/ns/person"/>
   </choice>
   <ref name="anything"/>
 </element>
      ]]></example>
      <compact>nameClass|nameClass</compact>
      <compact-description>
	<para>The <this/> production performs a choice between two name classes: a name will match <this/> if and only if it matches at least one of the two alternatives.</para>
      </compact-description>
      <compact-example><![CDATA[
 element lib:* | hr:* { anything }
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att-nc;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-data">
      <name>data</name>
      <purpose><thisName/> pattern</purpose>
      <description><para>The <this/> pattern matches a single text node and gives the possibility to restrict its values. This is different from the <literal>text</literal> pattern which matches zero or more text nodes and doesn't give any possibility to restrict the values of these text nodes. The restrictions are applied through the <literal>type</literal> attribute which defines the datatype and the <literal>param</literal> and <literal>except</literal> children patterns.</para></description>
      <restrictions>The <this/> pattern is meant for data oriented applications and can't be used in mixed content models.</restrictions>
      <example><![CDATA[
    <attribute name="see-also">
     <list>
      <data type="token"/>
     </list>
    </attribute>
    
    <attribute name="id">
     <data type="NMTOKEN">
       <param name="maxLength">16</param>
     </data>
    </attribute>

    <element name="isbn">
     <data type="token">
      <except>
       <value>0836217462</value>
      </except>
     </data>
    </element>
      ]]></example>
      <compact>datatypeName param exceptPattern</compact>
      <compact-description>
      <para>The <this/> pattern matches a single text node and gives the possibility to restrict its values. This is different from the <literal>text</literal> pattern which matches zero or more text nodes and doesn't give any possibility to restrict the values of these text nodes. </para>
      <para>In this construction, the restrictions are applied through <literal>datatypeName</literal> which defines the datatype, the optional <literal>param</literal> which define additional parameters passed to the datatype library (when the datatype library is W3C XML Schema datatypes, these parameters are the W3C XML Schema facets) and the optional <literal>exceptPattern</literal> which defines exceptions, i.e. a set of values which are excluded by the <literal>exceptPattern</literal>.</para>
      </compact-description>
      <compact-example><![CDATA[
   attribute available {xs:boolean - (xs:boolean "false")}
 
    element born {xs:date {
      minInclusive = "1900-01-01"
      maxInclusive = "2099-12-31"
      pattern = "[0-9]{4}-[0-9]{2}-[0-9]{2}"
    }}
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>type</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies the datatype used for evaluating the <thisParent/> pattern. Any text node which value isn't valid per this datatype fails to match the <thisParent/> pattern.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-define">
      <name>define</name>
      <purpose>Named pattern definition</purpose>
      <description><para>When <this/> is embedded in a grammar, it defines a named pattern or combines a new definition with an existing one. Named pattern are global to a <literal>grammar</literal> and can be referenced by <literal>ref</literal> in the scope of their <literal>grammar</literal> and by <literal>parentRef</literal> in the scope of the grammars directly embedded in their <literal>grammar</literal>.</para>
        <para>When <this/> is embedded in <literal>include</literal>, the new definition is a redefinition and replaces the definitions from the included grammar unless a <literal>combine</literal> attribute is specified in which case the definitions are combined.</para>
  </description>
  <restrictions>Named patterns are always global and apply only to patterns and it is not possible to define and make reference to non patterns such as class names or datatype parameters.</restrictions>
      <example><![CDATA[
  <define name="born-element">
    <element name="born">
      <text/>
    </element>
  </define>

  <define name="book-content" combine="interleave">
    <attribute name="id"/>
    <attribute name="available"/>
    <ref name="isbn-element"/>
    <ref name="title-element"/>
    <zeroOrMore>
      <ref name="author-element"/>
    </zeroOrMore>
    <zeroOrMore>
      <ref name="character-element"/>
    </zeroOrMore>
  </define>
  
  <define name="isbn-element" combine="choice">
    <notAllowed/>
  </define>
      ]]></example>
      <compact>identifier assignMethod pattern</compact>
      <compact-description><this path="description"/>
      <para>The combination is defined through the <literal>assignMethod</literal> which may take the values: "<literal>=</literal>" (definition), "<literal>&amp;=</literal>" (combination by interleave) or "<literal>|=</literal>" (combination by choice).</para></compact-description>
      <compact-example><![CDATA[

 date-element = element born { xsd:data }
 
 date-element |= element died { xsd:date }
 
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>name</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies the name of the named pattern.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>combine</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies how multiple definitions of a named pattern should be combined together. The possible values are <literal>choice</literal> and <literal>interleave</literal>.</para>
      <para>When the <this/> attribute is specified and set to <literal>choice</literal>, multiple definitions of a named pattern are combined in a <literal>choice</literal> pattern. When the <this/> attribute is specified and set to <literal>interleave</literal>, multiple definitions of a named pattern are combined in an <literal>interleave</literal> pattern.</para>
      <para>Note that it is forbidden to specify more than one <thisElement/> with the same name and no <this/> attribute or multiple <thisElement/> with different values of <this/> attribute.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-div1">
      <name>div</name>
      <purpose>Division (in the context of a <literal>grammar</literal>)</purpose>
      <description><para>The <this/> element is provided to define logical divisions in Relax NG schemas. It has no effect on the validation and its purpose is to define a group of definitions within a <literal>grammar</literal> which may be annotated as a whole.</para>
      <para>In the context of a <literal>grammar</literal>, the content of a <this/> element is the same than the content of a <literal>grammar</literal> (this means that <this/> elements may be embedded in other <this/> elements.</para></description>
      <example><![CDATA[
  <grammar xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://relaxng.org/ns/structure/1.0">
 .../...
   <div>
     <xhtml:p>The content of the book element has been split in two named patterns:</xhtml:p>
     <define name="book-start">
       <attribute name="id"/>
       <ref name="isbn-element"/>
       <ref name="title-element"/>
       <zeroOrMore>
         <ref name="author-element"/>
       </zeroOrMore>
     </define>
     <define name="book-end">
       <zeroOrMore>
         <ref name="author-element"/>
       </zeroOrMore>
       <zeroOrMore>
         <ref name="character-element"/>
       </zeroOrMore>
       <attribute name="available"/>
     </define>
   </div>
 .../...
 </grammar>
      ]]></example>
      <compact>div</compact>
      <compact-description>
      	<this path="description"/>
      </compact-description>
      <compact-example><![CDATA[
 [
   xhtml:p [
     "The content of the book element has been split in two named patterns:"
   ]
 ]
 div {
   book-start =
     attribute id { text },
     isbn-element,
     title-element,
     author-element*
   book-end =
     author-element*,
     character-element*,
     attribute available { text }
 }



      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-div2">
      <name>div</name>
      <purpose>Division (in the context of an <literal>include</literal>)</purpose>
      <description><para>The <this/> element is provided to define logical divisions in Relax NG schemas. It has no effect on the validation and its purpose is to define a group of definitions within an <literal>include</literal> which may be annotated as a whole.</para>
      <para>In the context of an <literal>include</literal>, the content of a <this/> element is the same than the content of a <literal>include</literal> (this means that <this/> elements may be embedded in other <this/> elements.</para></description>
      <example><![CDATA[
  <include href="common.rng">
 .../...
   <div>
     <xhtml:p>The content of the book element has been split in two named patterns:</xhtml:p>
     <define name="book-start">
       <attribute name="id"/>
       <ref name="isbn-element"/>
       <ref name="title-element"/>
       <zeroOrMore>
         <ref name="author-element"/>
       </zeroOrMore>
     </define>
     <define name="book-end">
       <zeroOrMore>
         <ref name="author-element"/>
       </zeroOrMore>
       <zeroOrMore>
         <ref name="character-element"/>
       </zeroOrMore>
       <attribute name="available"/>
     </define>
   </div>
 .../...
 </include>
      ]]></example>
      <compact>div</compact>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-element">
      <name>element</name>
      <purpose>Pattern matching an element</purpose>
      <description><para>The <this/> pattern matches an element. The name of the element may be defined either through a <literal>name</literal> attribute or through a name class.</para></description>
      <example><![CDATA[
      <element name="born">
       <text/>
      </element>

      <element name="character">
        <attribute name="id"/>
        <element name="name">
         <text/>
        </element>
        <element name="born">
         <text/>
        </element>
        <element name="qualification">
         <text/>
        </element>
      </element>

      <element>
        <anyName/>
        <ref name="anything"/>
      </element>
      ]]></example>
      <compact>element</compact>
      <compact-description><para>The <this/> pattern matches an element. The name of the element is defined through a nameClass which may be either a single name or name class.</para></compact-description>
      <compact-example><![CDATA[
element isbn { text }

element hr:born { text }

element title { attribute xml:lang { text }, text }

element * - (local:* | lib:* | hr:*) { anything }
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>name</literal>
          </term>
          <listitem>
            <para>When <this/> is specified, the  <thisElement/> pattern matches only elements with this name (<this/> is a shortcut to define a single name as a name class for the <thisElement/> pattern).</para>
            <para>Both <this/> and the definition of a name class cannot be specified (they are exclusive options).</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-empty">
      <name>empty</name>
      <purpose>Empty content</purpose>
      <description><para>The <this/> patterns is used to define elements which are empty, i.e. which have no children elements, text nor attributes. Note that it is mandatory to use this pattern in such case (<literal><![CDATA[<element name="foo"/>]]></literal> is forbidden) and that there is no such thing as empty attributes (an attribute such as <literal>foo=""</literal> is considered as having a value which is the empty string rather than be considered as being empty, i.e. having no value).</para></description>
      <example><![CDATA[
      <element name="pageBreak">
        <empty/>
      </element>
      ]]></example>
      <compact>empty</compact>
      <compact-description><para>The <this/> patterns is used to define elements which are empty, i.e. which have no children elements, text nor attributes. Note that it is mandatory to use this pattern in such case (<literal><![CDATA[element foo{}]]></literal> is not forbidden) and that there is no such thing as empty attributes (an attribute such as <literal>foo=""</literal> is considered as having a value which is the empty string rather than be considered as being empty, i.e. having no value).</para></compact-description>
      <compact-example><![CDATA[
 element foo {
  element out {empty} &
  (
   element in1 {empty},
   element in2 {empty}
  )
 }
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-except1">
      <name>except</name>
      <purpose>Remove a set of values from a <literal>data</literal></purpose>
      <description><para>The <this/> pattern is used to remove a set of values from a <literal>data</literal> pattern.</para></description>
      <restrictions>The <this/> pattern can only be used in the context of data and can only contain <literal>data</literal>, <literal>value</literal> and <literal>choice</literal> elements.</restrictions>
      <example><![CDATA[
      <element name="isbn">
     <data type="token">
      <except>
       <value>0836217462</value>
      </except>
     </data>
    </element>

    <attribute name="available">
     <data type="token">
      <except>
       <choice>
        <value type="string">true</value>
        <value type="string">false</value>
       </choice>
      </except>
     </data>
    </attribute>

      ]]></example>
      <compact>-pattern</compact>
      <compact-description>
      <para>The <thisName/> pattern is used to remove a set of values from a "<literal>datatypeName param exceptPattern</literal>" pattern.</para>
      </compact-description>
      <compact-example><![CDATA[
   attribute available {xs:boolean - (xs:boolean "false")}
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-except2">
      <name>except</name>
      <purpose>Remove a name class from another</purpose>
      <description><para>The <this/> name class is used to remove a name class from another. Note that this name class has no attributes.</para></description>
      <restrictions>It is impossible to use <this/> to produce empty name classes by including "anyName" in an "except" name class or "nsName" in an "except" name class included in another "nsName".</restrictions>
      <example><![CDATA[
      <element>
        <anyName>
          <except>
            <nsName ns=""/>
            <nsName ns="http://eric.van-der-vlist.com/ns/library"/>
            <nsName ns="http://eric.van-der-vlist.com/ns/person"/>
          </except>
        </anyName>
        <ref name="anything"/>
      </element>

      <element>
       <nsName ns=ns="http://eric.van-der-vlist.com/ns/person"/>
         <except>
           <name>lib:name</name>
           <name>hr:name</name>
         <except>
       </nsName>
       <ref name="anything"/>
      </element>

      ]]></example>
      <compact>-nameClass</compact>
      <compact-description>
      <para>The <thisName/> name class is used to remove a name class from another.</para>
      </compact-description>
      <compact-example><![CDATA[
 element hr:* - ( hr:author | hr:name | hr:born | hr:died ) { anything }
      ]]></compact-example>
      <attributes/>
    </refentry>
    <refentry id="ch15-externalRef">
      <name>externalRef</name>
      <purpose>Reference to an external schema</purpose>
      <description><para>The <this/> pattern is a reference to an external schema. This has the same effect than replacing the <this/> pattern by the external schema considered as a pattern.</para></description>
      <example><![CDATA[
      <element name="book">
        <externalRef href="book.rng"/>
      </element>
      
      <element xmlns="http://relaxng.org/ns/structure/1.0" name="university">
       <element name="name">
        <text/>
       </element>
       <externalRef href="flat.rng"/>
      </element>

      ]]></example>
      <compact>external</compact>
      <compact-description>
      	<this path="description"/>
      </compact-description>
      <compact-example><![CDATA[
 element university { element name { text }, external "flat.rnc" }

 element book { external "book.rnc" }
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>href</literal>
          </term>
          <listitem>
            <para>The <this/> attribute defines the location of the external schema.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-grammar">
      <name>grammar</name>
      <purpose>Grammar pattern</purpose>
      <description><para>The <this/> pattern encapsulates the definitions of <literal>start</literal> and named patterns.</para>
      <para>The most common use of <this/> is to validate XML documents and in this case the <literal>start</literal> pattern defines which elements may be used as the document root element. The <this/> pattern may also be used as a way to write modular schemas and in this case the <literal>start</literal> pattern defines which nodes must be matched by the <this/> at the location where it appears in the schema.</para>
      <para>In every case, the named patterns defined in a <this/> are considered to be local to this <this/>.</para></description>
      <example><![CDATA[
 <grammar xmlns="http://relaxng.org/ns/structure/1.0">
  <start>
   <element name="library">
    <oneOrMore>
     <ref name="book-element"/>
    </oneOrMore>
   </element>
  </start>
  <define name="author-element">
  .../...
  </define>
 </grammar>

  <define name="author-element">
    <grammar>
      <start>
        <element name="author">
          <attribute name="id"/>
          <ref name="name-element"/>
          <parentRef name="born-element"/>
          <optional>
            <ref name="died-element"/>
          </optional>
        </element>
      </start>
      <define name="name-element">
        <element name="name">
          <text/>
        </element>
      </define>
      <define name="died-element">
        <element name="died">
          <text/>
        </element>
      </define>
    </grammar>
  </define>

  <element xmlns="http://relaxng.org/ns/structure/1.0" name="university">
   <element name="name">
     <text/>
   </element>
   <grammar>
     <include href="flat.rng"/>
   </grammar>
 </element>

      ]]></example>
      <compact>grammar</compact>
      <compact-description><this path="description"/></compact-description>
      <compact-example><![CDATA[
 grammar {

  author-element= element author {
   attribute id {text},
   name-element,
   born-element,
   died-element?
  }

  book-element = element book {
   attribute id {text},
   attribute available {text},
   isbn-element,
   title-element,
   author-element *,
   character-element*
  }

  born-element = element born {text}

  character-element =  element character {
   attribute id {text},
   name-element,
   born-element,
   qualification-element
  }

  died-element = element died {text}

  isbn-element = element isbn {text}

  name-element = element name {text}

  qualification-element = element qualification {text}

  title-element = element title {attribute xml:lang {text}, text}

  start = element library {
   book-element +
  }
 }

      
 author-element =
   grammar
   {
      start =
         element author
         {
            attribute id { text },
            name-element,
            born-element,
            died-element?
         }
      name-element = element name { text }
      born-element = element born { text }
      died-element = element died { text }
   }


 
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-group">
      <name>group</name>
      <purpose><this/> pattern</purpose>
      <description><para>The <thisName/> pattern defines an ordered group of sub patterns (note that when <literal>attribute</literal> patterns are included in such a group, their order is not enforced). <this/> patterns are implicit with <literal>element</literal> and <literal>define</literal> patterns.</para></description>
      <example><![CDATA[
   <element name="name">
    <choice>
     <text/>
     <group>
      <element name="first"><text/></element>
      <optional>
        <element name="middle"><text/></element>
      </optional>
      <element name="last"><text/></element>
     </group>
    </choice>
   </element>

 <element name="foo">
  <interleave>
   <element name="out"><empty/></element>
   <group>
    <element name="in1"><empty/></element>
    <element name="in2"><empty/></element>
   </group>
  </interleave>
 </element>
      ]]></example>
      <compact>pattern,pattern</compact>
      <compact-description><para>The <thisName/> pattern defines an ordered group of sub patterns (note that when <literal>attribute</literal> patterns are included in such a group, their order cannot be guaranteed). Any number of patterns may be combine through the <literal>,</literal> operator using this construct, but one should note that different operators (<literal>,</literal>, <literal>|</literal> and <literal>&amp;</literal>) cannot be mixed at the same level.</para></compact-description>
      <compact-example><![CDATA[
      
   element author {
    attribute id {text},
    element name {text},
    element born {text},
    element died {text}?}*
 
   element lib:title { attribute xml:lang { text }, text }
   
   attribute dimensions {list {token, token, token, ("inches"|"cm"|"mm")}}
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-include">
      <name>include</name>
      <purpose>Grammar merge</purpose>
      <description><para>The <this/> pattern includes a grammar and merges its definitions with the definitions of the current grammar. The definitions of the included grammar may be redefined and overridden by the definitions embedded in the <this/> pattern. Note that a schema must contain an explicit <literal>grammar</literal> definition in order to be included.</para></description>
      <example><![CDATA[
  <grammar xmlns="http://relaxng.org/ns/structure/1.0">
   <start>
    <element name="library">
     <oneOrMore>
      <ref name="book-element"/>
     </oneOrMore>
    </element>
   </start>
   <include href="included.rng"/>
   .../...
  </grammar>

  <grammar xmlns="http://relaxng.org/ns/structure/1.0">
   <include href="flat.rng">
     <define name="book-element">
       <element name="book">
         <attribute name="id"/>
         <attribute name="available"/>
         <ref name="isbn-element"/>
         <ref name="title-element"/>
         <ref name="description-element"/>
         <zeroOrMore>
           <ref name="author-element"/>
         </zeroOrMore>
       </element>
     </define>
   </include>
   <define name="description-element">
     <element name="description">
       <text/>
     </element>
   </define>
 </grammar>

      ]]></example>
      <compact>include</compact>
      <compact-description>
      	<this path="description"/>
	<para>The optional <literal>inherit</literal> production defines which namespaces are inherited from the included schema and <literal>includeContent</literal> allows to redefine definitions from the included schema.</para>
      </compact-description>
      <compact-example><![CDATA[
  include "included.rnc"

  include "flat.rnc" { start = book-element }

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>href</literal>
          </term>
          <listitem>
            <para>The <this/> attribute defines the location of the schema which grammar should be included.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-interleave">
      <name>interleave</name>
      <purpose><thisName/> Pattern</purpose>
      <description><para>The <thisName/> pattern "interleaves" sub patterns, i.e. allows their leaves to be mixed in any relative order.</para>
			<para><thisName/> is more than defining unordered groups as we can see on the following example: consider element "a" and the ordered group of element "b1" and "b2". An unordered group of these two patterns would only allow element "a" followed by elements "b1" and "b2" or elements "b1" and "b2 followed by element "a". An <thisName/> of these two patterns does allow these two combinations but also element "b1" followed by "a" followed by "b2", i.e. a combination where the element "a" has been "interleaved" between elements "b1" and "b2".</para>
			<para>The <thisName/> behavior is the behavior applied to <literal>attribute</literal> patterns even when they are embedded in (ordered) <literal>group</literal> patterns (the reason for this is that XML 1.0 specifies that the relative order of attributes is not significant).</para>
			<para>Another case where <thisName/> patterns are often needed is to described mixed content models, i.e. content models where <literal>text</literal> are interleaved between elements. A shortcut (the <literal>mixed</literal> pattern) has been defined for this case.</para></description>
      <restrictions><itemizedList>
      	<listItem><para>The <this/> pattern cannot be used within a <literal>list</literal>.</para></listItem>
	<listItem><para>Elements within a <this/> pattern cannot have overlapping name classes.</para></listItem>
	<listItem><para>There must be at most one "text" pattern in each set of patterns combined by <this/></para></listItem>
     </itemizedList></restrictions>
      <example><![CDATA[
     <element name="character">
      <interleave>
       <attribute name="id"/>
       <element name="name">
        <text/>
       </element>
       <element name="born">
        <text/>
       </element>
       <element name="qualification">
        <text/>
       </element>
      </interleave>
     </element>

    <element name="title">
     <interleave>
      <attribute name="xml:lang"/>
      <zeroOrMore>
       <element name="a">
        <attribute name="href"/>
        <text/>
       </element>
      </zeroOrMore>
      <text/>
     </interleave>
    </element>
			]]></example>
      <compact>pattern&amp;pattern</compact>
      <compact-description>
      	<this path="description"/>
	<para>Any number of patterns may be combine through the <literal>&amp;</literal> operator using this construct, but one should note that different operators (<literal>,</literal>, <literal>|</literal> and <literal>&amp;</literal>) cannot be mixed at the same level.</para>
      </compact-description>
      <compact-example><![CDATA[

   element character {
    attribute id {text}&
    element name {text}&
    element born {text}&
    element qualification {text}}
 
 element foo {
  element out {empty} &
  (
   element in1 {empty},
   element in2 {empty}
  )
 }
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-list">
      <name>list</name>
      <purpose>Text node split</purpose>
      <description><para>The <thisName/> pattern splits a text node into tokens separated by white spaces to allow the validation of these tokens separately. This is most useful for validating lists of values.</para></description>
      <restrictions><itemizedList>
      	<listItem><para><literal>interleave</literal> cannot be used within <this/>.</para></listItem>
	<listItem><para>The content of a <this/> is only about data: it's forbidden to define <literal>element</literal>, <literal>attribute</literal> or <literal>text</literal> there.</para></listItem>
	<listItem><para>It's forbidden to embed <this/> into <this/>.</para></listItem>
     </itemizedList></restrictions>
      <example><![CDATA[
    <attribute name="see-also">
     <list>
      <zeroOrMore>
       <data type="token"/>
      </zeroOrMore>
     </list>
    </attribute>

    <attribute name="dimensions">
     <list>
      <data type="xs:decimal"/>
      <data type="xs:decimal"/>
      <data type="xs:decimal"/>
      <choice>
       <value>inches</value>
       <value>cm</value>
       <value>mm</value>
      </choice>
     </list>
    </attribute>
			]]></example>
      <compact>list</compact>
      <compact-description><this path="description"/></compact-description>
      <compact-example><![CDATA[
 attribute see-also {list {token*}}
 
 attribute dimensions {list {xsd:decimal, xsd:decimal, xsd:decimal, ("inches"|"cm"|"mm")}}
 
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-mixed">
      <name>mixed</name>
      <purpose>Pattern for mixed content models</purpose>
      <description><para>The <thisName/> pattern is a shortcut for <literal>interleave</literal> with an embedded <literal>text</literal> pattern. It describes unordered content models where a text node may be included before and after each element. Note that Relax NG does not allow to add constraints on these text nodes.</para></description>
      <restrictions><para>The limitations of <literal>interleave</literal> apply here:</para>
      <itemizedList>
      	<listItem><para>The <this/> pattern cannot be used within a <literal>list</literal>.</para></listItem>
	<listItem><para>Elements within a <this/> pattern cannot have overlapping name classes.</para></listItem>
	<listItem><para>There must no other "text" pattern in each set of patterns combined by <this/></para></listItem>
     </itemizedList></restrictions>
      <example><![CDATA[
    <element name="title">
     <mixed>
      <attribute name="xml:lang"/>
      <zeroOrMore>
       <element name="a">
        <attribute name="href"/>
        <text/>
       </element>
      </zeroOrMore>
     </mixed>
    </element>
 
is equivalent to:
 
    <element name="title">
     <interleave>
      <text/>
      <group>
        <attribute name="xml:lang"/>
        <zeroOrMore>
         <element name="a">
          <attribute name="href"/>
          <text/>
        </element>
        </zeroOrMore>
      </group>
     </interleave>
    </element>
 
which itself is equivalent to:

    <element name="title">
     <interleave>
      <text/>
      <attribute name="xml:lang"/>
      <zeroOrMore>
       <element name="a">
        <attribute name="href"/>
        <text/>
      </element>
      </zeroOrMore>
     </interleave>
    </element>


			]]></example>
      <compact>mixed</compact>
      <compact-description><this path="description"/></compact-description>
      <compact-example><![CDATA[
 element title {
  mixed {
   attribute xml:lang {text}&
   element a {attribute href {text}, text} *
  }
 }

is equivalent to:

 element title {
  ( text & (
   attribute xml:lang {text}&
   element a {attribute href {text}, text} *
  )
 }

which itself is equivalent to:

 element title {
   text & 
   attribute xml:lang {text}&
   element a {attribute href {text}, text} *
 }

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-name">
      <name>name</name>
      <purpose>Name class for a single name</purpose>
      <description><para>The <this/> name class defines a class with a single name.</para></description>
      <example><![CDATA[
 <element>
   <nsName ns="http://eric.van-der-vlist.com/ns/person"/>
     <except>
       <name>lib:name</name>
       <name>hr:name</name>
     <except>
   </nsName>
   <ref name="anything"/>
 </element>

 <element>
   <choice>
     <name>lib:name</name>
     <name>hr:name</name>
   </choice>
   <ref name="name-content"/>
 </element>

			]]></example>
      <compact>name</compact>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-notAllowed">
      <name>notAllowed</name>
      <purpose>Not allowed</purpose>
      <description><para>The <this/> pattern always fails. It can be used to provide abstract definitions which must be overridden before they can be used in a schema.</para></description>
      <example><![CDATA[
  <define name="isbn-element" combine="choice">
    <notAllowed/>
  </define>
	]]></example>
      <compact>notAllowed</compact>
      <compact-description>
      	<this path="description"/>
      </compact-description>
      <compact-example><![CDATA[
  isbn-element |= notAllowed
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-nsName">
      <name>nsName</name>
      <purpose>Name class for any name in a namespace</purpose>
      <description><para>The <this/> name class allows any name in a specific namespace.</para></description>
      <restrictions>Within the scope of an element, the name classes of attributes cannot overlap. The same restriction applies to name classes of elements when these elements are combined by <literal>interleave</literal>. It is impossible to use <this/> to produce empty name classes by including <this/> in an <literal>except</literal> name class included in another <literal>nsName</literal>.</restrictions>
      <example><![CDATA[
 <element>
   <choice>
     <nsName ns="http://eric.van-der-vlist.com/ns/library"/>
     <nsName ns="http://eric.van-der-vlist.com/ns/person"/>
   </choice>
   <ref name="anything"/>
 </element>

 <element>
   <nsName ns="http://eric.van-der-vlist.com/ns/person"/>
     <except>
       <name>lib:name</name>
       <name>hr:name</name>
     <except>
   </nsName>
   <ref name="anything"/>
 </element>

			]]></example>
      <compact>nsName exceptNameClass</compact>
      <compact-description>
      	<this path="description"/>
	<para>The namespace is defined by the <literal>nsName</literal> production and the set of these names can be restricted using the <literal>exceptNameClass</literal> production.</para>
      </compact-description>
      <compact-example><![CDATA[
 element lib:* { anything }
 
 element hr:* - ( hr:author | hr:name | hr:born | hr:died ) { anything }

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-oneOrMore">
      <name>oneOrMore</name>
      <purpose><thisName/> pattern</purpose>
      <description><para>The <this/> pattern specifies that its sub patterns considered as an ordered group must be matched one or more time.</para></description>
      <restrictions>The <this/> pattern cannot contain attribute definitions.</restrictions>
      <example><![CDATA[
 <element name="library">
  <oneOrMore>
   <element name="book">
   .../...
   </element>
  </oneOrMore>
 </element>			]]></example>
      <compact><literal>pattern+</literal></compact>
      <compact-description><para>A pattern qualified as <thisName/> must be matched one or more times.</para></compact-description>
      <compact-example><![CDATA[
  start = element library {
   book-element +
  }
 
   attribute see-also {list {("0836217462"|"0345442695"|"0449220230"|"0449214044"|"0061075647")+}}

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-optional">
      <name>optional</name>
      <purpose><thisName/> pattern</purpose>
      <description><para>The <thisName/> pattern specifies that its sub-patterns considered as an ordered group is optional, i.e. must be matched zero or one time.</para></description>
      <example><![CDATA[
     <element name="author">
      <attribute name="id"/>
      <element name="name">
       <text/>
      </element>
      <element name="born">
       <text/>
      </element>
      <optional>
       <element name="died">
        <text/>
       </element>
      </optional>
     </element>
		 
   <element name="name">
    <choice>
     <text/>
     <group>
      <element name="first"><text/></element>
      <optional>
        <element name="middle"><text/></element>
      </optional>
      <element name="last"><text/></element>
     </group>
    </choice>
   </element>

			]]></example>
      <compact><literal>pattern?</literal></compact>
      <compact-description><para>A pattern qualified as <thisName/> is optional, i.e. must be matched zero or one time.</para></compact-description>
      <compact-example><![CDATA[

    element died {text}?
 
  attribute see-also {list {token, token?, token?, token?}}
 
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-param">
      <name>param</name>
      <purpose>Datatype parameter</purpose>
      <description><para>The <this/> element defines parameters passed to the datatype library to determine if a value is valid per a datatype. When the datatype library is the W3C XML Schema datatypes, these parameters are the facets of the datatype and they define additional restrictions to be applied. The name of the parameter is defined by the <literal>name</literal> attribute and its value is the content of the <this/> element.</para></description>
      <example><![CDATA[
   <element name="book">
    <attribute name="id">
     <data type="NMTOKEN">
       <param name="maxLength">16</param>
     </data>
    </attribute>
    <attribute name="available">
     <data type="boolean"/>
    </attribute>
    <element name="isbn">
     <data type="NMTOKEN">
       <param name="pattern">[0-9]{9}[0-9x]</param>
     </data>
    </element>
    <element name="title">
     <attribute name="xml:lang">
      <data type="language">
       <param name="length">2</param>
      </data>
     </attribute>
     <data type="token">
       <param name="maxLength">255</param>
     </data>
    </element>
		]]></example>
      <compact>param</compact>
      <compact-description>
	<para>The <this/> production defines parameters passed to the datatype library to determine if a value is valid per a datatype. When the datatype library is the W3C XML Schema datatypes, these parameters are the facets of the datatype and they define additional restrictions to be applied. The name of the parameter is defined by <literal>identifierOrKeyword</literal> and its value defined by <literal>literal</literal><this/>.</para>
      </compact-description>
      <compact-example><![CDATA[
    element born {xs:date {
      minInclusive = "1900-01-01"
      maxInclusive = "2099-12-31"
      pattern = "[0-9]{4}-[0-9]{2}-[0-9]{2}"
    }}
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>name</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies the name of the parameter.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-parentRef">
      <name>parentRef</name>
      <purpose>Reference to a named pattern from the parent grammar</purpose>
      <description><para>The <this/> pattern is a reference to a named pattern belonging to the parent <literal>grammar</literal>, i.e. the <literal>grammar</literal> in which the current <literal>grammar</literal> is included. The scope of named pattern is usually limited to the <literal>grammar</literal> in which they are defined and the <this/> pattern provides a way to extend this scope and refer named pattern defined in the parent <literal>grammar</literal>.</para></description>
      <example><![CDATA[
  <define name="born-element">
    <element name="born">
      <text/>
    </element>
  </define>
  <define name="author-element">
    <grammar>
      <start>
        <element name="author">
          <attribute name="id"/>
          <ref name="name-element"/>
          <parentRef name="born-element"/>
          <optional>
            <ref name="died-element"/>
          </optional>
        </element>
      </start>
      <define name="name-element">
        <element name="name">
          <text/>
        </element>
      </define>
      <define name="died-element">
        <element name="died">
          <text/>
        </element>
      </define>
    </grammar>
  </define>			
			]]></example>
      <compact>parent</compact>
      <compact-description><this path="description"/></compact-description>
      <compact-example><![CDATA[
  born-element = parent born-element
 
 start =
    attribute id { parent id-content },
    attribute available { parent available-content },
    element isbn { parent isbn-content },
    element title { parent title-content },
    element author { parent author-content }*,
    element character { parent character-content }*

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>name</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies the name of the named pattern which is referenced.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-ref">
      <name>ref</name>
      <purpose>Reference to a named pattern</purpose>
      <description><para>The <this/> pattern defines a reference to a named pattern defined in the current <literal>grammar</literal>.</para></description>
      <example><![CDATA[
 <element name="book">
  <ref name="book-start"/>
  <ref name="book-end"/>
 </element>
 
   <element name="library">
    <oneOrMore>
     <ref name="book-element"/>
    </oneOrMore>
   </element>
 
 ]]></example>
      <compact>Name without a colon</compact>
      <attributes>
        <varlistentry>
          <term>
            <literal>name</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies the name of the named pattern which is referenced.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-start">
      <name>start</name>
      <purpose>Start of a grammar</purpose>
      <description><para>The <this/> pattern defines the "start" of a <literal>grammar</literal>. When this grammar is used to validate a complete document, the <this/> pattern defines which elements may be used as the document (root) element. When this grammar is embedded in another <literal>grammar</literal>, the <this/> pattern describes which pattern should be applied at the location where the <literal>grammar</literal> is embedded. Like named pattern definitions, start patterns may be combined by <literal>choice</literal> or <literal>interleave</literal> and redefined when they are included in <literal>include</literal> patterns.</para></description>
      <example><![CDATA[
  <start>
   <element name="library">
    <oneOrMore>
     <ref name="book-element"/>
    </oneOrMore>
   </element>
  </start>
  <start combine="choice">
    <ref name="book-element"/>
  </start>

  <define name="author-element">
    <grammar>
      <start>
        <element name="author">
          <attribute name="id"/>
          <ref name="name-element"/>
          <ref name="born-element"/>
          <optional>
            <ref name="died-element"/>
          </optional>
        </element>
      </start>
      <define name="name-element">
        <element name="name">
          <text/>
        </element>
      </define>
      <define name="born-element">
        <element name="born">
          <text/>
        </element>
      </define>
      <define name="died-element">
        <element name="died">
          <text/>
        </element>
      </define>
    </grammar>
  </define>


			]]></example>
      <compact>start</compact>
      <compact-description><this path="description"/>
      <para>The combination is defined through the <literal>assignMethod</literal> which may take the values: "<literal>=</literal>" (definition), "<literal>&amp;=</literal>" (combination by interleave) or "<literal>|=</literal>" (combination by choice).</para></compact-description>
      <compact-example><![CDATA[
  start = element library {
   book-element +
  }
 
  start |= book-element
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>combine</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies how multiple definitions of <thisElement/> pattern should be combined together. The possible values are <literal>choice</literal> and <literal>interleave</literal>.</para>
      <para>When the <this/> attribute is specified and set to <literal>choice</literal>, multiple definitions of a  <thisElement/> pattern are combined in a <literal>choice</literal> pattern. When the <this/> attribute is specified and set to <literal>interleave</literal>, multiple definitions of a  <thisElement/> pattern are combined in an <literal>interleave</literal> pattern.</para>
      <para>Note that it is forbidden to specify more than one <thisElement/> with the same name and no <this/> attribute or multiple <thisElement/> with different values of <this/> attribute.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-text">
      <name>text</name>
      <purpose>Pattern matching text nodes</purpose>
      <description><para>The <this/> pattern matches zero or more text nodes. The fact that a <this/> pattern matches more than one text node has no effect when it is used in ordered content models (the data model used by Relax NG for XML documents is similar to the data model of XPath 1.0 and two text nodes cannot be adjacent) but makes a difference when a <this/> pattern is used in <literal>interleave</literal>:adding a single <this/> pattern in an <literal>interleave</literal> pattern has the effect of allowing any number of text nodes which can interleave before and after each element (note that the <literal>mixed</literal> pattern is provided as a shortcut to define these content models).</para></description>
      <restrictions>No more than one <this/> pattern can be included in an <literal>interleave</literal> pattern. </restrictions>
      <example><![CDATA[
  <element name="first"><text/></element>

   <element name="name">
    <choice>
     <text/>
     <group>
      <element name="first"><text/></element>
      <optional>
        <element name="middle"><text/></element>
      </optional>
      <element name="last"><text/></element>
     </group>
    </choice>
   </element>
]]></example>
      <compact>text</compact>
      <compact-description>
      	<this path="description"/>
      </compact-description>
      <compact-example><![CDATA[
  element author {
   attribute id {text},
   element name {text},
   element born {text},
   element died {text}?}?

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-value">
      <name>value</name>
      <purpose>Match a text node and a value</purpose>
      <description><para>The <this/> pattern matches a text node against a value using the semantic of a specified datatype to perform the comparison.</para></description>
      <restrictions>The <this/> pattern is meant for data oriented applications and can't be used in mixed content models.</restrictions>
      <example><![CDATA[
    <attribute name="see-also">
     <list>
      <oneOrMore>
       <choice>
        <value>0836217462</value>
        <value>0345442695</value>
        <value>0449220230</value>
        <value>0449214044</value>
        <value>0061075647</value>
       </choice>
      </oneOrMore>
     </list>
    </attribute>

    <attribute name="available">
     <data type="boolean">
      <except>
       <value>0</value>
       <value>1</value>
      </except>
     </data>
    </attribute>

    <attribute name="available">
     <data type="boolean">
      <except>
       <value type="boolean">false</value>
      </except>
     </data>
    </attribute>


]]></example>
      <compact>datatypeName literal</compact>
      <compact-description><this path="description"/>
      <para>When datatypeName is omitted, the default datatype (which is the token datatype from the Relax NG built in library) is used.</para></compact-description>
      <compact-example><![CDATA[
 "0"
 
 xs:integer "0"

 xs:boolean "false"

 attribute available {xs:boolean "true"}
      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>type</literal>
          </term>
          <listitem>
            <para>The <this/> attribute specifies the datatype to use to perform the comparison. Note that this is not an inherited attribute and that when it is not specified, the comparison is done using the default datatype which is the <literal>token</literal> datatype of the Relax NG built in type library which means that a string comparison will be done on the values after space normalization.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch15-zeroOrMore">
      <name>zeroOrMore</name>
      <purpose><thisName/> pattern</purpose>
      <description><para>The <thisName/> pattern specifies that its sub patterns considered as an ordered group must be matched zero or more time.</para></description>
      <restrictions>The <this/> pattern cannot contain attribute definitions.</restrictions>
      <example><![CDATA[
  <define name="book-element">
   <element name="book">
    <attribute name="id"/>
    <attribute name="available"/>
    <ref name="isbn-element"/>
    <ref name="title-element"/>
    <zeroOrMore>
     <ref name="author-element"/>
    </zeroOrMore>
    <zeroOrMore>
     <ref name="character-element"/>
    </zeroOrMore>
   </element>
  </define>
]]></example>
      <compact>pattern*</compact>
      <compact-description><para>A pattern qualified as <thisName/> must be matched zero or more times (i.e. any number of times).</para></compact-description>
      <compact-example><![CDATA[
      
   element author {
    attribute id {text},
    element name {text},
    element born {text},
    element died {text}?}* 
 
  book-element = element book {
   attribute id {text},
   attribute available {text},
   isbn-element,
   title-element,
   author-element *,
   character-element*
  }

      ]]></compact-example>
      <attributes>
        <varlistentry>
          <term>
            <literal>ns</literal>
          </term>
          <listitem>
            <para>&ns-att;</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>datatypeLibrary</literal>
          </term>
          <listitem>
            <para>&dl-att;</para>
          </listitem>
        </varlistentry>
      </attributes>
    </refentry>
    <refentry id="ch16-namespace">
      <name>xmlns:</name>
      <purpose>Namespace declaration</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>namespace</compact>
      <compact-description><para>The <this/> declaration defines namespace prefixes for the compact syntax like xmlns:xxx attributes in XML. Note that unlike XML namespace declarations, declarations for the Relax NG compact syntax in general (and <this/> declarations in particular) are global to a schema and cannot be redefined. A prefix can be assigned to the lack of namespace using the value <literal>""</literal>. The <literal>xml</literal> prefix is predefined.</para></compact-description>
      <compact-example><![CDATA[
namespace hr = "http://eric.van-der-vlist.com/ns/person"
namespace local = ""
      ]]></compact-example>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-default-namespace">
      <name>xmlns</name>
      <purpose>Default namespace declaration</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>default namespace</compact>
      <compact-description><para>The <this/> declaration defines the default namespace for the compact syntax like <literal>xmlns</literal> attributes in XML. An optional prefix may be assigned to the default namespace which may then be explicitly referenced. Note that unlike XML default namespace declarations, declarations for the Relax NG compact syntax in general (and <this/> declarations in particular) are global to a schema and cannot be redefined. A prefix can be assigned to the lack of namespace using the value <literal>""</literal>.</para></compact-description>
      <compact-example><![CDATA[
default namespace = "http://eric.van-der-vlist.com/ns/library"
default namespace local = ""
      ]]></compact-example>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-datatypes">
      <name>xmlns:</name>
      <purpose>Namespace declaration (to identify datatype libraries)</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>datatypes</compact>
      <compact-description><para>The <this/> declaration assigns a prefix to a datatype library for the compact syntax like xmlns:xxx attributes in XML. Note that unlike XML namespace declarations, declarations for the Relax NG compact syntax in general (and <this/> declarations in particular) are global to a schema and cannot be redefined. The prefix <literal>xsd</literal> is predefined and bound to "http://www.w3.org/2001/XMLSchema-datatypes".</para></compact-description>
      <compact-example><![CDATA[
datatypes xs = "http://www.w3.org/2001/XMLSchema-datatypes"
      ]]></compact-example>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-parenthesis">
      <name>none</name>
      <purpose>Container</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>(pattern)</compact>
      <compact-description><para>The <this/> container is useful to group together patterns combined through "<literal>,</literal>" (ordered group),  "<literal>|</literal>" (choice) or "<literal>&amp;</literal>" (interleave). This container is a pattern and may be combined with other patterns or quantified using qualifiers. </para>
      <para>The operator "<literal>,</literal>",  "<literal>|</literal>" or "<literal>&amp;</literal>" used within the <this/> container defines how the sub patterns are combined and different operators cannot be mixed at the same level.</para>
      <para>Even when such a container is not required, it may often be used to improve the readability of a schema.</para>
      </compact-description>
      <compact-example><![CDATA[
 element name {
  text|(
   element first{text},
   element middle{text}?,
   element last{text}
  )}
  
 element foo {
  element out {empty} &
  (
   element in1 {empty},
   element in2 {empty}
  )
 }
      ]]></compact-example>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-parenthesis-nc">
      <name>none</name>
      <purpose>Container</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>(nameClass)</compact>
      <compact-description><para>The <this/> container is useful to group together name classes combined through "<literal>|</literal>" (choice). This container is a name class and may be combined with other name classes. </para>
      <para>Even when such a container is not required, it may often be used to improve the readability of a schema.</para>
      </compact-description>
      <compact-example><![CDATA[
 element hr:* - ( hr:author | hr:name | hr:born | hr:died ) { anything }    
    ]]></compact-example>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-pattern">
      <name>none</name>
      <purpose>Pattern</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>pattern</compact>
      <compact-description><para>A pattern is an atom of Relax NG schema which is matched against nodes from the instance document (elements, attributes, text nodes or token resulting of a split through <literal>list</literal>).</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-top-level">
      <name>none</name>
      <purpose>Top level</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>Top level</compact>
      <compact-description><para>Start symbol for the Relax NG compact syntax EBNF. The <this/> production describes the top level structure of a Relax NG compact syntax document composed of an optional declaration section and of the actual schema composed of either a single <literal>pattern</literal> or a more complete <literal>grammarContent</literal>.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-decl">
      <name>none</name>
      <purpose>Declarations</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>decl</compact>
      <compact-description><para>Declarations section of a Relax NG compact syntax schema. These declarations are global and common to the whole schema and include the namespace and datatype libraries declarations.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-grammarContent">
      <name>none</name>
      <purpose>Content of a grammar</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>grammarContent</compact>
      <compact-description><para>The <this/> production defines the content of a <literal>grammar</literal>.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-includeContent">
      <name>none</name>
      <purpose>Content of an <literal>include</literal> pattern.</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>includeContent</compact>
      <compact-description><para>The <this/> production defines the content of an <literal>include</literal>. The only difference with <literal>grammarContent</literal> is that <this/> doesn't allow embedded <literal>include</literal>.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-assignMethod">
      <name>none</name>
      <purpose>Define how to assign a content to <literal>start</literal> and named patterns.</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>assignMethod</compact>
      <compact-description><para>The <this/> how the content of  <literal>start</literal> and named patterns are affected by a new definition. <this/> which may take the values: "<literal>=</literal>" (definition), "<literal>&amp;=</literal>" (combination by interleave) or "<literal>|=</literal>" (combination by choice).</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-nameClass">
      <name>none</name>
      <purpose>Define a set of names that must be matched by an element or attribute.</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>nameClass</compact>
      <compact-description><para>The <this/> production defines sets of names that must be matched by elements and attributes. Its simplest expression is to define a single <literal>name</literal> but specific wildcards can also be expressed as <this/>.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-name">
      <name>none</name>
      <purpose>Define a set of names that must be matched by an element or attribute.</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>name</compact>
      <compact-description><para>The <this/> name class defines sets of names which are singletons i.e. that match only one name. There is no other restriction than those of XML 1.0 and namespaces in XML 1.0 on such names and they can be either <literal>CName</literal> or <literal>identifierOrKeyword</literal> (in particular, even <literal>keyword</literal>s can be used as <literal>name</literal>s).</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="ch16-datatypeName">
      <name>none</name>
      <purpose>Datatype name</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>datatypeName</compact>
      <compact-description><para>The <this/> production defines what is a valid datatype name. <literal>CName</literal> (Colonized names) must be used for any datatype library except for the built in type library which has only two datatypes (<literal>string</literal> and <literal>token</literal>).</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="namespaceURILiteral">
      <name>none</name>
      <purpose>Namespace URI Literal</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>namespaceURILiteral</compact>
      <compact-description><para>The <this/> production is used to specify a namespace URI and can either be a <literal>literal</literal> or the value "<literal>inherit</literal> to specify that the namespace URI is inherited from the including file.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="inherit">
      <name>none</name>
      <purpose>Namespace inheritance</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>inherit</compact>
      <compact-description><para>The <this/> production is used in <literal>external</literal> and <literal>include</literal> statements to specify the prefixes of the namespaces which are inherited by the included file.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="identifierOrKeyword">
      <name>none</name>
      <purpose>Identifier or keyword</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>identifierOrKeyword</compact>
      <compact-description><para>The <this/> production either a valid <literal>identifier</literal> or a <literal>keyword</literal>.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="identifier">
      <name>none</name>
      <purpose>Identifier</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>identifier</compact>
      <compact-description><para>The <this/> production describes valid <literal>identifier</literal>s for the compact syntax, i.e. either quoted identifiers or the non colonized names which are not keywords.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="quotedIdentifier">
      <name>none</name>
      <purpose>Quoted identifier</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>QuotedIdentifier</compact>
      <compact-description><para>The <this/> production describes quoted identifiers, i.e. non colonized names preceded by a <literal>\</literal>. This is needed to allow names which are the same than the keywords of the compact syntax.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="CName">
      <name>none</name>
      <purpose>Colonized names</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>CName</compact>
      <compact-description><para>The <this/> production describes colonized names (i.e. names containing a colon) as two non colonized names separated by a colon ("<literal>:</literal>").</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="literal">
      <name>none</name>
      <purpose>Literal</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>literal</compact>
      <compact-description><para>The <this/> production describes literals as several segments of literals contained by the "<literal>~</literal>" sign.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="literalSegment">
      <name>none</name>
      <purpose>Literal segment</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>literalSegment</compact>
      <compact-description><para>The <this/> production describes literal segments as strings enclosed either in simple or double quotes or enclosed in three double or single quotes using a pythonic syntax.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="literalSegmentDoubleQuote">
      <name>none</name>
      <purpose>Literal segment enclosed in double quotes</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>"..."</compact>
      <compact-description><para>The <this/> production describes literal segments enclosed in double quotes. These segments can include any character except newlines and double quotes.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="literalSegmentSimpleQuote">
      <name>none</name>
      <purpose>Literal segment enclosed in single quotes</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>'...'</compact>
      <compact-description><para>The <this/> production describes literal segments enclosed in single quotes. These segments can include any character except newlines and single quotes.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="literalSegmentPythonicDouble">
      <name>none</name>
      <purpose>Literal segment enclosed in three double quotes</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>"""..."""</compact>
      <compact-description><para>The <this/> production describes literal segments enclosed in three double quotes. These segments can include any character except sequences of three double quotes.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="literalSegmentPythonicSimple">
      <name>none</name>
      <purpose>Literal segment enclosed in three single quotes</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>'''...'''</compact>
      <compact-description><para>The <this/> production describes literal segments enclosed in three single quotes. These segments can include any character except sequences of three single quotes.</para></compact-description>
      <attributes></attributes>
    </refentry>
    <refentry id="keyword">
      <name>none</name>
      <purpose>Keywords</purpose>
      <description></description>
      <example><![CDATA[]]></example>
      <compact>keyword</compact>
      <compact-description><para>The <this/> production gives the list of keywords for the Relax NG compact syntax. Note that these keywords are reserved only when there is a risk of confusion and that they can be used, for instance, as element or attribute names without being quoted. When they are reserved, they can still be used as identifiers but need to be quoted.</para></compact-description>
      <attributes></attributes>
    </refentry>
  </sect1>
</chapter>