View source for SVG2/definitions.xml

==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

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

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

The [http://dev.w3.org/SVG/profiles/1.1F2/master/definitions.xml 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 <tt>&lt;definitions xmlns="http://mcc.id.au/ns/local"></tt>
element, inside which there can be any number of the following elements:

* <tt>&lt;element></tt> – information about an element defined in the specification (such as "rect")
* <tt>&lt;elementcategory></tt> – information about a category of elements defined in the specification (such as "filter primitive elements"), used when defining the content model of other elements
* <tt>&lt;attribute></tt> – information about an attribute defined in the specification (such as "id")
* <tt>&lt;attributecategory></tt> – 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
* <tt>&lt;property></tt> – information about a CSS property defined in the specification (such as "stroke-width")
* <tt>&lt;interface></tt> – information about a DOM interface defined in the specification (such as "SVGSVGElement")
* <tt>&lt;symbol></tt> – information about grammar symbol defined in the specification (such as "&lt;paint>")
* <tt>&lt;term></tt> – information about term defined in the specification (such as "outermost svg element")

===Elements===

The <tt>&lt;element></tt> 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
<tt>&lt;elementcategory name="..."></tt> 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
<tt>&lt;attributecategory name="..."></tt> 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
<tt>&lt;attribute name="..."></tt> 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
<tt>&lt;interface name="..."></tt> in the definitions file.

The child <tt>&lt;attribute></tt> 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 <tt>animatable="no"</tt>, 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 <tt>&lt;rect></tt> 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 <tt>&lt;attribute name="transform"></tt> element
defined at the top level of the file, and which elements reference from
<tt>&lt;element attributes="..."></tt>.

 <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 <tt>x</tt> 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 <tt>&lt;attribute></tt> children, since they
only allow common attributes on them, like <tt>&lt;g></tt> 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 <tt>&lt;set></tt>
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 <tt>&lt;attribute></tt> references the elements it
can appear on in its '''elements''' attribute, and each <tt>&lt;element></tt>
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 <tt>&lt;path</tt> 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 <tt>&lt;attributecategory name="presentation"></tt>
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. --[[User:Cmccorma|Cameron McCormack]] 05:36, 23 March 2011 (UTC)''