View source for 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:

*[http://www.w3.org/TR/css3-fonts/ CSS Fonts Module Level 3]
*[http://dev.w3.org/csswg/css3-values/ CSS Values and Units Module Level 3]
*[http://dev.w3.org/csswg/css3-transforms/ CSS Transforms]
*[https://dvcs.w3.org/hg/FXTF/raw-file/0ae665082f8d/custom/index.html CSS Shaders]

These specifications use variations of a new style sheet.

== Working With The Source ==

The SVG 2 specification is stored in the ''[https://github.com/w3c/svgwg 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 [https://svgwg.org/ 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 [https://help.github.com/articles/set-up-git/#platform-all 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 [https://help.github.com/articles/using-pull-requests/ 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 ''[https://github.com/w3c/svgwg/tree/master/tools 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.

<div class="note" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #52E052; background: #E9FBE9">
It is a good idea to scan the linking sections on the [[SVG2/Processing]] page before editing text.
</div>

After checking in your changes, you can see the fruits of your labor at [[https://svgwg.org/svg2-draft/]].

=== Git commands for the novice ===

* git status &mdash; Returns status of your local repository.
* git pull &mdash; Updates local repository from remote repository.
* git pull --rebase &mdash; Updates local repository moving any local commits after any pulled commits. Good for keeping things in order when you push your commits.
* git add &mdash; Add files to the list that will be commited.
* git commit &mdash; Commit your changes locally (after adding).
* git push &mdash; Push your locally commited changes to remote repository.
* git remote -v &mdash; Shows remote repository (should be: origin https://github.com/w3c/svgwg.git).
* git checkout filename &mdash; Reverts 'filename' to repository version.
* git stash &mdash; Move changes in directory out of the way (in order to 'pull' in changes).
* git stash pop &mdash; 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 ''[[SVG2/definitions.xml|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

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

* [[SVG2/definitions.xml#Elements|Elements]] with their attributes
* [[SVG2/definitions.xml#Element categories|Element categories]]
* [[SVG2/definitions.xml#Attributes|Attributes]] shared between multiple elements
* [[SVG2/definitions.xml#Attribute categories|Attribute catagories]]
* [[SVG2/definitions.xml#Properties|Properties]]
* [[SVG2/definitions.xml#Interfaces|Interfaces]]
* [[SVG2/definitions.xml#Grammar symbols|Grammar symbols]]
* [[SVG2/definitions.xml#Terms|Terms]]
* [[SVG2/definitions.xml#Importing definitions|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 <tt>svg-style-print.css</tt> 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.

<div class="note" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #52E052; background: #E9FBE9">
The appropriate W3C style sheet (e.g. Editors' Draft) is automatically inserted by the build scripts after the above style sheets.
</div>

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

 <pre>
<?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>
</pre>

<div class="note" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #52E052; background: #E9FBE9">
Note that this is an XML document with two name spaces. The XSL templates will determine the final document type.
</div>

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

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

=== Section ===

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

  &lt;h2 id="SectionID"&gt;Section Title&lt;/h2&gt;

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

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

 &lt;p>For further details, see the
 &lt;a href="types.html#BasicDataTypes">Basic data types&lt;/a>
 section.&lt;/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 ===

<div class="figure" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #E0CB52; background: #FCFAEE;">

Figures are inserted by using the following syntax:
<pre>
&lt;div class="figure"&gt;
  &lt;img alt="..." src="..."/&gt;
  &lt;p class="caption"&gt;
    My caption.
  &lt;/p&gt;
&lt;/div&gt;
</pre>

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

</div>

=== Example ===

<div class="example" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #E0CB52; background: #FCFAEE; width: 100%">

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

==== Without SVG source ====

Examples without SVG source are included by a &lt;div&gt; with the class "example".

==== With SVG source ====

Examples with SVG source are added by using the element: &lt;edit:example&gt; which gets
expanded via XSL. This element has the following attributes:

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

Examples should have a sensible title in the &lt;title&gt; element
and a sensible description if the &lt;desc&gt; element.

</div>

=== Note ===

<div class="note" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #52E052; background: #E9FBE9">

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 &lt;div&gt;,  &lt;p&gt;, or,  &lt;span&gt;.

</div>

=== Issue ===

<div class="issue" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #E05252; background: #FBE9E9; counter-increment: 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 &lt;div&gt;,  &lt;p&gt;, or,  &lt;span&gt;.

</div>

=== Annotation ===

<div class="annotate" style="text-indent: 0; margin-bottom: 0; margin-top: 1em; padding: 0.5em; border-left-width: .5em; border-left-style: solid; border-color: #C752E0; background: #F8E9FB; counter-increment: 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 &lt;div&gt;,  &lt;p&gt;, or,  &lt;span&gt;.

</div>

== SVG Specification Items ==

=== Element ===

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

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

See [[SVG2/Processing#Linking to elements, attributes and properties|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:
 <nowiki>

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

&lt;/edit:with&gt;
</nowiki>

The XML processor will expand a number of items here:

* &lt;edit:with element='anElement'&gt;: This provides a context for attributes lookups when an attribute occurs in multiple elements.
* &lt;edit:elementsummary name='anElement'/&gt;: Inserts the "blue box" summary for an element based on the element data in ''definitions.xml''.
* Terms surrounded by &lt;a&gt;&lt;/a&gt; pairs (without href values, e.g. &lt;a&gt;'anElement'&lt;/a&gt;) 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 &lt;p&gt; element and the &lt;dt&gt; 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 &lt;element&gt; tags, the second in a list &lt;elementcatagories&gt;, and finally in an &lt;interface&gt; list.

===== &lt;element&gt; =====

The &lt;element&gt; 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.

===== &lt;elementcatagory&gt; =====

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

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

===== &lt;interface&gt; =====

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

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

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

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

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

};
</pre>

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:

 <pre>
  interface SVGAnElementElement : 
                SVGElement,
                SVGTests,
                SVGLangSpace,
                SVGExternalResourcesRequired,
                SVGStylable {
</pre>

=== 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 &lt;br/&gt;. This makes the attributes definitions hard to read. Instead, please wrap paragraphs with the &lt;p&gt; 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 [[SVG2/Processing#Linking to elements, attributes and properties|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:

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

</pre>

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.

===== &lt;attributecategory name='presentation' ...&gt; =====

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

===== &lt;property&gt; =====

Just add the new property in alphabetic order.

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

==== Adding a property to ''property.xml'' ====

Add a new &lt;tr&gt; 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
* <span style="color:red">shouldn't there be Computed Value as well?</span>

 <pre>
  <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>
</pre>

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.