SVG2/definitions.xml

From SVG

definitions.xml

The definitions file holds information about elements, attributes, properties, interfaces, grammar symbols and defined terms. The main reason for including information about these things in the definitions file is so that the build system can automatically generate links to them without having to write out a complete link like 

<a href="shapes.html#RectElement"><span class="element-name">'svg'</span></a>

every time you want to reference the <svg> element. But there are various other automatically generated parts of the specification that use the information in this file.

The definitions file for SVG 1.1 Second Edition is quite large, so instead of reproducing it here in its entirety, we will go through selected examples taken from it.

The definitions file is structured with a root <definitions xmlns="http://mcc.id.au/ns/local"> element, inside which there can be any number of the following elements:

  • <element> – information about an element defined in the specification (such as "rect")
  • <elementcategory> – information about a category of elements defined in the specification (such as "filter primitive elements"), used when defining the content model of other elements
  • <attribute> – information about an attribute defined in the specification (such as "id")
  • <attributecategory> – information about a category of attributes defined in the specification (such as "conditional processing attributes"), used when defining the attributes allowed on a given element
  • <property> – information about a CSS property defined in the specification (such as "stroke-width")
  • <interface> – information about a DOM interface defined in the specification (such as "SVGSVGElement")
  • <symbol> – information about grammar symbol defined in the specification (such as "<paint>")
  • <term> – information about term defined in the specification (such as "outermost svg element")

Elements

The <element> element is used to declare information about an element defined in the specification. Here are some examples: 

<element
    name="rect"
    href="shapes.html#RectElement"
    contentmodel="anyof"
    elementcategories="animation, descriptive"
    attributecategories="conditional processing, core, graphical event, presentation, style"
    attributes="externalResourcesRequired, transform"
    interfaces="SVGRectElement">
  <attribute name="x" href="shapes.html#RectElementXAttribute" animatable="yes"/>
  <attribute name="y" href="shapes.html#RectElementYAttribute" animatable="yes"/>
  <attribute name="width" href="shapes.html#RectElementWidthAttribute" animatable="yes"/>
  <attribute name="height" href="shapes.html#RectElementHeightAttribute" animatable="yes"/>
  <attribute name="rx" href="shapes.html#RectElementRXAttribute" animatable="yes"/>
  <attribute name="ry" href="shapes.html#RectElementRYAttribute" animatable="yes"/>
</element>

The name attribute gives the name of the element.

The href attribute gives the link to the element's definition in the spec. In a multi-page spec, like SVG 1.1 Second Edition, this needs to be a link to a particular chapter, as seen here. In a single-page spec, using a bare fragment would be fine.

The contentmodel attribute specifies what elements are allowed to appear as children of the element in a valid document. The value that would be used most commonly is "anyof", which means that zero or more of the elements identified by the elementcategories and elements attributes can appear as childern of the element, in any order. Other values that can be used for the contentmodel attribute are "textoranyof", "oneormoreof", "any" and "text". "any" means that any child content is allowed, "text" means that only text content is allowed, and "textoranyof" and "oneormoreof" mean text interleaved with zero or more, or one or more, of the content model elements, in any order.

The elementcategories attribute identifies categories of elements that are part of this element's content model. It is a comma separate list of element category names, and each of these names must correspond to an <elementcategory name="..."> in the definitions file.

The attributecategories attribute identifies categories of attributes that can appear on this element. It is a comma separated list of attribute category names, and each of these names must correspond to an <attributecategory name="..."> in the definitions file.

The attributes attribute identifies additional single attributes that can appear on this element. It is a comma separated list of attribte names, and each of these names must correspond to an <attribute name="..."> at the top level of the definitions file.

The interfaces attribute identifies which IDL interfaces are implemented by DOM objects for this element type. It is a comma separated list of interface names, and each of these names must correspond to an <interface name="..."> in the definitions file.

The child <attribute> elements identify attributes that appear only on this element. (This is unlike those identified by the attributecategories and attributes attributes, which reference attributes whose definitions are common to multiple elements.) The name attribute gives the name of the attribute, href is the link to the attribute definition, and the animatable attribute specifies whether the attribute is animatable. (The default is animatable="no", so it can be omitted if the attribute is not animatable.)

So even though there are various elements in the specification that have a width attribute, the <rect> element has its particular definition of the attribute at shapes.html#RectElementWidthAttribute. On the other hand, there's only one definition of transform in the spec, so there is only <attribute name="transform"> element defined at the top level of the file, and which elements reference from <element attributes="...">. 

<element
    name="feDiffuseLighting"
    href="filters.html#feDiffuseLightingElement"
    attributecategories="core, style, presentation, filter primitive"
    attributes="in"
    interfaces="SVGFEDiffuseLightingElement">
  <x:contentmodel xmlns="http://www.w3.org/1999/xhtml">Any number of <a>descriptive elements</a>
  and exactly one <a>light source element</a>, in any order.</x:contentmodel>
  <attribute name="surfaceScale" href="filters.html#feDiffuseLightingSurfaceScaleAttribute" animatable="yes"/>
  <attribute name="diffuseConstant" href="filters.html#feDiffuseLightingDiffuseConstantAttribute" animatable="yes"/>
  <attribute name="kernelUnitLength" href="filters.html#feDiffuseLightingKernelUnitLengthAttribute" animatable="yes"/>
</element>

This is an example of an element with a custom content model, specified in HTML prose. (The x prefix there is just bound to http://mcc.id.au/ns/local, like all of the other non-HTML elements in the file.)

Some elements might not have any <attribute> children, since they only allow common attributes on them, like <g> does: 

<element
  name="g"
  href="struct.html#GElement"
  contentmodel="anyof"
  elementcategories="animation, descriptive, shape, structural, gradient"
  elements="a, clipPath, color-profile, cursor, filter, font, font-face, foreignObject, image, marker, mask,
            pattern, script, style, switch, view, text, altGlyphDef"
  attributecategories="conditional processing, core, graphical event, presentation, style"
  attributes="externalResourcesRequired, transform"
  interfaces="SVGGElement"/>

Element categories

Element categories are named groups of elements. They are grouped together to ease specifying the content model of other elements. As an example: 

<elementcategory
  name="container" href="intro.html#TermContainerElement"
  elements="svg, g, defs, symbol, mask, pattern, marker, a, switch, glyph, missing-glyph"/>

This defined an element category named "container", with the given element names in the elements attribute as members. The href is a link to a definition in the spec for that group of elements.

Attributes

Attributes defined at the top level of the definitions file are those that are applicable to multiple elements, and which have a single definition in the spec. For example: 

 <attribute
   name="xlink:href"
   elements="animate, animateColor, animateMotion, animateTransform, set"
   href="animate.html#HrefAttribute"/>

This defines an xlink:href attribute that is applicable to the specified animation elements. Note that the definition for, say, the <set> element specifies that an attribute named xlink:href is allowed by it having "xlink" in its attributecategories attribute: 

<element
    name="set"
    href="animate.html#SetElement"
    contentmodel="anyof"
    elementcategories="descriptive"
    attributecategories="conditional processing, core, animation event, xlink,
                         animation attribute target, animation timing"
    attributes="externalResourcesRequired"
    interfaces="SVGSetElement">
  <attribute name="to" href="animate.html#SetElementToAttribute"/>
</element>

<attributecategory
    name="xlink"
    href="intro.html#TermXLinkAttributes"
    attributes="xlink:href, xlink:show, xlink:actuate">
  <attribute name="xlink:type" href="linking.html#XLinkTypeAttribute"/>
  <attribute name="xlink:role" href="linking.html#XLinkRoleAttribute"/>
  <attribute name="xlink:arcrole" href="linking.html#XLinkArcRoleAttribute"/>
  <attribute name="xlink:title" href="linking.html#XLinkTitleAttribute"/>
</attributecategory>

Attributes that are defined to apply to more than one element like this must be linked both ways: the <attribute> references the elements it can appear on in its elements attribute, and each <element> that allows it must specify it in its attributes attribute or indirectly via its attributecategories attribute.

Attribute categories

Attribute categories are named sets of attributes that are used in defining the allowable attributes on a given element. For example: 

<attributecategory
    name="conditional processing"
    href="intro.html#TermConditionalProcessingAttribute">
  <attribute name="requiredFeatures" href="struct.html#RequiredFeaturesAttribute"/>
  <attribute name="requiredExtensions" href="struct.html#RequiredExtensionsAttribute"/>
  <attribute name="systemLanguage" href="struct.html#SystemLanguageAttribute"/>
</attributecategory>

Elements reference these categories in their attributecategories attributes, as seen in some of the examples above. The name attribute gives the name of the attribute category, and the href attribute gives a link to the definition of the attribute category.

Properties

Properties are defined very simply: 

<property name="fill" href="painting.html#FillProperty"/>

Since any properties can be specified on any stylable element even if they don't apply, there is no need to specify which elements a given property can appear on.

The definitions for stylable elements is done like this: 

<attributecategory
    name="style">
  <attribute name="class" href="styling.html#ClassAttribute" animatable="yes"/>
  <attribute name="style" href="styling.html#StyleAttribute"/>
</attributecategory>

<attributecategory
  name="presentation"
  href="intro.html#TermPresentationAttribute"
  presentationattributes="alignment-baseline, baseline-shift, clip, clip-path,
                          ...
                          unicode-bidi, visibility, word-spacing, writing-mode"/>

<element
    name="path"
    href="paths.html#PathElement"
    contentmodel="anyof"
    elementcategories="animation, descriptive"
    attributecategories="conditional processing, core, graphical event, presentation, style"
    attributes="externalResourcesRequired, transform"
    interfaces="SVGPathElement">
  <attribute name="d" href="paths.html#DAttribute" animatable="yes"/>
  <attribute name="pathLength" href="paths.html#PathLengthAttribute" animatable="yes"/>
</element>

So a stylable element like <path will reference the "presentation" and "style" attribute categories to allow the attribute style, class, fill, stroke, etc. on it.

Notice the use of presentationattributes on the "presentation" attribute category: this is used instead of attributes so that when the attribute table appendix is generated, regular and presentation attributes can be separated. (On <attributecategory name="presentation"> is the only place where there is a presentationattributes attribute.)

Interfaces

Interfaces are listed in the definitions file to associate a link with them, for example: 

<interface name="SVGSVGElement" href="struct.html#InterfaceSVGSVGElement"/>

Grammar symbols

Grammar symbols are also listed in the definitions file to associate a link with them, for example: 

<symbol name="length" href="types.html#DataTypeLength"/>

Terms

Terms are named, prose definitions in the specification that should be linked to whenever the term is mentioned. They are listed in the definitions file like this: 

<term name="local IRI reference" href="intro.html#TermLocalIRIReference"/>
<term name="local IRI references" href="intro.html#TermLocalIRIReference"/>

It is common to have entries for different forms of the term (like singular and plural) so that automatic linking can work for all of those forms.

Importing definitions

It is actually possible to import definitions from another specification's definitions file. This is useful if you are writing a module and wish to have, say, links to SVG 1.1 elements that are not defined in that module.

This isn't actually important until we get specifications other than SVG 2 into the Mercurial repository, so I will describe importing later. --Cameron McCormack 05:36, 23 March 2011 (UTC)

Retrieved from "https://www.w3.org/Graphics/SVG/WG/wiki/index.php?title=SVG2/definitions.xml&oldid=3701"