JackSVG Presentation - How to create a presentation

It is assumed that you have a basic knowledge of XML and know how to create an XML file. Creating a presentation involves writing an XML file (although later in this guide we will show a way to create simple presentations without directly using XML). XML is a specially formatted text file: you can use either programs designed especially for editing XML or an ordinary text editor to edit them.

It is also assumed that you have access to the JackSVG program. For basic presentations, you can use the online JackSVG serice and don't have to install JackSVG on your machine. To use the more advanced features of JackSVG (e.g. images in presentations, custom stylesheets) you will need JackSVG installed on your machine. See the installation guide for instructions on how to do this.

You will also need a SVG viewer to view the SVG presentation. The viewer must support the declarative animation features in SVG. At the time of writing, only the Adobe SVG viewer supports these.

Creating a presentation involves two major steps: create the XML file, and running the JackSVG program on that file to generate the SVG presentation. The resulting SVG file can then be viewed.

In this first section, we will describe step-by-step how to create a presentation using the online JackSVG service. This will introduce the basic concepts of using JackSVG.

Instead of creating a presentation XML file from scratch (we'll learn how to do that later in this guide), use one that has been prepared earlier. Download one of the sample presentation XML files from the JackSVG Web site and save it in a local file.

In this tutorial, we will use the online JackSVG service. This is a Web site where you submit your XML presentation file and get back the SVG presentation file. No special software needs to be installed on your local machine (other than a SVG viewer).

Go to the Web page and in the presentation source, supply the name of the XML file you have downloaded in step 1. This file will be uploaded to JackSVG to process.

In the style pop-up menu, select any of the predefined styles - it doesn't matter which one because all the example presentations will work with every example style.

After clicking on the submit button a SVG file will be created and returned to your browser. This will take a couple of seconds, or longer depending on the size and complexity of your presentation - be patient.

If there are no errors, the SVG presentation should appear on your Web browser. If there is an error in your presentation XML file an error message will be shown instead. You will need to edit the XML file, fix the error, and resubmit it.

Producing SVG presentations using JackSVG is quite simple. Try out some of the other styles. The ability to use different styles is a main feature of JackSVG. You can create your own styles, but that is beyond the scope of this introductory guide.

The next part of this guide describes how to write your own presentations. Obviously, these can be created from scratch. However, when you are starting out you might start by modifying one of the supplied examples.

A JackSVG presentation source file is an XML file. A DTD and XML Schema definition of this file is provided for your reference.

The presentation source XML file must use the correct XML Namespace. The file must have the XML Namespace explicitly declared.

Metadata information can be placed in a presentation source file. These are a set of information in named value pair format. A stylesheet uses the metadata values in various ways. For example, as the title of the presentation or some running text one each slide. Metadata cannot be repeated, each metadata name can appear at most once per presentation source.

A stylesheet may define some metadata values as mandatory, and an error is raised if the presentation source doesn't define its value. Optional metadata can be omitted without an error. Extra metadata values, with names not recognised by the stylesheet are ignored.

Different stylesheet can use different metadata. The example stylesheets supplied with JackSVG all use this common set. The title metadata value is used as the title of the presentation. The abstract is used as its description. In the generated SVG file, these are used for the title and desc of the SVG file.

If you are using a custom stylesheet, it may or may not use these metadata items. For example, a custom stylesheet might expect a presentationID metadata item. See the documentation of the custom stylesheet to find out which metadata items are necessary.

After the metadata, comes the main contents of the presentation. A basic presentation can simply be a sequence of slides. More larger presentations can make use of groups and sections to hierarchally structure the presentation.

How groups and sections affect the SVG presentation will depend on the stylesheet used. A stylesheet could ignore groups and sections. More commonly, a stylesheet could generate introduction and/or summary slides from them. It is recommended that groups and sections be used whenever they make sense: they will produce nicer looking index slides as well as encouraging you to logically structure your presentation content.

A slide must have a title, and optionally a subtitle. The body of the slide consists of an arbitrary mix of text paragraphs, images, and bullet points.

Text paragraphs are blocks of text. This can be arbitrary text (i.e. in XML terms, PCDATA). It can also contain specially identified spans of text. How these spans are rendered depends (as you may expect) on the stylesheet.

Bullet points is an item rendered with a bullet in front of it. The contents of bullet point is an arbitrary mix of text pargraphs, images, and other bullet points. You can nest bullet points to an arbitrary depth, bu to keep your presentation understandable you should not go too far.

Different stylesheets can define different spans. The example stylesheets all have defined these types of spans. The em span are rendered in italics and strong in bold.

The url can be used to format URL links. Note that any span can be an active link, the url span is just a formatting style.

The code span formats text in a monospace font. In general, spans represent semantic properties rather than how it should be presented, allowing different stylesheets to render it differently. However, since code is often pretty printed in colour, there are three specialised spans that render code in red, green and blue colour.

The stylesheet will render the different parts of a presentation in some default way. Advanced stylesheets may have special rendering methods that can be invoked by associating an item in the presentation source file with a class name. For example, there might be a special layout for slides containing code examples (it may have smaller margins so more code can be shown on the screen).

Classes can be applied to many elements. Text spans are usually are associated with an explicit class, since spans without a class don't do anything.

Consult the documentation of the stylesheet to find out what classes are available. The example stylesheet does not define any custom classes (other than those already described for text spans).

XML DTD and XML Schema definitions of the JackSVG presentation file format are provided with JackSVG. You can use these to validate your input file before submitting it to JackSVG. Here we will examine the DTD to look closely at the format.

The root element is the presentation element. It must have a version attribute. Currently, this attribute must have the value of "1.0". The presentation element contains metadata and the slides or groups of slides. The namespace must be explicitly declared.

Metadata elements are repeated for as many times as necessary. Each must have a name attribute. The value of the metadata is the text contents of the element. No two metadata element can have the same name.

The order of the metadata elements does not have any significance to JackSVG. However, other programs which also read the presentation might. Specifically, the sample XSLT script that converts a presentation into HTML will output the metadata in document order.

The metadata element names used will depend on the stylesheet. Unrecognised metadata are ignored, without any warning. However, some stylesheet might have mandatory metadata, and if they are not specified an error occurs.

Groups and sections are used to divide a presentation to give it a logical structure. Groups contain sections. Sections contain a series of slides or nested groups.

Both groups and sections must have a title, and optionally a subtitle. These are both simple text elements.

A slide has a mandatory title, followed by an optional subtitle, the contents of the slide, and optionally some notes.

One of the most common elements used in the contents of the slide is a bullet point.

The notes element can contain any fragment of XML. JackSVG will ignore everything in the notes section. However, they may be used by other programs which process the presentation source XML file. For example, they may be used to put in notes that appear in a HTML version of the presentation.

The second thing that can appear in a slide (and nested inside bullet points) are text paragraphs. These are represented using the para element. As previously described, text spans can be marked up inside text pargraphs. If you want to turn a section of text into an active link, add the attribute to the span element. You can do this for any text span (not just the one named url in the example stylesheets).

If you click on a hyperlink during a presentation, you will loose your current position in the SVG presentation when you go back to it in the browser. To avoid this problem (when using the Adobe SVG viewer), right click on the link instead and choose "Open in a New Window" from the context menu.

The third thing that can appear in a slide (and nested inside bullet points) are images. The mandatory xlink:href contains a relative file name to the file containing the image.

If you don't specify both an explicit width and height, JackSVG will attempt to use the natural size of the image. We say it "attempts" because depending on how JackSVG has been installed that may or may not work. It uses the Image::Size Perl module to examine the image file and determine its dimensions.

The optional type attribute contains one of the following values: image/svg+xml, image/jpeg, or image/png - these are the image formats that compliant SVG viewers must support. You can also use image/gif, but that is discouraged because GIF does not have to be supported by compliant SVG viewers - use PNG instead.

The type attribute is only neccessary if you have not explictly specified the image's size (both height and width) and the image is in SVG format. When you do not specify this attribute, and the Image::Size module is used, it will automatically determine what the format of the image file is. However, since Image::Size does not recognise the SVG format, it will return a cryptic error that says "Unknown image width size: Data stream is not a known image file format".

Note: images cannot be used with the online JackSVG service. You must install JackSVG locally on your machine to be able to use images.

It doesn't matter how you create a JackSVG presentation source file. You can use an XML editor or a normal text editor.

If you don't have an XML editor and find typing XML by hand too difficult, you might want to try the txt2pres program. This program converts a simple text file into a presentation source XML file.

The txt2pres is very basic. It doesn't support some features of JackSVG, such as text spans, images and classes. However, it will produce simple presentations containing slides with bullet pointed text. Groups and sections are supported. For simple text-only presentations, it might be all you need. For more advanced presentations, you may use it to create a first-cut presentation source XML file which you then further edit.

Currently the txt2pres input format is not documented. It is pretty straightforward. Have a look at the sample text file in the examples/presentations directory.

There are two ways of running JackSVG: using the online service (as described in the first part of this guide), or installing JackSVG on your local machine. To use all the features of JackSVG, you need to download it and install it on your machine.

The command line program program installed is called . It takes in a presentation source XML file and generates the SVG file. The SVG is printed to standard output unless the -output option is specified.

You must specify the stylesheet file using -stylesheet option. If the stylesheet uses a special font, the processor will need to know the dimensions of that font to perform layout properly. This is done by specifying a fontmetrics mapping file. Alternatively, you can specify the -Force (note: capital F) option so the program will ignore that requirement and just guess what those dimensions are. For the most accurate layout you shouldn't use the force option, however it might be handy for testing when you don't have the appropriate font metrics available.

All of the option names can be abbreviated. For information on other options, run the program with the -help option.

In the examples subdirectory, you'll find XSLT scripts to transform a presentation source XML file into either HTML or XSL-FO. You will need an XSLT processor to use these. These are useful for printing out the presentations. Mainly because it is difficult (if not impossible) to print out the SVG, but also because it allows you to add notes to the presentation.

The HTML format can be posted on a Web site. It will use any HTML elements found in the notes section of the slides. You must use elements from the XHTML namespace (specifically, http://www.w3.org/1999/xhtml) for this to work. The HTML can also function as a presentation for browsers that support the CSS2 projection media (e.g. try viewing it in the full screen mode of the Opera browser).

The XSL-FO can be processed by an XSL Formatting Objects processor to generate formatted pages.

This guide has provided you with enough information to get started in creating your own presentations. More advanced users may want to create their own stylesheets. We hope you enjoy using JackSVG and find it useful.