Processing instructions

Some forms of markup cause the build system to do some special processing. This section documents all of them.

Section numbers

Section numbers are generated automatically for <h2> – <h6> elements, and no additional markup is required for this. Every section header element must have an ID, since it will be linked to from the chapter's Table of Contents (as well as the Extended Table of Contents). An ID isn't generated for you.

Linking to sections

Linking to other sections must be done manually, like the following:

<p>For further details, see the
<a href="types.html#BasicDataTypes">Basic data types</a>
section.</p>

Make sure you use a relative link like this. (The script that generates the single page version of the spec does a bunch of ID rewriting for uniqueness, and will automatically rewrite links like the above.) For links within the current chapter, a bare fragment is fine too.

Linking to elements, attributes and properties

Most of the magic that the build system can do is generating links for you.

To link to the definition of an element, attribute or property, you write <a>'blah'</a>, where blah is the name of the thing you are linking to. For example:

<p>You can use the <a>'rect'</a> element to draw rectangles.</p>
<p>Specify a <a>'class'</a> attribute on it to give it a CSS class.</p>
<p>I like to set the <a>'stroke-width'</a> to <span class="prop-value">4px</span>.</p>

These use the definitions file to generate the value of the href attribute and the styling of the link.

Sometimes it will be ambiguous as to whether the link should be to an element, an attribute or a property. For example if you write:

<p>Here is an example that uses <a>'mask'</a>.</p>

then it is unclear whether that should be a link to the <mask> element or the 'mask' property. In most cases, when the link would be ambiguous, the build system will emit an error message and stop the build. In that case you need to explicitly disambiguate it:

<p>Here is an example that uses <a>'mask property'</a>.</p>

or

<p>Here is an example that uses <a>'mask element'</a>.</p>

When referencing an attribute that is not specific to any particular element, such as class, then writing <a>'class'</a> will be sufficient. Many attributes, though, have specific definitions for a particular element. In those cases, say for the width attribute on <rect>, then writing the following will cause the build system to stop with an error:

<p>The <a>'width'</a> attribute is the width of the rectangle.</p>

There are two ways to solve this. One is to specify which element the attribute is on:

<p>The <a>'rect/width'</a> attribute is the width of the rectangle.</p>

(The "rect/" part of the text there won't appear in the output; the generated link will look like ‘width’.)

The second way is to surround a section with an <edit:with> element that provides the context for attribute lookups:

<edit:with element="rect">

<h2 id="RectAttributes">The attributes you can stick on <span class="attr-name">rect</span></h2>
<p>The <a>'width'</a> and <a>'height'</a> attributes are used to specify the
size of a rectangle.</p>

...
</edit:with>

This can be handy for sections that define a given element, so that you don't need to continually specify the <a>'elementname/attributename'</a> form. (Most element definition sections in the specification are already surrounded with a corresponding <edit:with> element.)

Linking to interfaces and interface members

DOM interfaces can be linked to in a similar manner, like so:

<p>All <a>'rect'</a> elements implement the <a>SVGRectElement</a> interface.</p>

Linking to members of an interface (their operations, attributes or constants) is done like so:

<p>To get the bounding box of a shape, call the <a>SVGLocatable::getBBox</a> method.</p>

The href attribute of the corresponding <interface> element in the definitions file will be used as the link.

Linking to grammar symbols

Grammar symbols are linked to like this:

<p>The <a>'stroke-width'</a> property takes a <a>&lt;length></a> value.</p>

The href attribute of the corresponding <symbol> element in the definitions file will be used as the link.

Linking to terms

Terms are linked to like this:

<p>All <a>container elements</a> can have <a>graphical elements</a> as children.</p>

The exact textual contents of the <a> is matched against the name attribute of the <term> elements in the definitions file to find the href value to use.

There's no way currently to link to a term automatically while using a variation of the wording that doesn't appear in the definitions file.

Simple substitutions

A number of <edit:*> elements are used to insert some generated content into the document, many of which you don't need to use in the main body of the specification. Here are the important ones:

<edit:interface name="interface name"/>

This is used in the body of the specification to insert the IDL for a given interface along with the definitions of its operations, attributes and constants.

<edit:example href="images/chapter/example-filename.svg name="example-name" description="..." link="yes|no" image="yes|no"/>

This is used to include an example from an external example file. The href link is to the SVG file, and it is relative to the top level specification directory. Most examples are in a directory named images/blah/ where "blah" is the chapter name.

The name attribute is a short string identifying the example, and seems to be normally the same as the base name of the actual SVG file.

The description attribute gives a short description of the example, which will be included just below the example.

The link attribute is used to control whether a link to the external SVG example file will be included.

The image attribute is used to control whether the PNG rendering of the example (which must be at the same location as the href but ending with ".png" instead of ".svg") is included below the example listing.

<edit:includefile href="filename"/> – used to insert the plain text contents of a file.

<edit:elementsummary name="element name"/> – used to insert the blue box summary for an element.

<edit:locallink href="some file"/> – used to generate an absolute URL for a file distributed with the specification. For example, it is used in the idl.html appendix to generate the absolute URL for the SVG IDL file, like this:

<pre><edit:locallink href="svg.idl"/></pre>

The final output looks like:

<pre><a href="http://www.w3.org/2011/WD-SVG11-20110123/svg.idl">http://www.w3.org/2011/WD-SVG11-20110123/svg.idl</a></pre>

The following are less commonly used:

<edit:elementcategory name="element category name"/> – used in various parts of the specification to generate the list of elements that are part of the given category. For example, in intro.html, there is:

<dt id="TermFilterPrimitiveElement">filter primitive element</dt>
<dd>A filter primitive element is one that can be used as a child of a
<a>'filter element'</a> element to specify a node in the filter graph.
The following elements are the filter primitive elements defined
in SVG 1.1: <edit:elementcategory name="filter primitive"/>.</dd>

<edit:attributecategory name="attribute category name"/> – used in various parts of the specification to generate the list of elements that are part of the given category. For example, in intro.html, there is:

<dt id="TermFilterPrimitiveAttributes">filter primitive attributes</dt>
<dd>The filter primitive attributes is the set of attributes that are common
to all <a>filter primitive elements</a>.  They are
<edit:attributecategory name="filter primitive"/>.</dd>

<edit:elementswithattributecategory name="attribute category name"/> – used to generate a list of elements that are defined to allow attributes in a given category. It is used in a couple of places, such as in the attribute table appendix to generate the list of elements on which presentation attributes can be specified. <edit:minitoc/> – used in index.html to insert the front page table of contents.

<edit:fulltoc/> – used in expanded-toc.html to insert the full table of contents.

<edit:completeidl/> – used in the idl.html appendix to insert the entire IDL (without interface descriptions), with links to the definitions for each interface and interface member.

<edit:maturity/> – used in the header of index.html to include the full maturity level string for the document, such as "Working Draft". The maturity is taken from the <maturity> element in publish.xml.

<edit:date/> – used in the header of index.html to include the publication date of the document in the format "dd MMMM yyyy". This is taken from information in publish.xml, as described above.

<edit:thisversion/> – used in the header of index.html to include the "This version" link of the specification.

<edit:latestversion/> – used in the header of index.html to include the "Latest version" link of the specification.

<edit:previousversion/> – used in the header of index.html to include the "Previous version" link of the specification.

<edit:copyright/> – used in the header of index.html to generate the correct copyright string for the document based on the year of the publication date.

<edit:attributetable/> – used in the attribute table appendix to generate the table of attributes and which elements they can be specified on.

Other things current unexplained

edit:toc="no" attribute
edit:format="expanded" attribute