SVG2/Authoring Guide

From SVG
Jump to: navigation, search

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 dvcs.w3.org svg2 Mercurial repository. Direct writing to this repository is not allowed. Instead, specification authors are required to use the repository at svgwg.org. Changes to the svgwg.org repository will, after some checks, be forwarded to the dvcs.w3.org repository. Instructions for getting and working with the source can be found on the Svgwg.org wiki page.

The svgwg.org repository contains the directory master with the source files for the specification. These files 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 publish directory. Everything in the publish directory is created running make, so never modify this directory by hand. A second repository, svg2-tools, contains all the necessary file and Java code for doing the conversion. The main file of interest in svg2-tools is publish.xsl which contains templates for the XSL processor.

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

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):

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:

hrefReference to SVG image.
nameName of example.
descriptionDescription (the <desc> inside the SVG is not used).
imageIf an image should be include: "yes|no".
linkIf 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.