Easy Slide Shows With reST & S5

Introduction

rst2s5 [7] is a Docutils [2] front end that outputs HTML for use with S5 [4], a "Simple Standards-based Slide Show System" by Eric Meyer.

• reStructuredText

  Uses normal reStructuredText as input.

• One section per slide

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

• XHTML output

  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 [6] 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.

• Themes

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

• rst2s5 [7]

  The console script to generate S5 slide shows.

Features (1)

S5-specific features:

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

  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.

  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.

  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

• Use the "class" directive:

  .. class:: 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

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

• Use the "class" option of directives that support it:

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

Caveats

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

   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.

   The --no-toc-backlinks option is the default for the S5/HTML writer (toc_backlinks=False 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

Generating a Slide Show (1)

1. Open a console (terminal, command shell) and go to the folder containing your file, slides.rst.

2. Run the command:

   rst2s5 slides.rst --output=slides.html

3. Optionally, specify an S5 theme with the --theme option.

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

Generating a Slide Show (2)

4. Include a copy of any linked stylesheet.

   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 slides.html in a web browser.

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

   The Web Developer [10] 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.

7. Profit!

Examples (1)

Examples (2): Incremental Text

Paragraphs can be displayed one at a time...

We can also display one word at a time, or a phrase at a time, or even one letter at a time!

(But the markup ain't pretty.)

Examples (3): Incr. Graphics

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

Themes

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

  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/

  • http://www.openlight.com/Python-S5-Theme.tar.gz

  Do a web search for "S5 theme" and you're bound to find plenty of choices.

• "--theme" option.

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

  Example:

  rst2s5 --theme big-black slides.rst slides.html

  The default theme is "default".

• "theme" setting.

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

• Copied to ./ui/<theme>/.

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

• Link with "--theme-url" option.

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

Example Themes

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

"default"

Example Themes: Small Text

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.

"small-white"

"small-black"

Example Themes: Large Text

The "big-white" and "big-black" themes feature very large, bold text, with no footers. Only five short lines fit in a slide.

"big-white"

"big-black"

Example Themes: Medium Text

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

"medium-white"

"medium-black"

S5 Theme Files

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

Making a Custom Theme

1. Run "rst2s5 --theme <base-theme> <doc>.rst <doc>.html".

   This initializes the ui directory with the base theme files.

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

3. Edit the styles (save in UTF-8 encoding).

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

4. Run "rst2s5 --theme-url ui/<new-theme> <doc>.rst <doc>.html".

   We use the --theme-url option to refer to the new theme. Open your <doc>.html in a browser to test the new theme.

5. Rinse & repeat.

   Repeat from step 3 until you're satisfied.

Classes: Incremental (1)

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

As described earlier,

• .. class:: incremental

• .. container:: incremental

• .. sidebar:: title
     :class: incremental

Classes: Incremental (2)

The "incremental" interpreted text role is also supported:

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

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

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

This is all we need to mark up incremental text.

Classes: Incremental (3)

.. container:: animation

   .. image:: images/empty.png
      :class: hidden slide-display

   .. class:: incremental hidden slide-display

      .. image:: images/1.png
      .. image:: images/2.png

   .. image:: images/3.png
      :class: incremental

Classes: Text Size

• tiny (class & role name: "tiny", e.g. ":tiny:`text`")

• small ("small")

• normal (unstyled)

• big ("big")

• huge ("huge")

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

Classes: Alignment

Left (class name: "left")

Center ("center" & "centre")

Right ("right")

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

Example:

.. class:: center

Text to be centered.

Classes: Text Colours

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

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

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

Classes: Borderless Tables

Here's an ordinary, unstyled table:

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

Classes: Print-Only

Elements with class="print" attributes display their contents when printed, overriding class="hidden".

Example: the "target-notes" directive:

.. topic:: Links
   :class: hidden print

   .. target-notes::
      :class: hidden print

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

Useful Extensions For Firefox

• Autohide [11]

  Automatically hides toolbars in full-screen mode.

• Web Developer [10]

  Adds a context submenu and a toolbar with a lot of useful functionality, including the viewing and live editing of stylesheets, and sizing the browser window.

To Do

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

  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!

Further information: https://docutils.sourceforge.io

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

Any questions?