Creating a new spec

From SVG
Revision as of 05:13, 29 April 2009 by Pdengler (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

To create a new specification or module, you can use the template spec as a model. This is a stripped-down, empty module with some of the more common bits that are needed for an SVG spec.

Template Files

The template folder contains several files:

  • SVG Template: this is the main file, and the only one that's strictly necessary. This document contains normative prose, language features, schemae, and implementation details. This file assumes a single-page spec, though it can be split into multiple pages
  • SVG Template Primer: this is a supplementary file, for providing usage examples, informative prose, rationalization for design decisions, and introductory material for authors.
  • SVG Template Use Cases and Requirements: this is a supplementary file, for providing use cases and requirements for the main specification. It is strongly recommended to have one of these.

Customizing Templates

To reuse and customize the template for your own use, follow the following guidelines:

  • Create a new folder in the "modules" directory, with an appropriate short-name ("fonts", "filters", "layout", "integration", etc.)
  • Copy the desired files into a new directory. You only need to copy those files that you need (for example, you may not wish to have a primer yet, or you may wish to put the use cases and requirements directly in the main spec; note that in general, it is better to have a separate document for use cases and requirements, at least). Don't forget the stylesheets, if you need specific styles beyond those provided in the official W3C stylesheets.
  • Replace instances of the work "Template" or "<em>Template</em>" with the short-name in the file names and in the document itself
  • Edit the document to contain at least an introduction, and as much content as you have available
  • Add and commit the new directory and files into CVS
  • Add a link to the file in the SVG WG wiki under Specifications, and a tentative timeline on the Roadmap
  • Email public-svg-wg (and maybe www-svg) that this is done, for broader review

Build Scripts

Currently, the template is not hooked into the build scripts, because we haven't quite got them in place yet for modules. Therefore, handy things like automatic generation of a table of contents, automatic linking to definitions and such are not yet working. This is normaly fine for smaller specs, but quickly becomes unwieldy for larger specs, especially multi-page specs.

Syntax

When using the build script, you can use the shorthand notation <a>term</a> in the spec to link element names, attribute names, interfaces, methods, keywords, terms, definitions, etc. to their canonical definitions. Here are some rough notes detailing usage:

  • if the type of references is ambiguous you can do <a>'mask element'</a> or <a>'mask property'</a>
  • if it's not ambiguous you can leave out the "element" or " property" bit
  • for attributes, if they're element-specific attributes, and in the definitions.xml you put <attribute name="foo" elements="myElement" href="..."/>
  • in the spec you can do: <edit:with element="myElement"> ... blah blah spec text </edit:with>, so that the attributes for that element are "in scope" for the <a> lookup
  • for interfaces, you omit quotes, such as <a>InterfaceName</a> and <a>InterfaceName::memberName</a>
  • for small specs that only define one element, or don't have any clashing attributes, then you can leave out the elements="myElement" bit on the elt in definitions.xml
    • this effectively means it's a global attribute, but it means you don't need to put that edit:with to get the <a> lookup working properly (for one off references, instead of <edit:with> you can do <a>'myElement/foo'</a>)