This document describes the stylesheets used by JackSVG. These stylesheets determine how a presentation will be converted into a SVG file. This document is for people who want to create or modify their own stylesheets. You do not need to read this document if you are only creating presentations, and use stylesheets that have already been created.
It is expected that the reader of this document knows how to create SVG images manually by creating XML files. They should also know how to write and create JackSVG presentations.
Warning: This document is currently under construction.
This document is made up of three sections. The first section gives an overview of the structure and layout of the SVG file produced by the slide generation program. It also gives an overview of the stylesheet file.
The second section describes some general concepts used in the stylesheet.
The third section describes each element in the stylesheet in detail.
For further information on how to create stylesheets, see the stylesheet tutorial.
The generated SVG file is structured in a standard way. First comes the header, followed by all the slides, and then the footer. If there is a play stop button, that appears last, after the footer. Anything drawn later in the SVG file is rendered in front; so the slides are drawn on top of the header, the footer on top of the slides.
The slides are each drawn following an internal order. The starting slides appear first, then the content slides, and finally the index slide on top. However, this ordering is not very significant because only one slide is every displayed at any one time.
The slide sequence is viewed by turning on and off the display property of each slide. The SVG code to do this is generated automatically, and is not a concern of the stylesheet writer. What is of concern is where to draw your slide elements. Common items for all slides can be placed in the header, and these will appear behind every slide (unless covered up by something on the slide). Common items can also be placed in the footer, which will always appear in front of every slide (including the index slide).
The items in each slide is drawn in a standard way. Starting with the slide background first (behind everything else), and ending with the foreground last (and in front). These layers are drawn in the following order:
These layers can contain any SVG item you want. Usually, they contain visible elements to be displayed. Choose the layer based on what you want that item to overlap.
The body consists of the main content of the slide. Namely, the bullet points, paragraphs and image elements in the presentation.
For the index slide, the body is the set of thumbnail images. In starting slides, there is no body.
The metadata consists of blocks of text that have been defined in the slide master. For example, to show the slide title and subtitle.
The buttons layer contains the controls for navigating the presentation (e.g. showing the next slide, showing the previous slide, returning to the index slide).
The buttons are usually drawn in front of the foreground. This is the default, since you normally do not want anything else to cover up the navigation controls. However, the positions of the buttons item can be changed by the stylesheet designer. It can be moved to behind any of the other items. This may be useful when you want parts of the buttons to appear behind other items.
Only graphical elements relating to the navigation buttons should be placed in the buttons layer. The contents of this layer is not displayed when the slides are playing in automatic mode. If it needs to be visible, put it in the foreground, midground, or background layers.
In addition to the slides and items on them, there are two special items for the buttons controlling the auto-play mode. These contain the start and stop buttons.
The start button is placed on the index slide. It is placed in front of everything else on the index slide (and in front of the normal navigation buttons). It is hidden when playing starts, and only shown again when playing stops.
The stop button is placed in front of the entire presentation (i.e. in front of anything on the presentation footer). It is not placed inside any slide, but sits above all the slides. It is only displayed when the play mode has been started. It is not displayed at any other time.
The stylesheet is a single XML document that determines how a presention will appear as an SVG file. It contains layout information, display information, and SVG code.
The stylesheet XML document has a
stylesheet root element. Inside of which are a
collection of slide masters, SVG code fragments, and text span
definitions. These ordering of these items is not significant.
<stylesheet>
<fragment>...</fragment>
<fragment>...</fragment>
<master>...</master>
<master>...</master>
<master>...</master>
<textspan>...</textspan>
<textspan>...</textspan>
<textspan>...</textspan>
</styleheet>
The fragments contain arbitrary SVG code that is copied to the SVG file in specific places. These fragments are used to specify the SVG header, footer, and other items.
These fragments inside the top-level element are copied to the SVG file at most once, regardless of how many slides there are in the presentation.
The textspans define font properties for text that appears in spans. Note that textspans are global to the entire stylesheet: you cannot have a span that behaves differently when it is used on different slides (without giving it different names).
Font properties are inherited from the containing item at time
of use. For example, a span inside a
para would use the font properties of the
paragraph unless the span has an property that
overrides it.
The slide masters define how a single slide looks. Each slide (including heading slides, starting slides, and the index slide) will use one slide master definition from the stylesheet file.
A master element contains fragments and blocks. The ordering of these items in the master element is not significant.
<master>
<fragment>...</fragment>
<fragment>...</fragment>
<block>...</block>
<block>...</block>
<block>...</block>
</master>
These fragments contain SVG code that is copied to the SVG file in specific places inside the slide.
These fragments are copied to the SVG file every time a slide
uses the slide master - each slide has its own copy. Thus, for
compactness sake, it is preferable to put SVG code in the stylesheet
fragments rather than inside the slide master fragments - if you can
achieve the same effect. You might want to consider defining symbols in
the stylesheet header fragment, and then referencing them from the slide
master fragments with the SVG use
element. However, this is not always practical when you want to identify
individual elements on slides for animation.
Text blocks are used to define rectangular regions and the display properties of text inside them.
The most common use for text blocks is to declare how metadata information is displayed. If a text block with the name of the metadata element exists in the slide master, then that metadata is displayed. If no text block is found, the metadata is not displayed.
Any new names you create in your stylesheets should use at least one lowercase letter in it to avoid conflicting with any names used by JackSVG.
Names in capital letters (containing no lowercase letters) refer to special items recognised by the JackSVG program. Names beginning with an underscore are used internally, and should not appear in any stylesheet.
All numeric attributes in the stylesheet must contain a number without any units. Although SVG recognises numbers with units, the JackSVG program only processes pure numbers. Numbers may be integers or decimals. Currently, the program does not recognise numbers in scientific notation.
Names are used to identify items in the stylesheet. Names link content items in the presentation to the style definitions in the stylesheet. The information is associated with how it should look through these names.
Typically, the presentation author assigns class names to items in the presentation. For example, they label a text span to have a class name of "strong". Alternatively, some items are automatically assigned class names during the SVG generation process. For example, on introduction heading slides, the bullet point corresponding to the title of the next section may be assigned a class name of "INTRO".
During the SVG generation process, a definition in the stylesheet is found for each item according to its class name. For example, the stylesheet may have a definition corresponding to "strong" that renders the text in bold; or "INTRO" bullet points in red.
The presentation author uses class names to identify logical properties. Other than knowing what class names have been defined in the stylesheet they wish to use, they should not be concerned with how those properties map into SVG code. However, you the stylesheet creator, do.
The stylesheet designer also sees another use for class names - for identifying fragments of SVG code. These fragments are used in the SVG generation process to create the SVG output. So, class names are used for logical content items (e.g. bullet points, paragraphs, text spans), as well as for identifying internal SVG fragments.
When the SVG generator is looking up the definition corresponding to a given class name, a specific algorithm is used. The algorithm looks for an exact match of the name. If that fails, it removes the last component of the name and tries again. Components are separated by a full-stop (a.k.a. a period). This is repeated until a match is found. If there are no more components left, then the special name of "DEFAULT" is used. If a match for "DEFAULT" is not found the lookup fails (which may result in a error, the item being ignored, or a built-in default used - depending on the item).
For example, if it is looking up the name "HEADING.INTRO.FIRST", then it will try the following names in sequence until the first match is found.
HEADING.INTRO.FIRST HEADING.INTRO HEADING DEFAULT
In addition, if the last name component is a positive integer, that number is decremented by one and reused as the last name component. This is repeated until (and including) the number zero.
For example, if it is looking up the name "POINT.3", then it will try the following names in sequence until the first match is found.
POINT.3 POINT.2 POINT.1 POINT.0 POINT DEFAULT
This matching algorithm gives stylesheet designers choice in how they define items. They can have have one definition match many names (using a name with fewer components). Alternatly, they can be very specific and have individual definitions for specific names.
Fragments contain arbitrary SVG code. They are expanded and incorporated into the SVG file.
Variables are expanded in text and attribute values. These variables are enclosed in braces and start with a dollar sign. No spaces are permitted anywhere between the braces and the name of the variable. For example, the following fragment contains two variables:
<text id="mytitle{$SLIDE_INTERNAL_NUMBER}">${PRESENTATION_TITLE}</text>
Fragments are used for serveral purposes. For the HEADER and FOOTER fragments, the following variables can be used:
For the slide fragments: BACKGROUND, MIDGROUND, FOREGROUND, PREV.*, NEXT.*, all of the document variables are available, plus the following:
START.1 START.2 START.3
The stylesheet elements must come from the namespace:
http://www.dstc.edu.au/ns/2002/JackSVG/stylesheet.
The stylesheet contains the following attributes:
xMinYmin,
xMidYmin, and xMaxYMax. If
it is not present, the default of none is used;
however, that will makes the slides look distored if the window size is
not correct, so you should specify this attribute. See the SVG
documentation for more details. (optional)The stylesheet can control which heading slides are generated from groups and sections in the presentation.
Heading generation is controlled by the
generating-heading-slides attribute in the
stylesheet element. This is a mandatory attribute. Its value is a set
of whitespace separated terms. The terms are:
By using combinations of these terms, you can control which heading slides gets generated.
There is an additional term that can be used in conjunction with any or all of the above:
If it is included, one bullet point in the intro-first and/or intro-rest heading slides is marked with the class "INTRO". If intro-highlight is not specified, then the generated intro-first and first headings slides will both have exactly the same content (though may not necessary appear the same, depending on which slides master have been specified).
Two short-hand terms can also be used:
Every heading slide is assigned a class name based on what type of heading slide it is:
When finding a slide master for each heading slide, the normal class name searching rule is appled. Hence, if you supply explicitly named masters you can make each type of heading slide look different. Or you can specify a single "HEADING" master which is applied to every heading slide. Alternatively, don't specify any master for heading slides and the DEFAULT slide master will be used.
All fragments have a single mandatory attribute called
name.
The following fragment names can be used in the top-level
stylesheet element:
{$BUTTON_PLAY_START_ID}.{$BUTTON_PLAY_STOP_ID}.All of these are optional. However, if you don't have a
fragment called PLAY_START then automatic advance
mode cannot be used. If you have specified a
PLAY_START fragment and it is not visible on the
index slide, a possible cause is that there is no
play-delay attribute in the
stylesheet element.
Examples:
<fragment name="HEADER">
<svg:rect x="0" y="0" width="800" height="600" style="fill:blue"/>
</fragment>
<fragment name="PLAY_STOP">
<svg:circle id="{$BUTTON_PLAY_START_ID}" cx="100" cy="100" r="30"/>
<svg:text x="100" y="110">Play</svg:text>
</fragment>
The textspan element defines font
properties for text spans. It is an empty element, with the following
attributes:
When the SVG file is generated, the actual font properties used
are inherited from the containing item. If a font property is specified
in the textspan, then it is used instead of the
inherited value. The inherited value may come from text blocks or the
slide master.
Text spans are found using the name lookup rule. For example, if the span-class is defined as "highlight", it may match spans called "highlight", "hilight.strong", "highlight.2" etc.
It is possible to define a textspan called "DEFAULT", which will match any span name that hasn't been matched by another span definition. This is useful for creating a stylesheet that handles any presentation (even if it uses custom span names). However, bad for detecting errors like incorrectly spelt span class names.
Examples:
<textspan span-class="strong" font-weight="bold"/> <textspan span-class="em" font-style="italic"/> <textspan span-class="code" font-family="Courier New"/> <textspan span-class="quote" font-style="italic" font-family="Times" fill="blue" font-weight="bold"/>
A slide master defines template and definitions for rendering a single slide.
Most simple presentations do not explicitly tag their slides with a class name. These will be called "DEFAULT", so most stylesheets will have at least one master called "DEFAULT".
If heading slides are generated (see the
generate-heading-slide attribute in the top-level
stylesheet element), the generated slides will be assigned class names
of:
The index slide is always assigned a class name of "INDEX".
The name lookup mechanism is used to find slide masters. So if you only supply a "DEFAULT" master, it will be used for all slides (including all heading slides and the index). If you only supply a master called "HEADING", it will be used for all heading slides. Alternatively, you can give each type of heading slide its own master.
Examples:
<master slide-class="DEFAULT" advance-delay="1"> ... </master> <master slide-class="HEADING.LAST" font-family="Helvetica"> ... </master>
The slide master elements, can contain
fragments of SVG. These are the same as the fragments in the top-level
of the stylesheet. They have a mandatory name
attribute.
Standard fragments are:
Every time a slide master is instantiated, each of the above fragment names are searched for. If found, its contents are expanded and placed in the slide.
With the last three, the names that are searched for are generated from the slide class names. This allows context specific animations to be selected based on the slide that appears before, at, and after the current slide.
For example, if the previous slide was a "HEADING.LAST", the current slide has no explicit class, and the next slide is a "HEADING.FIRST", then the program will search for: "ANIMATE_THIS", "ANIMATE_PREV.HEADING.LAST" and "ANIMATE_NEXT.HEADING.FIRST".
The way to use these fragments is to draw the items into the foreground, midground and background fragments (possibly hidden by default), and then control them using animation commands in these fragments. This allows you to change the behaviour of a slide based on the slides around it.
Blocks define the position and display properties of blocks of
text. They appear inside slide master
elements.
The following values are permitted in the
line-wrap attribute:
The default for blocks used for metadata is single-fit. The default for blocks used inside the body is "multi".
The line breaking algorithm does not hyphenate words.
The region can be specified in absolute terms (using x, y, width, and height) or relative to its surrounding container (with the margin attributes).
The algorithm first sets up x, y, width, and height or uses their defaults. Then it applies the margins to them. For example: x=10, y=10, width=1000, height=500, margin-left=1, margin-right=50, margin-bottom=5 produces the region where x=11, y=10, width=949, height=495.
When blocks are used inside the slide body, only the margins are used. The x, y, width and height are ignored and the dimensions of the enclosing body or bullet point are used instead.
The following font attributes can be used inside slide
master, text block, and
text span elements. They are all
optional.
All of these (except line-height) are
based on the CSS font attributes. However, some only take a limited
subset of values and not the full set supported by CSS.
There are variables that represent the number of the current slide, and also the total number of slides.
There are three types of slide numbers: ordinary slide numbers, real slide numbers, and internal slide numbers. They differ according to how they treat the starting slides and generated heading slides. In the descriptions below, when a slide is not given a number the variable expands to a single hyphen.
Ordinary slide numbers are they ones you would normally use to number your slides. For the content slides, they use arabic numbers and start from 1 up to the total number. Heading slides are included in the count. Any starting slides are numbered with roman numbers in their own separate sequence. The index slide is not given a number. The ordinary slide number variables are: 'SLIDE_NUMBER' and 'SLIDE_TOTAL' for the total.
Real slide numbers are the same as ordinary slide numbers, except that heading slides are not given a number. They are skipped in the counting sequence. These numbers may be useful if you don't want to include the generated heading slides in the numbering sequence. The real slide number variables are: 'SLIDE_REAL_NUMBER' and 'SLIDE_REAL_TOTAL'.
Internal slide numbers are used internally to number and identify elements. Every slide is given an internal number. The sequence starts from 1 with the first starting slide, and counts all slides including heading slides. The index slide is numbered zero. These numbers may be useful in your internal stylesheet, but avoid displaying them to viewers. The nternal slide number variables are: 'SLIDE_INTERNAL_NUMBER' and 'SLIDE_REAL_TOTAL'.
For example, consider a presentation that has three starting slides, followed by a single slide and three sections in a group (each section containing one slide. The numbering will be:
Type S S S n H H n n H n n H n n H I SLIDE_NUMBER i ii iii 1 2 3 4 5 6 7 8 9 10 11 12 - SLIDE_REAL_NUMBER i ii iii 1 - - 2 3 - 4 5 - 6 7 - - INTERNAL_SLIDE_NUMBER 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 0
The slide types are 'n' for normal slides, 'S' for starting slides, 'H' for headings, and 'I' for the index slide. In the example, the following totals will be defined in each normal slide and heading slide.
SLIDE_TOTAL 12 SLIDE_REAL_TOTAL 7 INTERNAL_SLIDE_TOTAL 15
For the starting slides, the following totals will be defined in each:
SLIDE_TOTAL iii SLIDE_REAL_TOTAL iii INTERNAL_SLIDE_TOTAL 15
A slide may have any number of navigation buttons...