.. include:: <s5defs.txt>

=================================
 Easy Slide Shows With reST & S5
=================================

:Authors: David Goodger & Chris Liechti
:Date:    $Date$

.. This document has been placed in the public domain.

.. container:: handout

   How to create quick, good-looking presentation slide shows with
   Docutils_/reStructuredText_ and S5_.

   This document serves both as a user manual and as a usage example
   of the s5_html.py writer and the rst2s5.py front end.

   To view this document as a slide show see
   http://docutils.sf.net/docs/user/slide-shows.s5.html (absolute URL;
   or `local <slide-shows.s5.html>`__).

.. contents::
   :class: handout

.. class:: tiny

* Use the space bar to advance, Page Up/Down & arrow keys to navigate.

* Best viewed in Firefox, Safari, Konqueror.  Click the "|mode|"
  button to switch between presentation & handout/outline modes.  Hit
  the "C" key to display the navigation controls, or mouse over the
  lower right-hand corner.

* Functionality is limited in Opera.  Switch to full-screen mode (F11
  key) to activate Opera Show.

.. container:: handout

   The first slide of a presentation consists of all visible text up
   to the first section title.  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).

   There is no support for the "header" directive in the themes
   included with Docutils.

.. _Docutils: http://docutils.sourceforge.net/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _S5: http://meyerweb.com/eric/tools/s5/
.. |bullet| unicode:: U+02022
.. |mode| unicode:: U+00D8 .. capital o with stroke

.. footer:: Location |bullet| Date


Introduction
============

.. class:: handout

   ``rst2s5.py`` is a Docutils_ front end that outputs HTML for use
   with S5_, a "Simple Standards-based Slide Show System" by Eric
   Meyer.

.. topic:: Installation
   :class: handout

   Prerequisites: Python and the Docutils_ package have to be
   installed.  See the `Docutils README`__ file for installation
   instructions.

   __ http://docutils.sourceforge.net/README.html

* reStructuredText

  .. class:: handout

  Uses normal reStructuredText as input.

* One section per slide

  .. class:: handout

  Each first-level section is converted into a single slide.

* XHTML output

  .. container:: handout

     Presentations can be viewed using most modern graphical web
     browsers.  The browser must support CSS, JavaScript, and XHTML.
     S5 even works with IE!

     S5 was designed to add the functionality of the `Opera Show`_
     standard (without Opera Show's limitations) to non-Opera
     browsers.  Unfortunately, most of S5's CSS and JavaScript
     extensions don't function in the Opera browser.

  .. _Opera Show: http://www.opera.com/support/tutorials/operashow/

* Themes

  .. class:: handout

  A variety of themes are available.  See `Example Themes`_, below.

* ``rst2s5.py``

  .. class:: handout

  The front-end tool to generate S5 slide shows.

.. topic:: Keyboard Controls
   :class: handout

   The following apply in any supporting browser besides Opera, which
   uses the default Opera Show controls instead.

   .. list-table::
      :header-rows: 1

      * - Action
        - Key(s)
      * - Go to the next slide
        - * [Space bar]
          * [Return]
          * [Enter]
          * [Right arrow]
          * [Down arrow]
          * [Page down]
          * Click the left mouse button outside of the control area,
            Flash object, or movie
      * - Go to the previous slide
        - * [Left arrow]
          * [Up arrow]
          * [Page up]
      * - Go to the title (first) slide
        - [Home]
      * - Go to the last slide
        - [End]
      * - Jump directly to a slide
        - Type the slide number, then hit [Return] or [Enter]
      * - Skip forward *n* slides
        - Type the number of slides to skip, then hit any "go to next"
          key (except [Return] or [Enter])
      * - Skip backward *n* slides
        - Type the number of slides to skip, then hit any "go to
          previous" key
      * - Switch between slideshow and outline view
        - * [T]
          * Click the |mode| button
      * - Show/hide slide controls
        - * [C]
          * Move the mouse pointer over the control area

   Further details of the S5 user interface can be found at `Eric
   Meyer's S5 page`__.

   __ S5_


Features (1)
============

.. container:: handout

   The S5/HTML Writer supports all the standard Docutils HTML
   features.  S5 has been released to the Public Domain.

S5-specific features:

.. class:: incremental

* 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.

  .. container:: handout

     But it is limited to one line of text.

     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 no ``footer`` directive is used.

     Example::

         .. footer:: Location - Date

     There is also a progress indicator (slide counter) in the footer
     that can be enabled.  It's disabled by default.

* Incremental display.

  .. class:: handout

  An "incremental" class can be assigned to lists and other elements
  to get one-item-at-a-time behavior (like this list).  Incremental
  display does not work in the Opera browser.

* Text auto-scaling.

  .. class:: handout

  The text size adjusts relative to the size of your browser window
  automatically.  You may need to reload the document after resizing
  the window.  The browser and platform affect the font used; be sure
  to test the slide show on the presentation system.


Features (2): Handouts
======================

``<element class="handout">``

.. container:: handout

   The contents of any element with a "class" attribute value of
   "handout" are hidden in the slide presentation, and are only
   visible when the presentation is printed, or viewed in outline
   mode.  "Handout"-class elements can appear anywhere in the text, as
   often as needed.

   This means that the slides and extra handout material can be
   combined in one document.  The handout can be printed directly from
   the browser, and it will contain more than just silly framed
   slides.  This can be used to provide more detailed information, or
   for speaker's notes.

.. class:: incremental

* Use the "class" directive::

      .. class:: handout

  .. container:: handout

     The ``.. class:: handout`` directive can be used to tag
     individual paragraphs and other elements.  The "class" directive
     applies to the first element immediately following::

         .. class:: handout

         This paragraph will get a
         ``class="handout"`` attribute.

         This paragraph will not be affected.

     It also applies to multiple elements in the directive content::

         .. class:: handout

            These paragraphs are the content
            of the "class" directive.  And as such...

            Both paragraphs will *individually* receive
            ``class="handout"`` attributes.

* Use the "container" directive::

      .. container:: handout

  .. container:: handout

     Arbitrary handout blocks can be created using the ``container``
     directive.  The content is treated as one.

* Add a "class" option to certain directives::

      .. topic:: Extra Material For Handouts
         :class: handout

.. container:: handout

   The following directives support "class" options:

   * all admonition directives ("admonition", "note", "hint", etc.)
   * "image" & "figure"
   * "topic"
   * "sidebar"
   * "line-block"
   * "parsed-literal"
   * "rubric"
   * "compound"
   * "table", "csv-table", & "list-table"
   * "target-notes" (more about that below)
   * "role" (pre-defined; more below)

   Handout contents are also visible on the screen if the S5 view mode
   is toggled from "slide show" to "outline" mode.


Caveats
=======

.. class:: incremental

1. Some Docutils features are not supported by some themes.

   .. container:: handout

      For example, header rendering is not supported by the themes
      supplied with Docutils.

      The "header" directive is used to set header text.  S5
      automatically inserts section/slide titles into the "header"
      area of a slide.  If both Docutils headers and S5 headers (slide
      titles) exist simultaneously, they interfere with each other.

2. Care must be taken with the "contents" directive.

   .. container:: handout

      The ``--no-toc-backlinks`` option is the default for the S5/HTML
      writer (``toc_backlinks=0`` setting).  Other values for this
      setting will change the CSS class of headings such that they
      won't show up correctly in the slide show.

      Use the ``:class: handout`` option on the "contents" directive
      to limit the table of contents to the handout/outline mode
      only::

          .. contents::
             :class: handout


.. class:: incremental

3. Subsections ...
------------------

... may be used, sparingly.

.. container:: handout

   Only first-level sections become slides.  Not many levels of
   subsections can fit on a slide.

   Subsections (of any level) work normally in handouts though.  Add
   "``.. class:: handout``" before a subsection (or sub-subsection, or
   ...), and the entire subsection will only appear in the handout.


Generating a Slide Show (1)
===========================

.. class:: incremental

1. Open a console (terminal, command shell) and go to the folder
   containing your file, ``presentation.txt``.

2. Run the command::

       rst2s5.py presentation.txt \
                 presentation.html

3. Specify an S5 theme with the ``--theme`` option.

   .. class:: handout

   Docutils will copy the S5 theme files into a ``ui/<theme>`` folder
   beside the output HTML file.  A slide show can also link to an
   existing theme using the ``--theme-url`` option.


Generating a Slide Show (2)
===========================

.. class:: incremental

4. Include a copy of any linked stylesheet.

   .. class:: handout

   The default Docutils stylesheet, ``html4css1.css``, will normally
   be embedded in the output HTML.  If you choose to link to a
   stylesheet instead of embedding, you must include a copy (suggested
   location: in the ``ui/`` directory).

5. Open ``presentation.html`` in a web browser.

6. Expand the browser window to full-screen mode, and speak.

   .. class:: handout

   The `Web Developer`__ extension for Firefox is very useful.  With
   it, you can resize your browser window to the exact dimensions of
   the projector you'll be using, so you can test beforehand.  There
   are many other useful features as well.

   __ http://chrispederick.com/work/webdeveloper/

7. Profit!


Examples (1)
============

.. sidebar:: Hint

   Admonitions, tables, sidebars, and other elements can be used in
   on-screen presentations in handouts.  Images too!

   .. image:: images/happy_monkey.png
       :alt: sample image

=====  =====  ======
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======


Examples (2): Incremental Text
==============================

.. class:: incremental

   Paragraphs can be displayed one at a time...

   .. container::

      ... or a bunch at a time.

      This second paragraph is displayed together with the previous
      one by grouping them with the "container" directive.

| `We can also display` `one` `word` `at` `a` `time,`
| `or a phrase` `at a time,`
| `or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!`
|
| `(But the markup ain't pretty.)`


Examples (3): Incr. Graphics
============================

Let's play... Rock, Scissors, Paper

.. container:: animation

   .. image:: images/rsp-empty.png

   .. class:: incremental

      .. image:: images/rsp-objects.png
      .. image:: images/rsp-cuts.png
      .. image:: images/rsp-covers.png
      .. image:: images/rsp-breaks.png
      .. image:: images/rsp-all.png


Themes
======

.. class:: incremental

* Several themes are available, and they're easy to adapt.

  .. container:: handout

     Themes from the `S5 tutorial`__ can be used.  These themes are in
     the public domain and may be redistributed freely.

     __ http://meyerweb.com/eric/tools/s5/s5blank.zip

     Sites with other S5 themes:

     * http://meyerweb.com/eric/tools/s5/themes/
     * http://mozilla.wikicities.com/wiki/Firefox_S5:Designs
     * http://lachy.id.au/dev/mozilla/firefox/s5/

     S5 is becoming more popular every day.  Do a web search for "S5
     theme" and you're bound to find plenty of choices.

* "``--theme``" option.

  .. container:: handout

     The theme can be specified with the "``--theme``" command-line
     option.

     Example::

         rst2s5 --theme big-black presentation.txt presentation.html

     The default theme is "default".

* "``theme``" setting.

  .. class:: handout

  You can set the theme with the "``theme``" configuration file
  setting.

* Copied to ``./ui/<theme>/``.

  .. class:: handout

  Themes are copied into a ``ui/<theme>`` folder inside the folder
  containing the presentation.

* Link with "``--theme-url``" option.

  .. class:: handout

  Link to a theme on the same or another web site, using the
  "``--theme-url``" option or "``theme_url``" configuration file
  setting.


Example Themes
==============

.. class:: handout

   The default theme, "default", is a simplified version of S5's
   default theme.  It accommodates up to 13 lines of text.

.. class:: center

   "default"

   .. image:: images/default.png
      :align: center


Example Themes: Small Text
==========================

.. class:: handout

   The "small-white" and "small-black" themes are simplifications of
   the default theme (**small** black text on a **white** background,
   and **small** black text on a **white** background, respectively).
   They each accommodate up to 15 lines of text.

.. list-table::
   :class: borderless

   * - "small-white"

       .. image:: images/small-white.png

     - "small-black"

       .. image:: images/small-black.png


Example Themes: Large Text
==========================

.. class:: handout

   The "big-white" and "big-black" themes feature very large, bold
   text, with no footers.  Only five short lines of large text fits
   per slide.

.. list-table::
   :class: borderless

   * - "big-white"

       .. image:: images/big-white.png

     - "big-black"

       .. image:: images/big-black.png


Example Themes: Medium Text
===========================

.. class:: handout

   The "medium-white" and "medium-black" themes feature medium-sized
   text.  Up to 8 lines of text are accommodated.

.. list-table::
   :class: borderless

   * - "medium-white"

       .. image:: images/medium-white.png

     - "medium-black"

       .. image:: images/medium-black.png


S5 Theme Files
==============

An S5 theme consists of a directory containing several files --
stylesheets, JavaScript, and graphics:

.. image:: images/s5-files.png
   :align: center

.. container:: handout

   The generated HTML contains the entire slide show text.  It also
   contains links to the following files:

   * slides.css simply contains import links to:

     - s5-core.css: Default styles critical to the proper functioning
       of the slide show; don't touch this!

     - framing.css: Sets the basic layout of slide components (header,
       footer, controls, etc.  This file is the often edited.

     - pretty.css: Presentation styles that give the slide show a
       unique look and feel.  This is the file that you're most likely
       to edit for a custom theme.  You can make a whole new theme
       just by editing this file, and not touching the others.

   * outline.css: Styles for outline mode.

   * print.css: Styles for printing; hides most layout elements, and
     may display others.

   * opera.css: Styles necessary for the proper functioning of S5 in
     Opera Show.

   * slides.js: the JavaScript that drives the dynamic side of the
     slide show (actions and navigation controls).  It automatically
     IDs the slides when the document loads, builds the navigation
     menu, handles the hiding and showing of slides, and so on.  The
     code also manages the fallback to Opera Show if you're using
     the Opera web browser.

     Two files are included to support PNG transparency (alpha
     channels) in Internet Explorer:

     - iepngfix.htc
     - blank.gif


Making a Custom Theme
=====================

.. class:: incremental

1. Run "``rst2s5.py --theme <base-theme> <doc>.txt <doc>.html``".

   .. class:: handout

   This initializes the ``ui`` directory with the base theme files.

2. Copy ``ui/<base-theme>`` to ``ui/<new-theme>``.

3. Edit the styles.

   .. class:: handout

   Start with ``pretty.css``; edit ``framing.css`` if you need to make
   layout changes.

4. Run "``rst2s5.py --theme <new-theme> <doc>.txt <doc>.html``".

   .. class:: handout

   Open your ``<doc>.html`` in a browser to test the new theme.

5. Rinse & repeat.

   .. class:: handout

   Repeat from step 3 until you're satisfied.

.. TODO: What to do next:

   * add a ``__base__`` file
   * create a personal reusable theme (plugin)
   * submit the new theme to Docutils

  ``docutils/writers/s5_html/themes/<theme>``

.. container:: handout

   Resources:

   * W3C's `Learning CSS <http://www.w3.org/Style/CSS/learning>`__

   * `Creating An S5 Theme <http://home.cogeco.ca/~ve3ll/s5themes.htm>`__

   * A short tutorial on how to create themes (in German):
     `Eigenes Theme erstellen <http://yatil.de/s5/dokumentation/9/>`__


Classes: Incremental (1)
========================

.. class:: handout

   Several "class" attribute values have built-in support in the
   themes supplied with Docutils.

.. class:: incremental

   As described earlier,

   * ``.. class:: incremental``

   * ``.. container:: incremental``

   * ::

         .. sidebar:: title
            :class: incremental


Classes: Incremental (2)
========================

The "incremental" interpreted text role is also supported:

.. class:: incremental

   ::

       :incremental:`This will appear first,` `and
       this will appear second.`:incremental:

   Requires "``.. include:: <s5defs.txt>``".

.. container:: handout

   As you can see, this markup is not very convenient.

.. class:: incremental

   | But ``s5defs.txt`` includes this useful definition:
   | "``.. default-role:: incremental``".  So:

   ::

       `This` `is` `all` `we` `need`

`This` `is` `all` `we` `need` `to mark up incremental text.`


Classes: Incremental (3)
========================

.. class:: handout

   The "animation" class is provided to support incremental graphics.
   This is how the example earlier was done:

::

    .. container:: animation

       .. image:: images/rsp-empty.png

       .. class:: incremental

          .. image:: images/rsp-objects.png
          .. image:: images/rsp-cuts.png
          .. image:: images/rsp-covers.png
          .. image:: images/rsp-breaks.png
          .. image:: images/rsp-all.png

.. admonition:: Caveat
   :class: handout

   The animation effects are caused by placing successive images at
   the same location, laying each image over the last.  For best
   results, all images should be the same size, and the positions of
   image elements should be consistent.  Use image transparency (alpha
   channels) to get overlay effects.

   Absolute positioning is used, which means that the images take up
   no space in the flow.  If you want text to follow the images, you
   have to specify the image sizes.  Otherwise, the images and any
   following text will overlap.


Classes: Text Size
==================

.. class:: incremental

   * :tiny:`tiny` (class & role name: "tiny", e.g. "``:tiny:`text```")
   * :small:`small` ("small")
   * normal (unstyled)
   * :big:`big` ("big")
   * :huge:`huge` ("huge")

   Requires "``.. include:: <s5defs.txt>``".


Classes: Alignment
==================

.. class:: incremental

   .. class:: left

   Left (class name: "left")

   .. class:: center

   Center ("center" & "centre")

   .. class:: right

   Right ("right")

.. class:: handout

   These classes apply to block-level elements only.  They cannot be
   used for inline text (i.e., they're not interpreted text roles).

.. class:: incremental

   Example::

       .. class:: center

       Text to be centered.


Classes: Text Colours
=====================

:black:`black` [black], :gray:`gray`, :silver:`silver`, :white:`white`
[white], :maroon:`maroon`, :red:`red`, :magenta:`magenta`,
:fuchsia:`fuchsia`, :pink:`pink`, :orange:`orange`, :yellow:`yellow`,
:lime:`lime`, :green:`green`, :olive:`olive`, :teal:`teal`,
:cyan:`cyan`, :aqua:`aqua`, :blue:`blue`, :navy:`navy`,
:purple:`purple`

The class names and role names are the same as the colour names.  For
example, "``:orange:`text```" produces ":orange:`text`".

.. class:: incremental

Requires "``.. include:: <s5defs.txt>``".


Classes: Borderless Tables
==========================

.. class:: handout

   Here's an ordinary, unstyled table:

.. class:: incremental

   =========  =======
   Sometimes  borders
   ---------  -------
   are        useful.
   =========  =======

   And after applying "``.. class:: borderless``":

   .. class:: borderless

   =======  ==========  =======
   But      sometimes,  borders
   -------  ----------  -------
   are      **not**     wanted.
   =======  ==========  =======


Classes: Print-Only
===================

.. class:: handout

   Two classes are provided that only display their contents in
   hardcopy.  The "print-block" class applies to block-level elements
   (like paragraphs, lists, and topics).  The "print-inline" class
   applies to text within paragraphs.

.. class:: incremental

   | "print-block" for block elements
   | "print-inline" for inline text

   Example: the "target-notes" directive::

       .. topic:: Links
          :class: print-block

          .. target-notes::
             :class: print-inline

.. container:: handout

   One good example, used in this document, is the "target-notes"
   directive.  For each external target (hyperlink) in the text, this
   directive generates a footnote containing the visible URL as
   content.  Footnote references are placed after each hyperlink
   reference.

   The "topic" directive is given a "class" attribute with value
   "print-block"; the entire topic will only be displayed when
   printed.  The "target-notes" assigns a "class" attribute with value
   "print-inline" to each of the footnote references it inserts
   throughout the text; they will only show up when printed.

.. class:: incremental

   Other uses may require "``.. include:: <s5defs.txt>``".


Chained Presentations
=====================

.. class:: handout

   Presentation slide shows can be chained together.  This is useful
   for including all or part of one presentation in another, and for
   changing themes.  Slide numbers are not carried over, unless you
   fake a continuous multi-themed presentation:

   1. Generate slide show HTML files with two different names from
      different themes but from the same source text.

   2. Include a link to the **next** slide, in the **second** theme's
      file.

   3. To return to the first theme, include a link to the **next**
      slide, in the **first** theme.

From one theme, `to another...`__

__ slide-shows-alt.s5.html#chained-presentations-2


Chained Presentations (2)
=========================

... and `back again...`__

__ slide-shows.s5.html#chained-presentations-3


Chained Presentations (3)
=========================

... back to the first theme.

.. container:: handout

   Now we're back where we started from, back in the first theme, but
   two slides further on.

   In this way, any number of themes can be chained together.

`Or you could cheat.`

.. container:: handout

   Just prepare the browser in advance, with all the slide show files
   set up at the right slide in separate tabs in your browser, in the
   right order.  Closing one tab will reveal the next.


Useful Extensions For Firefox
=============================

* `Autohide`__

  __ http://www.krickelkrackel.de/autohide/autohide.htm

* `Web Developer`__

  __ http://chrispederick.com/work/webdeveloper/


To Do
=====

.. class:: incremental

   * Multi-display support:

     - speaker's notes on the laptop screen
     - slides on the projector
     - two views stay in sync
     - presentation controlled from either display

   * Add timeout to incremental style.

     .. class:: handout

     I.e., incremental-specific style should go away (revert to
     normal) after a certain interval.

   These will require some serious JavaScript-fu!


That's All, Folks!
==================

.. class:: huge

   Further information:
   http://docutils.sf.net

   Docutils users' mailing list:
   docutils-users@lists.sf.net

   `Any questions?`


.. topic:: Links
   :class: print-block

   .. target-notes:: :class: print-inline
