writerfilter/documentation/ooxml/model.rng

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9 -->
  10 <!--
  11 This file is both a relax-ng schema for writerfilter/source/ooxml/model.xml and
  12 documentation for that file. The schema has two parts:
  13
  14 - first part: a subset of the relax-ng grammar to define *what* we expect as
  15   the input in a DOCX file
  16 - second part: additional annotation on top of that to define *how* to handle
  17   that expected input
  18 -->
  19 <grammar xmlns="http://relaxng.org/ns/structure/1.0">
  20   <!--
  21   First part: a subset of the relax-ng XML markup.
  22
  23   The order of elements in this part follow a bottom-up approach.
  24   -->
  25
  26   <!-- Basic building blocks: element, attribute and their contents. -->
  27
  28   <!--
  29   Describes an XML element.
  30
  31   Example:
  32
  33   <element name="charset">
  34     <ref name="CT_Charset"/>
  35   </element>
  36   -->
  37   <define name="element-element">
  38     <element name="element" ns="http://relaxng.org/ns/structure/1.0">
  39       <optional>
  40         <attribute name="name"/>
  41       </optional>
  42       <oneOrMore>
  43         <choice>
  44           <ref name="attribute-element"/>
  45           <ref name="data-element"/>
  46           <ref name="ref-element"/>
  47         </choice>
  48       </oneOrMore>
  49     </element>
  50   </define>
  51
  52   <!--
  53   Describes an attribute.
  54
  55   Example:
  56
  57   <attribute name="name">
  58     <data type="string"/>
  59   </attribute>
  60   -->
  61   <define name="attribute-element">
  62     <element name="attribute" ns="http://relaxng.org/ns/structure/1.0">
  63       <optional>
  64         <attribute name="name"/>
  65       </optional>
  66       <zeroOrMore>
  67         <choice>
  68           <ref name="data-element"/>
  69           <ref name="ref-element"/>
  70         </choice>
  71       </zeroOrMore>
  72     </element>
  73   </define>
  74
  75   <!--
  76   Describes the type of the data contained in an attribute. Possible values:
  77   boolean, integer or string. See also <text>.
  78   -->
  79   <define name="data-element">
  80     <element name="data" ns="http://relaxng.org/ns/structure/1.0">
  81       <attribute name="type"/>
  82     </element>
  83   </define>
  84
  85   <!--
  86   Describes an enumeration element: a possible value for an attribute.
  87   -->
  88   <define name="value-element">
  89     <element name="value" ns="http://relaxng.org/ns/structure/1.0">
  90       <text/>
  91     </element>
  92   </define>
  93
  94   <!--
  95   This element is ignored during parsing, it just helps readability.
  96
  97   Example:
  98
  99   <choice>
 100     <value>true</value>
 101     <value>false</value>
 102   </choice>
 103   -->
 104   <define name="choice-element">
 105     <element name="choice" ns="http://relaxng.org/ns/structure/1.0">
 106       <oneOrMore>
 107         <choice>
 108           <ref name="data-element"/>
 109           <ref name="element-element"/>
 110           <ref name="ref-element"/>
 111           <ref name="value-element"/>
 112         </choice>
 113       </oneOrMore>
 114     </element>
 115   </define>
 116
 117   <!-- Grouping elements: define and grammar. -->
 118
 119   <!--
 120   A define is named definition of its contents, so that multiple <ref> elements
 121   can refer to it, to avoid copy&paste. OOXML named (complex and simple) types
 122   are described using defines.
 123   -->
 124   <define name="define-element">
 125     <element name="define" ns="http://relaxng.org/ns/structure/1.0">
 126       <attribute name="name"/>
 127       <oneOrMore>
 128         <choice>
 129           <ref name="choice-element"/>
 130           <ref name="attribute-element"/>
 131           <ref name="element-element"/>
 132           <ref name="data-element"/>
 133           <ref name="ref-element"/>
 134           <empty/>
 135         </choice>
 136       </oneOrMore>
 137     </element>
 138   </define>
 139
 140   <!--
 141   A reference to a define.
 142   -->
 143   <define name="ref-element">
 144     <element name="ref" ns="http://relaxng.org/ns/structure/1.0">
 145       <attribute name="name"/>
 146     </element>
 147   </define>
 148
 149   <!--
 150   A grammar is a set of defines, one grammar is equivalent to one .xsd file
 151   from the OOXML spec.
 152   -->
 153   <define name="grammar-element">
 154     <element name="grammar" ns="http://relaxng.org/ns/structure/1.0">
 155       <attribute name="ns"/>
 156       <optional>
 157         <attribute name="attributeFormDefault"/>
 158       </optional>
 159       <zeroOrMore>
 160         <ref name="include-element"/>
 161       </zeroOrMore>
 162       <oneOrMore>
 163         <ref name="define-element"/>
 164       </oneOrMore>
 165     </element>
 166   </define>
 167
 168   <!--
 169   Controls the resolution of <ref> elements. The order is:
 170
 171   - the current grammar
 172   - included grammars, if there are any
 173   - the first define in the whole model
 174   -->
 175   <define name="include-element">
 176     <element name="include" ns="http://relaxng.org/ns/structure/1.0">
 177       <attribute name="href"/>
 178     </element>
 179   </define>
 180
 181   <!--
 182   Second part: custom markup, building on top of the first one.
 183
 184   The order of elements in this part follow a top-down approach.
 185
 186   The output of the code generated from these elements is a token stream. There
 187   are two types of tokens: SPRM tokens and attribute ones. SPRM refers to
 188   Single PRoperty Modifier, in this context it means a token that contains other
 189   tokens. It's used to represent an XML element. That means that SPRM tokens
 190   can contain other SPRM tokens, and also attribute tokens, while attribute
 191   tokens only contain simple types (boolean, integer, string).
 192
 193   More terminology: the types in the OOXML schema have two typical prefixes:
 194
 195   - CT_something: complex type, used to describe an XML element
 196   - ST_something: simple type, used to describe the contents of an attribute
 197
 198   For tokens the following abbreviations are used:
 199
 200   - NS_something: namespace
 201   - LN_something: local name
 202   -->
 203
 204   <!--
 205   The model element is the toplevel container for the XML element /
 206   attribute mapping definition. It contains namespace aliases, direct token
 207   definitions and mapping definitions for each namespace.
 208   -->
 209   <define name="model-element">
 210     <element name="model">
 211       <oneOrMore>
 212         <ref name="token-element"/>
 213       </oneOrMore>
 214       <oneOrMore>
 215         <ref name="namespace-element"/>
 216       </oneOrMore>
 217     </element>
 218   </define>
 219
 220   <!--
 221   A token element can explicitly define a token. This allows generating
 222   such a token in the tokenizers and handling it in the domain mapper. Ideally
 223   tokens are *not* defined this way, they are mapped to an XML element or
 224   attribute from the OOXML specification.
 225   -->
 226   <define name="token-element">
 227     <element name="token">
 228       <!--
 229       The token name must be ooxml:something, then in C++ it'll be the
 230       NS_ooxml::LN_something ("OOXML namespace, something local name")
 231       constant.
 232       -->
 233       <attribute name="tokenid"/>
 234     </element>
 235   </define>
 236
 237   <!--
 238   A namespace element is a container for a subset of the relax-ng grammar
 239   of a part of the OOXML specification. It also contains the resource
 240   definitions, which specify how XML elements and attributes are mapped to
 241   tokens.
 242   -->
 243   <define name="namespace-element">
 244     <element name="namespace">
 245       <attribute name="name"/>
 246       <zeroOrMore>
 247         <ref name="start-element"/>
 248       </zeroOrMore>
 249       <ref name="grammar-element"/>
 250       <zeroOrMore>
 251         <ref name="resource-element"/>
 252       </zeroOrMore>
 253     </element>
 254   </define>
 255
 256   <!--
 257   A start element is similar to the relax-ng start element, but this one has a
 258   name attribute to refer to a define, while the relax-ng one has a ref child
 259   element to do the same.
 260   -->
 261   <define name="start-element">
 262     <element name="start">
 263       <attribute name="name"/>
 264     </element>
 265   </define>
 266
 267   <!--
 268   A resource element always matches (by its name attribute) a define from the
 269   grammar of the namespace. It describes how that (simple or complex) type is
 270   parsed during import.
 271
 272   Example:
 273
 274   <resource name="CT_Font" resource="Properties">
 275     ...
 276   </resource>
 277
 278   or
 279
 280   <resource name="CT_OMathPara" resource="Stream"/>
 281   -->
 282   <define name="resource-element">
 283     <element name="resource">
 284       <!-- There should be a define element with the same name attribute. -->
 285       <attribute name="name"/>
 286       <!--
 287       This means the resource element will be handled by the
 288       OOXMLFastContextHandler<resource> class.
 289
 290       The two most important resources:
 291
 292       - Properties: this maps elements/attributes to SPRM/attribute tokens
 293       - Stream: If the element itself does not require any special handling,
 294         but the subelements are interesting, use this resource.  If no
 295         explicit resource element is available, then a null context will be
 296         created and the element and all its subelements will be ignored.
 297       -->
 298       <attribute name="resource"/>
 299       <optional>
 300         <attribute name="tokenid"/>
 301       </optional>
 302       <zeroOrMore>
 303         <choice>
 304           <ref name="resource-element-element"/>
 305           <ref name="resource-attribute-element"/>
 306           <ref name="resource-value-element"/>
 307           <ref name="resource-action-element"/>
 308         </choice>
 309       </zeroOrMore>
 310     </element>
 311   </define>
 312
 313   <!--
 314   The <element> child of a <resource> defines what element name will be handled
 315   via what token.
 316
 317   Example:
 318
 319   <element name="charset" tokenid="ooxml:CT_Font_charset"/>
 320
 321   Means the <charset> element will be handled in the sprm() function of the handler
 322   class as a NS_ooxml::LN_CT_Font_charset case. (sprm() is a logging wrapper
 323   around lcl_sprm(), which is the real implementation.)
 324   -->
 325   <define name="resource-element-element">
 326     <element name="element">
 327       <attribute name="name"/>
 328       <attribute name="tokenid"/>
 329     </element>
 330   </define>
 331
 332   <!--
 333   The <attribute> child of a <resource> defines what attribute name will be
 334   handled via what token.
 335
 336   Example:
 337
 338   <attribute name="name" tokenid="ooxml:CT_Font_name"/>
 339
 340   Means the <name> attribute will be handled in the attribute() (real
 341   implementation in lcl_attribute()) function of the handler class as a
 342   NS_ooxml::LN_CT_Font_name case.
 343   -->
 344   <define name="resource-attribute-element">
 345     <element name="attribute">
 346       <attribute name="name"/>
 347       <optional>
 348         <attribute name="tokenid"/>
 349       </optional>
 350       <optional>
 351         <attribute name="action"/>
 352       </optional>
 353     </element>
 354   </define>
 355
 356   <!--
 357   A <value> inside a <resource> defines how to map the string data of a value
 358   to a token. The tokenid attribute defines the token name, the text of the
 359   element defines the string. This is useful in case the value of an attribute
 360   is a choice from a predefined list.
 361   -->
 362   <define name="resource-value-element">
 363     <element name="value">
 364       <attribute name="tokenid"/>
 365       <text/>
 366     </element>
 367   </define>
 368
 369   <!--
 370   An <action> inside a <resource> can perform additional actions in the
 371   following situations:
 372
 373   - start of the element
 374   - end of the element
 375   - character data of the element
 376
 377   The tokenid attribute restricts the action to a particular element.
 378
 379   Example:
 380
 381   <resource name="CT_TxbxContent" resource="Stream">
 382     <action name="start" action="startTxbxContent"/>
 383     <action name="end" action="endTxbxContent"/>
 384   </resource>
 385
 386   That means that when:
 387
 388   - <txbxContent> starts, OOXMLFastContextHandler::startTxbxContent() will be called
 389   - <txbxContent> ends, OOXMLFastContextHandler::endTxbxContent() will be called
 390   -->
 391   <define name="resource-action-element">
 392     <element name="action">
 393       <attribute name="name"/>
 394       <attribute name="action"/>
 395       <optional>
 396         <attribute name="tokenid"/>
 397       </optional>
 398       <optional>
 399         <attribute name="sendtokenid"/>
 400       </optional>
 401       <optional>
 402         <ref name="resource-action-cond-element"/>
 403       </optional>
 404     </element>
 405   </define>
 406
 407   <!--
 408   Some actions take parameters, which can be defined by the <cond> element.
 409
 410   Example:
 411
 412   <resource name="CT_FldChar" resource="Stream">
 413     <action name="start" action="fieldstart">
 414       <cond tokenid="ooxml:CT_FldChar_fldCharType" value="ooxml:Value_ST_FldCharType_begin"/>
 415     </action>
 416   </resource>
 417
 418   That means:
 419
 420   - if the <fldChar> starts with an fldCharType attribute being "begin"
 421   - then perform the "fieldstart" action.
 422   -->
 423   <define name="resource-action-cond-element">
 424     <element name="cond">
 425       <attribute name="tokenid"/>
 426       <attribute name="value"/>
 427     </element>
 428   </define>
 429
 430   <!-- The entry point of the schema. -->
 431   <start>
 432     <ref name="model-element"/>
 433   </start>
 434 </grammar>
 435 <!-- vim: ft=xml shiftwidth=2 softtabstop=2 expandtab:
 436 -->