1
.. include:: <s5defs.txt>
3
=================================
4
Easy Slide Shows With reST & S5
5
=================================
7
:Authors: David Goodger & Chris Liechti
8
:Date: $Date: 2005-12-21 03:01:15 +0100 (Wed, 21 Dec 2005) $
10
.. This document has been placed in the public domain.
12
.. container:: handout
14
How to create quick, good-looking presentation slide shows with
15
Docutils_/reStructuredText_ and S5_.
17
This document serves both as a user manual and as a usage example
18
of the s5_html.py writer and the rst2s5.py front end.
20
To view this document as a slide show see
21
http://docutils.sf.net/docs/user/slide-shows.s5.html (or `your
22
local copy <slide-shows.s5.html>`__).
29
* S5 themes are designed for full-screen display areas with a 4:3
30
aspect ratio. If the slide text doesn't fit in your browser window,
31
try decreasing the text size.
33
* Use the space bar to advance, Page Up/Down & arrow keys to navigate.
35
* Best viewed in Firefox_, Safari, and Konqueror. Click the "|mode|"
36
button to switch between presentation & handout/outline modes. Hit
37
the "C" key to display the navigation controls, or mouse over the
38
lower right-hand corner.
40
* Functionality is limited in Opera. Switch to full-screen mode (F11
41
key) to activate Opera Show.
43
* S5 works in Internet Explorer, but it may look ugly.
45
.. container:: handout
47
The first slide of a presentation consists of all visible text up
48
to the first section title. The document title is also added to
49
the footer of all slides.
51
The "footer" directive is used to specify part of the slide footer
52
text. It is currently limited to one short line (one paragraph).
54
There is no support for the "header" directive in the themes
55
included with Docutils.
57
.. _Docutils: http://docutils.sourceforge.net/
58
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
59
.. _S5: http://meyerweb.com/eric/tools/s5/
60
.. _Firefox: http://www.mozilla.com/firefox/
61
.. |bullet| unicode:: U+02022
62
.. |mode| unicode:: U+00D8 .. capital o with stroke
64
.. footer:: Location |bullet| Date
72
``rst2s5.py`` is a Docutils_ front end that outputs HTML for use
73
with S5_, a "Simple Standards-based Slide Show System" by Eric
76
.. topic:: Installation
79
Prerequisites: Python and the Docutils_ package have to be
80
installed. See the `Docutils README`__ file for installation
83
__ http://docutils.sourceforge.net/README.html
89
Uses normal reStructuredText as input.
91
* One section per slide
95
Each first-level section is converted into a single slide.
99
.. container:: handout
101
Presentations can be viewed using most modern graphical web
102
browsers. The browser must support CSS, JavaScript, and XHTML.
103
S5 even works with IE!
105
S5 was designed to add the functionality of the `Opera Show`_
106
standard (without Opera Show's limitations) to non-Opera
107
browsers. Unfortunately, most of S5's CSS and JavaScript
108
extensions don't function in the Opera browser.
110
.. _Opera Show: http://www.opera.com/support/tutorials/operashow/
116
A variety of themes are available. See `Example Themes`_, below.
122
The front-end tool to generate S5 slide shows.
124
.. topic:: Keyboard Controls
127
The following apply in any supporting browser besides Opera, which
128
uses the default Opera Show controls instead.
135
* - Go to the next slide
142
* Click the left mouse button outside of the control area,
143
Flash object, or movie
144
* - Go to the previous slide
148
* - Go to the title (first) slide
150
* - Go to the last slide
152
* - Jump directly to a slide
153
- Type the slide number, then hit [Return] or [Enter]
154
* - Skip forward *n* slides
155
- Type the number of slides to skip, then hit any "go to next"
156
key (except [Return] or [Enter])
157
* - Skip backward *n* slides
158
- Type the number of slides to skip, then hit any "go to
160
* - Switch between slideshow and outline view
162
* Click the |mode| button
163
* - Show/hide slide controls
165
* Move the mouse pointer over the control area
167
Further details of the S5 user interface can be found at `Eric
176
.. container:: handout
178
The S5/HTML Writer supports all the standard Docutils HTML
179
features. S5 has been released to the Public Domain.
181
S5-specific features:
183
.. class:: incremental
185
* The document title is duplicated on each slide in the S5 footer.
187
* The ``footer`` directive may be used to define additional text in
190
.. container:: handout
192
But it is limited to one line of text.
194
This is useful for information such as the date of the
195
presentation and/or the location. The field in the footer is
196
left blank if no ``footer`` directive is used.
200
.. footer:: Location - Date
202
There is also a progress indicator (slide counter) in the footer
203
that can be enabled. It's disabled by default.
205
* Incremental display.
209
An "incremental" class can be assigned to lists and other elements
210
to get one-item-at-a-time behavior (like this list). Incremental
211
display does not work in the Opera browser.
217
The text size adjusts relative to the size of your browser window
218
automatically. You may need to reload the document after resizing
219
the window. The browser and platform affect the font used; be sure
220
to test the slide show on the presentation system.
223
Features (2): Handouts
224
======================
226
.. container:: handout
228
The contents of any element with a "class" attribute value of
229
"handout" are hidden in the slide presentation, and are only
230
visible when the presentation is printed, or viewed in outline
231
mode. "Handout"-class elements can appear anywhere in the text, as
234
This means that the slides and extra handout material can be
235
combined in one document. The handout can be printed directly from
236
the browser, and it will contain more than just silly framed
237
slides. This can be used to provide more detailed information, or
240
.. class:: incremental
242
* Use the "class" directive::
246
.. container:: handout
248
The ``.. class:: handout`` directive can be used to tag
249
individual paragraphs and other elements. The "class" directive
250
applies to the first element immediately following::
254
This paragraph will get a
255
``class="handout"`` attribute.
257
This paragraph will not be affected.
259
It also applies to multiple elements in the directive content::
263
These paragraphs are the content
264
of the "class" directive. And as such...
266
Both paragraphs will *individually* receive
267
``class="handout"`` attributes.
269
* Use the "container" directive::
271
.. container:: handout
273
.. container:: handout
275
Arbitrary handout blocks can be created using the ``container``
276
directive. The content is treated as one.
278
* Use the "class" option of directives that support it::
280
.. topic:: Extra Material For Handouts
283
.. container:: handout
285
The following directives support "class" options:
287
* all admonition directives ("admonition", "note", "hint", etc.)
295
* "table", "csv-table", & "list-table"
296
* "target-notes" (more about that below)
297
* "role" (pre-defined; more below)
299
Handout contents are also visible on the screen if the S5 view mode
300
is toggled from "slide show" to "outline" mode.
306
.. class:: incremental
308
1. Some Docutils features are not supported by some themes.
310
.. container:: handout
312
For example, header rendering is not supported by the themes
313
supplied with Docutils.
315
The "header" directive is used to set header text. S5
316
automatically inserts section/slide titles into the "header"
317
area of a slide. If both Docutils headers and S5 headers (slide
318
titles) exist simultaneously, they interfere with each other.
320
2. Care must be taken with the "contents" directive.
322
.. container:: handout
324
The ``--no-toc-backlinks`` option is the default for the S5/HTML
325
writer (``toc_backlinks=0`` setting). Other values for this
326
setting will change the CSS class of headings such that they
327
won't show up correctly in the slide show.
329
Use the ``:class: handout`` option on the "contents" directive
330
to limit the table of contents to the handout/outline mode
337
.. class:: incremental
342
... may be used, sparingly.
344
.. container:: handout
346
Only first-level sections become slides. Not many levels of
347
subsections can fit on a slide.
349
Subsections (of any level) work normally in handouts though. Add
350
"``.. class:: handout``" before a subsection (or sub-subsection, or
351
...), and the entire subsection will only appear in the handout.
354
Generating a Slide Show (1)
355
===========================
357
.. class:: incremental
359
1. Open a console (terminal, command shell) and go to the folder
360
containing your file, ``slides.txt``.
364
rst2s5.py slides.txt slides.html
366
3. Specify an S5 theme with the ``--theme`` option.
370
Docutils will copy the S5 theme files into a ``ui/<theme>`` folder
371
beside the output HTML file. A slide show can also link to an
372
existing theme using the ``--theme-url`` option.
375
Generating a Slide Show (2)
376
===========================
378
.. class:: incremental
380
4. Include a copy of any linked stylesheet.
384
The default Docutils stylesheet, ``html4css1.css``, will normally
385
be embedded in the output HTML. If you choose to link to a
386
stylesheet instead of embedding, you must include a copy (suggested
387
location: in the ``ui/`` directory).
389
5. Open ``slides.html`` in a web browser.
391
6. Expand the browser window to full-screen mode, and speak.
395
The `Web Developer`__ extension for Firefox is very useful. With
396
it, you can resize your browser window to the exact dimensions of
397
the projector you'll be using, so you can test beforehand. There
398
are many other useful features as well.
400
__ http://chrispederick.com/work/webdeveloper/
410
Admonitions, tables, sidebars, and other elements can be used in
411
on-screen presentations in handouts. Images too!
413
.. image:: images/happy_monkey.png
426
Examples (2): Incremental Text
427
==============================
429
.. class:: incremental
431
Paragraphs can be displayed one at a time...
435
... or a bunch at a time.
437
This second paragraph is displayed together with the previous
438
one by grouping them with the "container" directive.
440
`We can also display` `one` `word` `at` `a` `time,`
441
`or a phrase` `at a time,`
442
`or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!`
444
`(But the markup ain't pretty.)`
447
Examples (3): Incr. Graphics
448
============================
450
Let's play... Rock, Scissors, Paper
452
.. container:: animation
454
.. image:: images/rsp-empty.png
455
:class: hidden slide-display
457
.. class:: incremental hidden slide-display
459
.. image:: images/rsp-objects.png
460
.. image:: images/rsp-cuts.png
461
.. image:: images/rsp-covers.png
462
.. image:: images/rsp-breaks.png
464
.. image:: images/rsp-all.png
471
.. class:: incremental
473
* Several themes are available, and they're easy to adapt.
475
.. container:: handout
477
Themes from the `S5 tutorial`__ can be used. These themes are in
478
the public domain and may be redistributed freely.
480
__ http://meyerweb.com/eric/tools/s5/s5blank.zip
482
Sites with other S5 themes:
484
* http://meyerweb.com/eric/tools/s5/themes/
485
* http://mozilla.wikicities.com/wiki/Firefox_S5:Designs
486
* http://lachy.id.au/dev/mozilla/firefox/s5/
488
S5 is becoming more popular every day. Do a web search for "S5
489
theme" and you're bound to find plenty of choices.
491
* "``--theme``" option.
493
.. container:: handout
495
The theme can be specified with the "``--theme``" command-line
500
rst2s5 --theme big-black slides.txt slides.html
502
The default theme is "default".
504
* "``theme``" setting.
508
You can set the theme with the "``theme``" configuration file
511
* Copied to ``./ui/<theme>/``.
515
Themes are copied into a ``ui/<theme>`` folder inside the folder
516
containing the presentation.
518
* Link with "``--theme-url``" option.
522
Link to a theme on the same or another web site, using the
523
"``--theme-url``" option or "``theme_url``" configuration file
532
The default theme, "default", is a simplified version of S5's
533
default theme. It accommodates up to 13 lines of text.
539
.. image:: images/default.png
543
Example Themes: Small Text
544
==========================
548
The "small-white" and "small-black" themes are simplifications of
549
the default theme (**small** black text on a **white** background,
550
and **small** black text on a **white** background, respectively).
551
They each accommodate up to 15 lines of text.
558
.. image:: images/small-white.png
562
.. image:: images/small-black.png
565
Example Themes: Large Text
566
==========================
570
The "big-white" and "big-black" themes feature very large, bold
571
text, with no footers. Only five short lines fit in a slide.
578
.. image:: images/big-white.png
582
.. image:: images/big-black.png
585
Example Themes: Medium Text
586
===========================
590
The "medium-white" and "medium-black" themes feature medium-sized
591
text. Up to 8 lines of text are accommodated.
598
.. image:: images/medium-white.png
602
.. image:: images/medium-black.png
608
An S5 theme consists of a directory containing several files --
609
stylesheets, JavaScript, and graphics:
611
.. image:: images/s5-files.png
614
.. container:: handout
616
The generated HTML contains the entire slide show text. It also
617
contains links to the following files:
619
* slides.css simply contains import links to:
621
- s5-core.css: Default styles critical to the proper functioning
622
of the slide show; don't touch this!
624
- framing.css: Sets the basic layout of slide components (header,
625
footer, controls, etc. This file is the often edited.
627
- pretty.css: Presentation styles that give the slide show a
628
unique look and feel. This is the file that you're most likely
629
to edit for a custom theme. You can make a whole new theme
630
just by editing this file, and not touching the others.
632
* outline.css: Styles for outline mode.
634
* print.css: Styles for printing; hides most layout elements, and
637
* opera.css: Styles necessary for the proper functioning of S5 in
640
* slides.js: the JavaScript that drives the dynamic side of the
641
slide show (actions and navigation controls). It automatically
642
IDs the slides when the document loads, builds the navigation
643
menu, handles the hiding and showing of slides, and so on. The
644
code also manages the fallback to Opera Show if you're using
645
the Opera web browser.
647
Two files are included to support PNG transparency (alpha
648
channels) in Internet Explorer:
654
Making a Custom Theme
655
=====================
657
.. class:: incremental
659
1. Run "``rst2s5.py --theme <base-theme> <doc>.txt <doc>.html``".
663
This initializes the ``ui`` directory with the base theme files.
665
2. Copy ``ui/<base-theme>`` to ``ui/<new-theme>``.
671
Start with ``pretty.css``; edit ``framing.css`` if you need to make
674
4. Run "``rst2s5.py --theme <new-theme> <doc>.txt <doc>.html``".
678
Open your ``<doc>.html`` in a browser to test the new theme.
684
Repeat from step 3 until you're satisfied.
686
.. TODO: What to do next:
688
* add a ``__base__`` file
689
* create a personal reusable theme (plugin)
690
* submit the new theme to Docutils
692
``docutils/writers/s5_html/themes/<theme>``
694
.. container:: handout
698
* W3C's `Learning CSS <http://www.w3.org/Style/CSS/learning>`__
700
* `Creating An S5 Theme <http://home.cogeco.ca/~ve3ll/s5themes.htm>`__
702
* A short tutorial on how to create themes (in German):
703
`Eigenes Theme erstellen <http://yatil.de/s5/dokumentation/9/>`__
706
Classes: Incremental (1)
707
========================
711
Several "class" attribute values have built-in support in the
712
themes supplied with Docutils.
714
.. class:: incremental
716
As described earlier,
718
* ``.. class:: incremental``
720
* ``.. container:: incremental``
728
Classes: Incremental (2)
729
========================
731
The "incremental" interpreted text role is also supported:
733
.. class:: incremental
737
:incremental:`This will appear first,` `and
738
this will appear second.`:incremental:
740
Requires "``.. include:: <s5defs.txt>``".
742
.. container:: handout
744
As you can see, this markup is not very convenient.
746
.. class:: incremental
748
| But ``s5defs.txt`` includes this useful definition:
749
| "``.. default-role:: incremental``". So:
753
`This` `is` `all` `we` `need`
755
`This` `is` `all` `we` `need` `to mark up incremental text.`
758
Classes: Incremental (3)
759
========================
765
.. container:: animation
767
.. image:: images/empty.png
768
:class: hidden slide-display
770
.. class:: incremental hidden slide-display
772
.. image:: images/1.png
773
.. image:: images/2.png
775
.. image:: images/3.png
778
.. container:: handout
780
This is how the example works.
782
The animation effects are caused by placing successive images at
783
the same location, laying each image over the last. For best
784
results, all images should be the same size, and the positions of
785
image elements should be consistent. Use image transparency (alpha
786
channels) to get overlay effects.
788
Absolute positioning is used, which means that the images take up
789
no space in the flow. If you want text to follow the images, you
790
have to specify the total size of the container via a style.
791
Otherwise, the images and any following text will overlap.
793
These class values do the work:
796
This wraps the container with styles that position the images
797
absolutely, overlaying them over each other. Only useful on a
801
Unless overridden (by "slide-display", for example), these
802
elements will not be displayed. Only the last image will be
803
displayed in handout mode, when print, or when processed to
804
ordinary HTML, because it does *not* carry a "hidden" class.
807
In conjunction with "hidden", these elements will only appear
808
on the slide, preventing clutter in the handout.
811
The second and subsequent images will appear one at a time.
812
The first image will already be present when the slide is
813
displayed, because it does *not* carry an "incremental" class.
819
.. class:: incremental
821
* :tiny:`tiny` (class & role name: "tiny", e.g. "``:tiny:`text```")
822
* :small:`small` ("small")
825
* :huge:`huge` ("huge")
827
Requires "``.. include:: <s5defs.txt>``".
833
.. class:: incremental
837
Left (class name: "left")
841
Center ("center" & "centre")
849
These classes apply to block-level elements only. They cannot be
850
used for inline text (i.e., they're not interpreted text roles).
852
.. class:: incremental
861
Classes: Text Colours
862
=====================
864
:black:`black` [black], :gray:`gray`, :silver:`silver`, :white:`white`
865
[white], :maroon:`maroon`, :red:`red`, :magenta:`magenta`,
866
:fuchsia:`fuchsia`, :pink:`pink`, :orange:`orange`, :yellow:`yellow`,
867
:lime:`lime`, :green:`green`, :olive:`olive`, :teal:`teal`,
868
:cyan:`cyan`, :aqua:`aqua`, :blue:`blue`, :navy:`navy`,
871
The class names and role names are the same as the colour names. For
872
example, "``:orange:`text```" produces ":orange:`text`".
874
.. class:: incremental
876
Requires "``.. include:: <s5defs.txt>``".
879
Classes: Borderless Tables
880
==========================
884
Here's an ordinary, unstyled table:
886
.. class:: incremental
894
And after applying "``.. class:: borderless``":
896
.. class:: borderless
898
======= ========== =======
899
But sometimes, borders
900
------- ---------- -------
902
======= ========== =======
910
Elements with ``class="print"`` attributes display their contents
911
when printed, overriding ``class="hidden"``.
913
.. class:: incremental
915
Example: the "target-notes" directive::
923
.. container:: handout
925
One good example, used in this document, is the "target-notes"
926
directive. For each external target (hyperlink) in the text, this
927
directive generates a footnote containing the visible URL as
928
content. Footnote references are placed after each hyperlink
931
The "topic" directive is given a "class" attribute with values
932
"hidden" and "print", so the entire topic will only be displayed
933
when printed. The "target-notes" directive also assigns a "class"
934
attributes with values "hidden" and "print" to each of the footnote
935
references it inserts throughout the text; they will only show up
938
.. class:: incremental
940
Other uses may require "``.. include:: <s5defs.txt>``".
943
Useful Extensions For Firefox
944
=============================
950
Automatically hides toolbars in full-screen mode.
952
__ http://www.krickelkrackel.de/autohide/autohide.htm
958
Adds a context submenu and a toolbar with a lot of useful
959
functionality, including the viewing and live editing of
960
stylesheets, and sizing the browser window.
962
__ http://chrispederick.com/work/webdeveloper/
968
.. class:: incremental
970
* Multi-display support:
972
- speaker's notes on the laptop screen
973
- slides on the projector
974
- two views stay in sync
975
- presentation controlled from either display
977
* Add timeout to incremental style.
981
I.e., incremental-specific style should go away (revert to
982
normal) after a certain interval.
984
These will require some serious JavaScript-fu!
993
http://docutils.sf.net
995
Docutils users' mailing list:
996
docutils-users@lists.sf.net
1002
:class: hidden print
1004
.. target-notes:: :class: hidden print
added
removed
docs/user/slide-shows.txt
