Preface

This user's manual is an attempt to make the work invested in XSLidy accessible to more than just the people involved in the planning and programming of XSLidy. So if you find any errors, omissions, or other good candidates for improvements, your feedback is very welcome. As usual, the most valuable feedback is constructive criticism, stating what you found that could be improved, and how to would suggest to improve it. Please note that XSLidy is a by-product of trying to use non-proprietary ways of managing presentations and the resulting frustration, and not a professional product.

Thanks to Philippe Cattin for all the discussions (mostly while running), ideas, and test drives of my code!

Getting and Running XSLidy

XSLidy is implemented in XSLT 2.0 as a single XSLT stylesheet
- get the XSLidy XSLT program
There also is an XML Schema defining XSLidy's elements
- get the XSLidy XML Schema
- the schema will not find all errors, but at least some of them
You can also get everything in a single ZIP file
- the ZIP contains the XSLT and the XML Schema
- as well as the complete contents of the XSLidy Web page
For running XSLidy, you need an XSLT 2.0 processor
- XSLT 2.0 is still under development (but almost finished)
- Saxon is a freely available implementation
- for running Saxon, a Java runtime environment is required (1.5 or higher recommended)

Input

The input is an XML document according to the XSLidy XML Schema
- this is the XSLidy XML which created this presentation
- basically, XSLidy files are a mix of XSLidy markup and XHTML markup
The XSLidy XML Schema can be used to validate the input
- an XML Schema processor is required to perform this validation
- validation will find some, but not all errors (strange things may still occur)

Output

The output is a set of Slidy XHTML presentations
- and an optional presentation navigator (an HTML snippet)
The generated Slidy presentations need an environment to work properly
- a Slidy installation containing the Slidy CSS and JavaScript
- layout definitions to control how individual slides are displayed

XSLidy Parameters

The XSLidy XSLT can be controlled with parameters
- how parameters are passed to the XSLT processor depends on the processor
- XSLT 2.0 does not define how stylesheet parameters are being passed
Parameters can be used to control various aspects of XSLidy
The following command line shows how Saxon accepts parameters

java -jar saxon8.jar xslidy.xml xslidy.xsl presentation=intro,manual

Selecting Presentations

The presentation parameter specifies which presentations to generate
- XSLidy structures every document into one or more presentations
By default, XSLidy generates all presentations
- the default value of the presentation parameter is *
If required, only a subset of all presentations can be generated
- comma-separated list of presentation ids such as intro,manual
Caution: Changes in one presentation may affect other presentations!
- if a presentation changes, links into it may have to be re-generated
- be careful when re-generating only a subset of all presentations

java -jar saxon8.jar xslidy.xml xslidy.xsl presentation=intro,manual

XSLidy Processing Messages

The messages parameter controls processing messages
- error is the default and suppresses warning messages
- warning selects that warnings should be printed, too

java -jar saxon8.jar xslidy.xml xslidy.xsl messages=warning

Processing Slide Notes

The notes parameter controls Slide Notes
- include is the default and includes all Slide Notes
- remove removes Slide Notes from generated Slidy files
Slide Notes by default are included in generated Slidy files
- they can always be revealed by using n
- confidential or personal notes therefore should be removed when generating Slidy files

java -jar saxon8.jar xslidy.xml xslidy.xsl notes=remove

How XSLidy Elements Work

XSLidy picks up XSLidy elements during processing
- they are transformed to XHTML elements
- the output of XSLidy does not contain any XSLidy elements
XSLidy elements can broadly be classified into two categories
1. elements which are representing special XSLidy structures
2. elements which serve as shortcuts to more cumbersome XHTML code

Element Overview

Presentation Structures	xslidy, presentation, part, slide, note
Title Information	title, author, affiliation, date, copyright, location, occasion
Generating Tables of Contents	toc, slides, for-each-presentation, presentation-link
Generating Indexes	index, category
XHTML Helpers	list (ul/ol), image
Miscellaneous	listing, counter, link, layout

Specifying the Content Language

...
- xslidy, presentation, part, and slide may carry xml:lang information

Presentations, Parts, and Slides

Each XSLidy document contains one or more Presentations
- usually a lecture or one block of a course
Each presentation contains a sequence of Parts and/or Slides
- parts are optional, but are useful to structure the presentation
- Outline Slides are generated for all parts
Each slide is processed and yields one Slidy slide
Presentations and Parts carry Title Information
Tables of Contents can be created listing all presentations
- these are created as individual files and can be included or further processed

Presentations

Each presentation will become an individual Slidy XHTML document
- presentations may be interlinked with other presentations
Presentations will be written to XHTML files
- the file extension will be set as defined by extension-file
- if a name attribute is set, it will be used as the file name
- if an id attribute is set (but no name attribute), it will be used as the file name
- if neither a name nor an id attribute is set, a file name will be generated
An id attribute can be used for Linking within XSLidy
A presentation cover slide is generated if there is a cover attribute
- there must be a presentation style with this name
- this means either a layout element or a CSS class
Each presentation is described by Title Information
The contents of a presentation are Parts and/or Slides

External Presentations

Some presentations may be delivered without the help of XSLidy
- these presentations should also be part of the Table of Contents
- for these presentations, the Title Information can be included in XSLidy
external specifies the URI of the presentation material
- it must be specified on the presentation element
- external presentations may not contain content (i.e., Parts and/or Slides)
- the external URI will be used as the (unprefixed!) presentation-link in the Table of Contents
It is possible to link to external presentations
- the link will point to the external attribute's URI

Parts

A part groups related Slides and/or parts
Parts can be nested as deeply as required
- However, only two levels are supported when generating Outline Slides
An id attribute can be used for Linking within XSLidy
Each part can be described by Title Information

Outline Slides

...
Controlling Outline Slides
- ...

Slides

Slides are parts of Parts or Presentations
Each slide is processed and yields one Slidy slide
- Slides look very much like Slidy slides
- but they have an explicit title
- they may contain special XSLidy elements

Slide Notes

Slides may contain notes which are not intended for presentation
- note is used to mark up slide notes (they are formatted as a block)
- notes contain additional information about a slide's content
- they are particularly useful when Printing XSLidy Presentations
Notes can be revealed and hidden by pressing the n key
- usually, they are not revealed during presentations
- when printing, a and n show all slides and reveal their notes
- for printing without notes, just do a without n
Notes can be removed when Processing Slide Notes
- public notes can be made public (and used for printing)
- private notes should be removed from the Slidy files
- the notes parameter controls how to handle notes

This is a note demonstrating the note element
note formatting can be changed if required
- the default is defined in xslidy.css
- it can be overridden by layout-specific stylesheets

Additional Styles or Scripts

It may be necessary to use additional styles and/or scripts
- first check whether they should not be part of the layout
XSLidy supports styles/scripts for all or single presentations
style and script can be used as in XHTML
- style may even have a src attribute (then the element is mapped to XHTML's link)
Both elements may appear within xslidy or presentation elements
- each generated Slidy presentation contains the xslidy and the presentation styles/scripts

Title Information Elements

title	The title, e.g. Title Information Elements
author	The author, e.g. Erik Wilde
affiliation	The author's affiliation, e.g. iSchool, UCB
date	The date of the presentation, e.g. August 2006
copyright	The copyright notice of the presentation, e.g. 2006 Erik Wilde (if none is given, the default is the date followed by the author)
location	The location where the presentation is being held, e.g. a city or institution
occasion	The occasion of the presentation, e.g. a conference, course or lecture

Using Title Information on Slides

Cover slides (and maybe others) may want to reference title information
An empty element on a slide produces the most recent definition
- <title/> : Using Title Information on Slides
- <author/> : Erik Wilde
- <affiliation/> : iSchool, UCB
- <date/> : August 2006
- <occasion/> :
If there is not title information, the result is an empty string

<li><code>&lt;title/></code> : <title/></li>
<li><code>&lt;author/></code> : <author/></li>
<li><code>&lt;affiliation/></code> : <affiliation/></li>
<li><code>&lt;date/></code> : <date/></li>
<li><code>&lt;occasion/></code> : <occasion/></li>

Getting Title Information from Specific Levels

Title information from different levels may be interesting
- e.g., displaying the XSLidy and the presentation title on a cover slide
Using level it is possible get specific levels
- <title level="xslidy"/> : XSLidy — Slidy Slideshow Generator
- <title level="presentation"/> : XSLidy User's Manual (default for cover slides and the ToC)
- <title level="part"/> : Title Information
- <title level="slide"/> : Getting Title Information from Specific Levels (default for non-cover slides)
- if there is no such information, the fallback is the next higher definition

<li><code>&lt;title level="xslidy"/></code> : <q><title level="xslidy"/></q></li>
<li><code>&lt;title level="presentation"/></code> : <q><title level="presentation"/></q> (default for cover slides and the <link href="toc">ToC</link>)</li>
<li><code>&lt;title level="part"/></code> : <q><title level="part"/></q></li>
<li><code>&lt;title level="slide"/></code> : <q><title/></q> (default for non-cover slides)</li>

Getting Different Forms of Title Information

Title information may use mixed content and short forms
Depending on the context, different forms of title information may be required
Using form it is possible to get specific forms of title information
- <affiliation form="full"/> : iSchool, UCB (default)
- <affiliation form="text"/> : iSchool, UCB (only the textual content)
- <affiliation form="short"/> : iSchool/UCB (the short value)

<li><code>&lt;affiliation form="full"/></code> : <affiliation/> (default)</li>
<li><code>&lt;affiliation form="text"/></code> : <affiliation form="text"/> (only the textual content)</li>
<li><code>&lt;affiliation form="short"/></code> : <affiliation form="short"/> (the short value)</li>

Generating ToC Files

XSLidy documents usually contain more than one presentation
Providing an ToC over all presentations can be automated
The exact format of the ToC is hard to predict
- it may be a complete Web page
- it may be an HTML snippet to be included on some Web page
- it may be XML which is intended for further processing
- or it maybe that all of the above are required!
Each toc contains a template for a ToC
- id identifies the ToC format for Adding Presentation-Specific Information
- name specifies the name of the generated ToC file

Specifying the ToC Format

The toc template may contain any markup
- elements in the XSLidy namespace will be transformed to XHTML elements
for-each-presentation contains markup which is repeated for each presentation
within for-each-presentation, the following elements are recognized
- all Title Information Elements can be used as usual (generating presentation-level content)
- slides is expanded to the number of slides in the presentation (replacing an asterisk in its content with the actual number)
- presentation-link is used to generate ToC-Links to Presentations
- slides and presentation-link are ignored for empty or external presentations

<toc id="html-toc" name="toc.html">
 <table>
  <for-each-presentation>
   <tr>
    <th><presentation-link><title/></presentation-link><br/><slides>(* Slides)</slides></th>
    <td><toc/></td>
   </tr>   
  </for-each-presentation>
 </table> 
</toc>

ToC-Links to Presentations

presentation-link
element
attribute
prefix

Adding Presentation-Specific Information

toc can also be used inside presentation
- id then specifies the toc where these contents should be included

...example from xml-fall06.xml...

Conditional ToC Information

It may be necessary to generate ToC markup selectively
- some presentation-specific information may only occur for some presentations
- it may be necessary to only generate markup when this information is present
if-toc tests whether a certain toc is present
- id specifies to which toc the test applies
- if-toc's content is only generated if the toc is present
- if-toc makes most sense inside for-each-presentation
- most likely, a toc will appear as part of if-toc's content
The following code tests for <toc id="abstract"/>

<if-toc id="abstract">
 <sylvia:description><toc id="abstract"/></sylvia:description>
</if-toc>

Information about keywords in presentations

index
category

HTML is Great, but...

Not all XHTML elements are easy to use
XSLidy can provide shortcuts
- these can be used if they seem to be useful
- they can be ignored and the XHTML can be entered directly
- new ones can be implemented in XSLidy Extensions

Making Lists

HTML lists are a sequence of one or more li elements
- nested lists must appear within li elements

Organizing Images

img-prefix processing instruction

Including Text Files

HTML supports transclusion only for images
Using listing, you can transclude content from text files
- by default, a link to the included file will be generated
line
- ...
href
- if href is set to the empty string, no link will be generated
- if href is set to anything else, a link to this URI will be generated
tab
- replace
- retain
title
- ...

Linking within XSLidy

link
class style
outlink-mark
outlink-style

Presentation Links

HTML supports document relationships (part of the document head)
- a very useful feature for better navigable sites (standardized site navigation)
- poorly supported by today's browsers (only Opera provides native support)
- Firefox's cmSiteNavigation extension provides support in Firefox
XSLidy automatically inserts links between presentations
- next and prev to navigate through presentations
- start and last to navigate to the first and last presentation
- for all these links, the presentation titles are added as link descriptions
Additional links can be configured and are then added to all presentations
- link-author is a link to a resource about the author
- link-contents is a link to the table of contents
- link-glossary is a link to a glossary

Counters

Using a counter, you can count anything you like
- a counter has a name for grouping items being counted: <counter name="tables" ...
- a counter has an id for identifying one of these items: <counter name="tables" id="elements" ...
The title of the counted thing should be the counter's content
- this makes it possible to use titles for lists and links
- the title as content outputs counter and title, separated by counter-separator: 1: Example
- the title attribute only outputs the number: 2 (the title attribute is set as tool tip, though)
Counters are reset at the beginning of each presentation
- the number format is defined by counter-format (full or short)
- full yields 2.1, short yields 1
- this global setting may be overwritten by using the form attribute on the counter
References to the counter use a ref attribute
- <counter name="tables" ref="elements" ... generates the table's number
- the number is a link to the referenced item, its title is set as tool tip

Presentation Styles

layout
CSS

How XSLidy Processing Instructions Work

File and Link Extensions

XSLidy generates files and within these links to generated files
- generated files are Slidy XHTML presentations
- links may point to other slides or presentations
extension-file controls the file name extension of the generated files
- the default of html is useful in most cases
- the separator dot does not have to be included
extension-link controls the file name extension of the links
- the default of html is useful for file-based testing
- the separator dot does not have to be included
- for publication on decent Web Servers use the empty string

Slidy Files

XSLidy is designed to produce Slidy presentations
slidy-prefix

XSLidy Files

XSLidy presentations require additional resources
xslidy-prefix

outlink-mark

Outlinks are links leaving the current presentation (i.e., the current Slidy XHTML page)
This may happen in two cases:
1. normal HTML links (<a>) within XSLidy files
2. cross-presentation links generated by XSLidy
outlink-mark controls whether outlinks should be marked
- no: no outlink marking
- link: only mark outlinks made by Linking within XSLidy
- a: only mark HTML outlinks (made with a)
- all: mark all outlinks

outlink-style

outlink-style controls how outlinks should be marked
- the style only applies to outlinks selected by outlink-mark
outlink-style can use a text style of the form → * (the default)
- a text style is only applied if there are text nodes inside the link
- the * is replaced with the link's content
- the text before and after the * is inserted before and after this content
outlink-style can use a class style of the form class(outlink)
- a class style is only applied if the link does not have a class attribute
- the contents are set as the link's class attribute
- there should be CSS code defining the formatting for the specified class

Controlling Outline Slides

Outline slides are automatically created for each part
- down to the second level, other parts are ignored in the outline
- but they may still be useful as containers and structuring aid
- <part outline="no"> suppresses outline slides (default is "yes")
The outline-title is used as the title of these slides
- each outline slide will have this title (Presentation Outline by default)
The outline-class is set as the Slidy layout class for each outline slide
- it is easy to create a custom layout for outline slides
- each outline slide is marked as being of class outline by default
The outline-current CSS class is used for formatting the current part
- XSLidy layouts should define this class (as shown in the XSLidy Example)

Counting Slides on Outline Slides

Outline slides may contain the slide count for each listed part
- counting can be controlled on a per-level basis
- part-slide-count is set to 1 per default (only include counts in topmost parts)
- setting part-slide-count to all enables counting for all parts
The generated text can be controlled by using part-slide-text
- the default (* Slides) generates texts like XSLidy Processing Instructions (14 Slides)
- the text can be set to anything, the * will be replaced by the actual number

XSLidy User's Manual

XSLidy — Slidy Slideshow Generator

Erik Wilde, iSchool, UCB (August 2006)