SVG2/Authoring Guide

Notes for Editing the SVG 2 Specification

Parts of this page originated from Cameron's SVG2/Specification_authoring_guide.

Goal

A clearly written SVG 2.0 specification that also happens to look good.

One can look at other specification for inspiration:

These specifications use variations of a new style sheet.

Working With The Source

The SVG 2 specification is stored in the github.com/w3c/svgwg repository. Changes that are pushed to this repository will also automatically trigger a rebuild of the editor's draft version of the spec on svgwg.org.

No special priviliges are required to clone the spec and to submit pull-requests, however, to be able to push changes directly to the main repository one must first be added to w3c organization group on github. This is administered by the w3c staff contact(s).

To get a local copy of the spec to work with, first make sure you have git setup correctly by following the instructions here.

If you are a member of the working group, then get yourself a local copy of the repository:

   git clone https://github.com/w3c/svgwg.git

If you're an external contributor (as in, not a member of the svg working group) you may still submit your changes via a github pull-request.

The files in the repository contain a lot of special processing instructions to generate and modify their contents, making them unsuitable for consumption by end users. The actual specification documents are created by running the command make which uses the Makefile found in the top level directory. This creates the build/publish directory. Everything in the publish directory is created running make, so never modify this directory by hand. The top-level directory tools, contains all the necessary file and Java code for doing the conversion.

Converting the the source files to the publish version inserts a number of things:

section numbers,
links,
generated content (via items in the 'edit' name space).

These things are covered in detail by the SVG2/Processing page and in the sections below.

It is a good idea to scan the linking sections on the SVG2/Processing page before editing text.

After checking in your changes, you can see the fruits of your labor at [[1]].

Git commands for the novice

git status — Returns status of your local repository.
git pull — Updates local repository from remote repository.
git pull --rebase — Updates local repository moving any local commits after any pulled commits. Good for keeping things in order when you push your commits.
git add — Add files to the list that will be commited.
git commit — Commit your changes locally (after adding).
git push — Push your locally commited changes to remote repository.
git remote -v — Shows remote repository (should be: origin https://github.com/w3c/svgwg.git).
git checkout filename — Reverts 'filename' to repository version.
git stash — Move changes in directory out of the way (in order to 'pull' in changes).
git stash pop — Restore changes stashed by 'git stash'.

The 'Master' Directory

Inside the master directory, there is one XHTML source file for each chapter of the source as well as the special files publish.xsl, definitions.xml, and svg.idl. There are also two subdirectories, one for images and one for style.

Chapter Source Files

These files are basic XHTML with some mark-up using the 'edit' name space. (This namespace URI is a legacy from the SVG 1.2 Tiny build system, from where these processing elements originate.) The file publish.xsl in the 'svg2-tools' repository contains the XSL templates used to expand the mark-up.

publish.xml

The publish.xml file contains instructions to the build system on how the specification is structured and how it is to be built. It included data such as the specification name, maturity, version number, chapter and appendix lists.

definitions.xml

The definitions.xml 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. How to link to the various items is discussed on the SVG2/Processing page and in the sections below.

In addition to its use in link generation, this file is used to generate other parts of the specification.

This file is documented in detail on the SVG2/definitions.xml page. Here is a quick summary of the sections in this file (in file order):

Elements with their attributes
Element categories
Attributes shared between multiple elements
Attribute catagories
Properties
Interfaces
Grammar symbols
Terms
Interfaces defined in other specification.

svg.idl

This file contains the IDL for the SVG specification.

Images Directory

This directory contains images. Most images are in sub-directories organized by chapter. Please do not put random images in this directory. Suggested styling for images is discussed in the Figures section below.

Style Directory

This directory contains a number of CSS style sheets as well as a number of fonts which are used with the svg-style-print.css style sheet.

Style Sheets

There are several style sheets available with the SVG 2 HTML pages:

default_svg.css: A custom SVG 2 style sheet that references a style sheet from the CSS3 Values specification. All SVG specific styles are defined in this sheet.
default_no_issues.svg: Same as default_svg.css but with issues and annotations hidden.
default.css: CSS3 style sheet without SVG stuff added.
svg_style.css: The SVG 1.1 style sheet.

The custom SVG 2 style sheet adds styling for:

Annotations.
Element names, element summary, etc.
Attribute and property names and values.
IDL items.
Unreviewed/ready for review backgrounds.
Etc.

The appropriate W3C style sheet (e.g. Editors' Draft) is automatically inserted by the build scripts after the above style sheets.

General Items

Chapter or Appendix

To add a new chapter or appendix: create a new XHTML file with the chapter or appendix name. Add the chapter or appendix file name to publish.xml in the appropriate place. The following shows the structure of a chapter or appendix file:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional+edit//EN" "xhtml1-transitional+edit.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:edit="http://xmlns.grorg.org/SVGT12NG/">
<head>
  <title>Paint Servers: Solid Colors, Gradients, and Patterns</title>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <link rel="stylesheet"           title="Default"               type="text/css" media="screen" href="style/default_svg.css"/>
  <link rel="alternate stylesheet" title="No issues/annotations" type="text/css" media="screen" href="style/default_no_issues.css"/>
  <link rel="alternate stylesheet" title="CSS3 Unmodified"       type="text/css" media="screen" href="style/default.css"/>
  <link rel="alternate stylesheet" title="SVG 1.1"               type="text/css" media="screen" href="style/svg-style.css"/>
  <!-- W3C style sheet will be added here during processing. -->
</head>
<body>

<h1>Chapter Title</h1>

<p>Some body text.</p>

<h2 id="SectionID">A section in the chapter.</h2>

<p>More text.</p>

<h2 id="AnotherSectionID">Another section.</h2>

...

</body>
</html>

Note that this is an XML document with two name spaces. The XSL templates will determine the final document type.

The table of contents in a chapter is generated automatically below the <h1> element without a need to include a special processing element.

To avoid unnecessary waste of horizontal space, direct child elements of <body> should be placed in column 1.

Section

To add a new section, include a header (<h2> – <h6>) with the new section name. The header must include an 'id' which is used for linking. Example:

 <h2 id="SectionID">Section Title</h2>

Section numbers are generated automatically for <h2> – <h6> elements, and no additional mark-up is required for this.

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 specification 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.

Figure

Figures are inserted by using the following syntax:

<div class="figure">
  <img alt="..." src="..."/>
  <p class="caption">
    My caption.
  </p>
</div>

Note that this is a different syntax from that used in the SVG 1.1 specification. Figures are automatically numbered.

It has been asked if the specification should use SVG figures. The problem with this is that many figures will be of features not yet included in browsers (or rendered correctly by them). It might be interesting to include both PNG and SVG versions of each figure, with the SVG figure being shown or hidden depending on the style sheet.

In the interest of uniformity, it is recommended that major figures be 600px wide (nominally 600px x 300px) and minor figures 300px wide (nominally 300px x 150px) with a default text size of 20px and a default stroke width of 2px (this also ensures pixel alignment).

Example

Examples come in two types: with and without the SVG source.

Without SVG source

Examples without SVG source are included by a <div> with the class "example".

With SVG source

Examples with SVG source are added by using the element: <edit:example> which gets expanded via XSL. This element has the following attributes:

href	Reference to SVG image.
name	Name of example.
description	Description (the <desc> inside the SVG is not used).
image	If an image should be include: "yes\|no".
link	If a link should be included to the SVG file: "yes\|no".

Examples should have a sensible title in the <title> element and a sensible description if the <desc> element.

Note

Notes are intended for non-normative text that will remain in the published specification.

Use for:

Marking additions to or changes from the SVG 1.1 specification.
Motivation for a new feature.
etc.

Notes are included by adding the class "note" to a <div>, <p>, or, <span>.

Issue

Issues are intended for open issues and editorial remarks that are not for final publication. Note that the number at the start of an issue is auto-generated and is intended to aid discussion (during conference calls, for example). If an issue is in the tracker, add a link to it.

Use for:

Open issues.
Inconsistencies.
Formatting problems.
etc.

Issues are included by adding the class "issue" to a <div>, <p>, or, <span>.

Annotation

Annotations are intended to keep a history of the development of the specification to help future editors understand why the specification is the way it is. They are intended to be kept in the specification but hidden for final publication.

Use for:

Links to resolutions.
Explanations of editing decisions.
etc.

Annotations are included by adding the class "annotation" to a <div>, <p>, or, <span>.

SVG Specification Items

Element

To add a new element, the following files must be edited:

The appropriate chapter file,
definitions.xml,
svg.idl.

See Linking to elements, attributes, and properties for details on adding links to element definitions.

Adding an element to a chapter

The general structure for an element is as follows:


<hn id="AnElement">An Element</hn>

<edit:with element='anElement'>

  <p id="anElement">
    AnElements are defined by a <a>'anElement'</a> element.
  </p>

  <edit:elementsummary name='anElement'>

  <hn+1 id="AnElementAttributes">Attributes</hn+1>

  <dl class="attrdef-list">

    <dt id="anElementAttributeAAttribute">
      <span class="adef">attributeA</span>
    </dt>
    <dd>

      <p>
        Description of attribute A.
      </p>

      <dl class="attrdef">

	<dt>Value</dt>                <dd>value1 | value2</dd>
	<dt><a>Lacuna value</a></dt>  <dd>value1</dd>
	<dt><a>Animatable</a></dt>    <dd>yes</dd>

      </dl>

      <dl class="attrdef-values">

        <dt>value1</dt>
        <dd>Explanation of <span class="attr-value">value1</span>.</dd>

        <dt>value2</dt>
        <dd>Explanation of <span class="attr-value">value2</span>.</dd>

      </dl>

    </dd>

    Additional attributes.

  </dl><!-- Attribute list -->

  <hn+1 id="AnElementParameters">Parameters</hn+1>

  Parameters (see below).

  <hn+1 id="AnElementNotes">Some notes on anElements.</hn+1>

  More explanations. figures, examples.

</edit:with>

The XML processor will expand a number of items here:

<edit:with element='anElement'>: This provides a context for attributes lookups when an attribute occurs in multiple elements.
<edit:elementsummary name='anElement'/>: Inserts the "blue box" summary for an element based on the element data in definitions.xml.
Terms surrounded by <a></a> pairs (without href values, e.g. <a>'anElement'</a>) will be expanded to include links. Terms that should be included this way include element names, attribute names, data types, and "inherit".

Note the formats of the 'id' of both the initial <p> element and the <dt> elements. These formats ensures a consistent naming system for incoming links.

Add an element to definitions.xml

A new element is normally added three different places in the definitions.xml file. The first place is in the list of <element> tags, the second in a list <elementcatagories>, and finally in an <interface> list.

<element>

The <element> entry summarizes the structure of the element including name, content model, element categories, attributes, and interfaces. The XSL processor will turn this entry into the 'blue boxed' element summary that appears in the specification.

See SVG2/definitions.xml#Elements for complete instructions on how to add this section.

<elementcatagory>

If the new element shares a content model with other elements then add it to the corresponding element category:

  <elementcategory name='category' href='chapter.html#TermCategoryElement'
    elements='anElement, someOtherElement, ...'/>

<interface>

Include an entry for linking to the element's interface:

  <interface name='SVGAnElementElement' href='chapter.html#InterfaceSVGAnElementElement'/>

Adding an element to svg.idl

The element entry in the svg.idl file will appear in the DOM Interfaces section of the corresponding chapter.

Add an entry for the new element grouped with related elements. The minimal format for a new element with the name 'anElement' is:

  /**
   * The <a>SVGAnElementElement</a> interface corresponds to the
   * <a>'anElement'</a> element.
   */
  interface SVGAnElementElement : SVGElement {

   List of types.
   List of attributes.
   List of functions.

};

Note that the comment will appear as text in the specification.

An element may inherit from more than one interface, in which case a list of interfaces can be given:

  interface SVGAnElementElement : 
                SVGElement,
                SVGTests,
                SVGLangSpace,
                SVGExternalResourcesRequired,
                SVGStylable {

Attribute

To add a new property, the following files must be edited:

The appropriate chapter file,
definitions.xml,

See Linking to elements, attributes, and properties for details on adding links to attribute definitions.

Adding an attribute to a chapter

Add the attribute under the appropriate element. See the above adding an element section.

The SVG 1.1 Specification separates paragraphs within an attribute definition by using <br/>. This makes the attributes definitions hard to read. Instead, please wrap paragraphs with the <p> element.

Suitable styling for attributes is being studied.

Property

To add a new property, the following files must be edited:

The appropriate chapter file,
definitions.xml,
property.xml.

See Linking to elements, attributes, and properties for details on adding links to property definitions.

Adding a property to a chapter

The general structure for a property is as follows:

  <h4 id="AnElementProperties">Properties</h4>

  <dl class="propdef-list">

    <dt id="PropertyAProperty"><span class="propdef-title prop-name">'property-a'</span></dt>
    <dd>

      <p>
	The <a>'property-a'</a> property ....
      </p>

      <dl class="propdef">
	<dt>Value</dt>
        <dd>
          <a>value1</a> | <a>value2</a> | <a class="noxref">inherit</a>
	</dd>
        <dt>Initial</dt>            <dd>value1</dd>
        <dt>Applies to</dt>         <dd><a>'anElement'</a> elements</dd>
        <dt>Inherited</dt>          <dd>no</dd>
        <dt>Percentages</dt>        <dd>N/A</dd>
        <dt>Media</dt>              <dd>visual</dd>
        <dt><a>Animatable</a></dt>  <dd>yes</dd>
      </dl>

      <dl class="propdef-values">  <!-- If not defined elsewhere. -->
	<dt><value1></dt>
	<dd>
	  The value1 is ...
	</dd>

        More values.

      </dl>
    
    </dd>

    More properties.

  </dl>

Note that SVG1.1 uses cellspacing, cellpadding, and valign which are obsolete. Existing tables will need to be updated. The SVG 2 specification uses a definition list with styling done by CSS. The structure between properties and attributes has been unified.

Adding a property to definitions.xml

A new property is normally added two different places in the definitions.xml file. The first place is in the attribute category 'presentation', the second in a list of properties.

<attributecategory name='presentation' ...>

Just add the new property in alphabetic order to the existing 'presentationattibutes' list.

<property>

Just add the new property in alphabetic order.

  <property name='property-a' href='chapter.html#PropertyAProperty' />

Adding a property to property.xml

Add a new <tr> row for the property (in alphabetic order). The table data is in the order:

Property name
Possible values
Initial value
Elements it applies to
Inherited
Percentages
Media
Animatable
shouldn't there be Computed Value as well?

  <tr>
    <td><a>'property-a'</a></td>
    <td>
      <a><DataType1></a>|<br />
      <a><DataType2></a>|<br />
      <a class="noxref">inherit</a>
    </td>
    <td>InitialValue</td>
    <td><a>'anElement'</a> elements</td>
    <td>no</td>
    <td>N/A</td>
    <td><a
      href="http://www.w3.org/TR/2008/REC-CSS2-20080411/media.html#visual-media-group">
      visual</a></td>
    <td>yes</td>
  </tr>

Note, the data types and "inherit" will have links added when the files are processed.

This file should be but is not yet generated by script.

Interface

And new interfaces in the appropriate chapter.

Add new interfaces at the end of definitions.xml.

Grammar Symbol

Add new grammar symbols to the symbol section of definitions.xml (near the bottom of the file). Grammar symbols are placed alphabetically.

Term

Add new terms to the term section of definitions.xml (near the bottom of the file). Terms are placed alphabetically in groups of related terms.