S5 Slideshows using reST
========================

.. This document serves as manual and example of the rst2s5.py
   converter at the same time.  See the hint below on how to create
   the slideshow.

:Author:        Chris Liechti <cliechti@gmx.net>
:Version:       1.1
:Date:          Today

A short introduction to the S5 converter for Docutils

.. The first slide consists of all visible text between the document
   title and the first subtitle.  The document title is also added to
   the footer of all slides.

.. The "footer" directive is used to specify part of the slide footer
   text.  It is currently limited to one short line (one paragraph).

.. |bullet| unicode:: U+02022
.. footer:: Location |bullet| Today


Introduction
------------

``rst2s5.py`` is a Docutils__ front-end tool that outputs HTML
compatible with S5__, a Simple Standards-based Slide Show System.

* A simple reStructuredText-format text file serves as input.

* Presentations can be viewed using any modern web browser (CSS,
  JavaScript, XHTML).

* Several themes are available on the Internet, easy to adapt.

  .. handout::

     Some sites with S5 slideshows or themes:

     * http://meyerweb.com/eric/tools/s5/themes/
     * http://mozilla.wikicities.com/wiki/Firefox_S5:Designs

     And a short tutorial on how to create themes:
     http://yatil.de/s5/dokumentation/9/ (german text)

* The slides and handout can be combined in one document.  The handout
  will not just contain the silly framed slides.

__ http://docutils.sourceforge.net/
__ http://meyerweb.com/eric/tools/s5/


Usage
-----

Based on Docutils, normal ``reST`` documents are supported.  Each
section is converted to a single slide.

.. sidebar:: Installation
   :class: handout

   Prerequisites: Python and the docutils package have to be
   installed.

   Install ``s5.py`` in docutils/writers, ``rst2s5.py`` to a directory
   in the ``$PATH``.  (Or copy both files to the same folder,
   e.g. ``/usr/local/bin`` on un*x).

A slideshow is simply made by the following command::

    rst2s5.py presentation.txt presentation.html

Some additional files are needed to view a presentation. These go into
the same directory as ``presentation.html``

* The Docutils stylesheet ``default.css``.

  .. handout::

     The ``default.css`` stylesheet is included in the standard
     docutils distribution.  One can also be downloaded from here:
     http://docutils.sf.net/tools/stylesheets/default.css

* A subdirectory ``ui`` with the S5 theme (CSS and JavaScript).

  .. handout::

     By default, the slideshow uses the ``ui`` theme, but that can be
     overriden by a command line option; see below.

     The theme from the S5 tutorial can be used.  Get it here:
     http://meyerweb.com/eric/tools/s5/s5blank.zip

     Most of these themes are available under a `Creative Commons
     Share Alike`__ license.  This means the themes can be used for
     commercial and non-commercial purposes.  But the ``rst2s5``
     converter has a different license.  Therefore no theme is
     distributed along with the converter.

     __ http://creativecommons.org/licenses/by-sa/2.0/

.. class:: handout
.. hint:: Basic steps to create a slideshow:

   1. Open a console (terminal, command shell) go to the folder
      containing ``presentation.txt``.
   2. Run ``rst2s5.py presentation.txt presentation.html``.
   3. Put ``default.css`` in the same folder.  (Get it from
      http://docutils.sf.net/tools/stylesheets/default.css.)
   4. Extract the sample theme from
      http://meyerweb.com/eric/tools/s5/s5blank.zip in the same folder
      (this should create a ``ui`` subfolder).
   5. Open ``presentation.html`` in a web browser.


Features
--------

``rst2s5`` is based on ``rst2html``, and it basically supports all of
its features.

Specifics:

* The document title is duplicated on each slide in the S5 footer.

* The ``footer`` directive may be used to define additional text in
  the S5 footer, limited to one paragraph.

  .. handout::

     This is useful for information such as the date of the
     presentation and/or the location.

     The field in the footer is left blank if the directive is not
     used.

     Example::

         .. footer:: Location - Date

Additions:

* ``.. handout::``: The contents of the "handout" directive are only
  visible when the presentation is printed.  They are hidden in the
  screen presentation.

  .. handout::

     Handout contents are also visible on the screen if the S5 "raw
     view mode" is active.

     The text in a "handout" directive block or elements with a
     "class" attribute of "handout" are hidden in the slideshow on the
     screen.  This can be used to provide more detailed information in
     a handout.

     "Handout" directives can appear anywhere in the text, as often as
     needed.

* The S5 theme (directory name) can be specified with the ``--theme``
  command-line option or "theme" configuration file setting.

  .. handout::

     Example::

         rst2s5 --theme pixel presentation.txt presentation.html

     The default theme is "ui".

     Usualy, themes are placed in a subfolder with the specified name,
     in the same folder as the presentation.  But it is also possible
     to use URLs and grab the design from another website.


Samples: Tables, Directives, Images
-----------------------------------

.. sidebar:: Images are OK

    .. image:: ui/bodybg.gif
       :scale: 30
       :alt: sample image

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

.. hint:: Admonitions, tables, sidebars and others can be used on the
   screen and in the handout.

.. sidebar:: Handout only
   :class: handout

   Elements only visible in the handout can also be generated using a
   ":class: handout" option with "sidebar", "compound" and other
   directives.

.. class:: handout

The ``.. class:: handout`` directive can be used to tag single
paragraphs and other elements.


Caveats
-------

* The ``.. contents::`` directive must not be used.  It changes the
  CSS class of headings and they won't show up correctly in the screen
  presentation.

  [Add a "disable table of contents" setting to the parser?  The S5
  writer could set it as a default.]

* ``.. handout::`` directives generate an error if other ``rst2...``
  converters are used, instead of the S5 converter.

  [How to avoid this?]
