head	1.1;
access;
symbols;
locks; strict;
comment	@# @;


1.1
date	2005.02.02.22.29.16;	author cworth;	state Exp;
branches;
next	;


desc
@@


1.1
log
@
        * README: Add a big README. It's got good coverage in some parts,
        (template generation), and no coverage in others (dependencies,
        installing, actually running the thing). The big text portions
        should probably be broken out into separate documentation files.
@
text
@svgslides - Make slides with text-based (XML) input and lovely SVG output.

What is this?
-------------
The svgslides package allows you to easily create slides, (or foils,
or viewgraphs, or whatever you want to call them) for presentations.

The input to svgslides consists of two separate parts, content and
theme, which are described in more detail below. the svgslides program
transforms the content according to the theme, to produce SVG files as
output (one file per slide).

What does the content look like?
--------------------------------
The content is created as an text file with XML syntax. It's quite
straight-forward and will be familiar to users of HTML and SVG. For
example, a single slide for presenting this document might look like
this:

	<slide title="Introduction to svgslides">
	  <ul>
	    <li>What is this?</li>
	    <li>What does the content look like?</li>
	    <li>How do I create a theme?</li>
	    <li>Is this really a good idea?</li>
	    <li>Who can we blame for this mess?</li>
	  <ul>
	</slide>

The svgslides package ships with a very simple example file that
demonstrates more of the required and available syntax.

[XXX: I still need to document more of what already works. Direct SVG
snippet inclusion, referencing external SVG images with the <img> tag,
etc.]

[XXX: Need to describe or fix the current known bugs: vertical layout
and indentation is broken when nesting. Vertical layout of images is
currently not there. Theme can't override bullets anywhere, not font
style for nested text. No support for automatic line-breaking. No
pre-formatted text.

And some of these Richard had working fine before and the support just
needs to be copied back in now that the rewrite is complete.]

How do I create a theme?
------------------------
In svgslides, a theme is a sort of "slide template" that captures the
graphical appearance for the slides, (logos, frames, background
watermarks, gradients, etc.). Themes are designed separately from the
slide content. (At least one of the authors has no artistic talent and
as such requires a system in which the design work can be easily
farmed out to a real designer.)

A theme is provided as one (or more) SVG images. It is convenient if
the image targets the expected output resolution for the presentation,
but it's not critical, (though getting the desired aspect ratio right
is helpful).

Much of the theme will be static artwork, and the designer is free to
use any SVG objects for those portions. So, the designer can also use
whatever SVG authoring tools he or she most prefers.

Then, the designer needs to indicate the dynamic portions of the
slides, (the parts that will be substituted by the slide author's
content). In order to do this the designer must first add the
svgslides namespace declaration to the top-level svg element in the
document:

	xmlns:ss="http://www.svgslides.org/svgslides0.1"

Most SVG authoring programs provide some sort of "XML editing" mode to
make this very easy to do. Consult the documentation for your favorite
program, or in a pinch, just edit the SVG file in a text editor and
add the above declaration to the root <svg> element.

Once the svgslides namespace has been declared, there are two forms of
dynamic content that can be indicated, variables and regions.

An svgslides variable is a text object in the SVG theme where the text
will be substituted by the content author. Common uses for variables
include slide titles, footers, fine-print legal disclaimers, etc. A
variable is created by simply creating a text object with some
stand-in text (eg. "Title will appear here") in the desired style and
location. Then, an XML attribute must be added to the text object,
declaring it to be a variable, and giving it a unique name. The
attribute should have thoe following form, (with whatever name is
appropriate in place of title):

	ss:variable="title"

The content author will need to be informed of the names of all
variables that appear in the theme so that text can be provided for
them.

The second type of dynamic content is an svgslides region. This is
conceptually a rectangular portion of the slide which the content
author can fill with anything desired. Almost all theme images should
provide one default region, (which often fills the remaining space
after margins, logo, title, etc.). The only exceptions would be for
slides that are completely static (ie. the content author can't change
anything) or are completly customizable through variables.

Creating a region consists of the following four steps:

	1) Draw a rectangle to encompass the region. The size and the
	   position of the rectangle are significant, but its drawing
	   style is not (though it is most natural if the rectangle is
	   stroked, not filled).

	2) Within the region, place an example line of text, in the
           font, font-size, and color desired for text that the
           content author will provide.

	3) Group the rectangle and the text object together.

	4) Add an XML attribute to the group, (not the rectangle or
           the text object), of the following form:

		ss:region="default"

	   Almost all theme images will contain one region named
	   "default", but (more rarely) can also provide additional
	   regions with any desired names. As with variables, content
	   author should be informed of available region names so that
	   they may use them.

Finally, themes can also have variations. This is useful, for example,
when a title, separator, or final slide should have a different look
than the default slide look.

Variations are indicated in the SVG filename by appending the name of
the variant to the theme name, separated by a hyphen. For example, if
I had a primary theme image named:

	smooth-blue.svg

Then I might also have the following variations:

	smooth-blue-title.svg
	smooth-blue-separator.svg
	smooth-blue-final.svg

Is this really a good idea?
---------------------------
We don't yet know if svgslides will work out or not. But so far, we're
at least learning and having fun with it. Here are some of the goals
we had in coming up with this system:

	* Separation of content/presentation

	* Text input for content for easy collaboration (ie CVS)

	* Scalable output

	* Output that we could render well with cairo

Some might argue that content/presentation separation doesn't work for
slides. The argument could be that since the slides need to contain so
much information, the user really needs the instant feedback to be
able to easily adjust things to fit.

That might be a good argument for a more WYSIWYG approach to the
user-interface, but we don't think that need necessarily be
incompatible with this kind of easy-to-collaborate file format.

For now, we anticipate just having one text editor open for the
textual content, and one SVG editor open for graphical content and
we'll see if it works.

Who can we blame for this mess?
-------------------------------
Carl Worth <carl@@theworths.org>
Richard Worth <richard@@theworths.org>
@