erik
/
docutils0.14-fork
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 Commits
1 Branch
0 Tags
3.5 MiB
Tree: f8c3971a0e
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'f8c3971a0e'
${ noResults }
docutils0.14-fork/docs/user/slide-shows.txt

1007 lines
25 KiB
Raw Normal View History Unescape

Added files missing from initial import.
7 years ago
.. include:: <s5defs.txt>
=================================
Easy Slide Shows With reST & S5
=================================
:Authors: David Goodger & Chris Liechti
:Date: $Date: 2006-03-30 16:29:59 +0200 (Do, 30 Mär 2006) $
.. 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 (or `your
local copy <slide-shows.s5.html>`__).
.. contents::
:class: handout
.. class:: tiny
* S5 themes are designed for full-screen display areas with a 4:3
aspect ratio. If the slide text doesn't fit in your browser window,
try decreasing the text size.
* Use the space bar to advance, Page Up/Down & arrow keys to navigate.
* Best viewed in Firefox_, Safari, and 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.
* S5 works in Internet Explorer, but it may look ugly.
.. 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/
.. _Firefox: http://www.mozilla.com/firefox/
.. |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
======================
.. 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.
* Use the "class" option of directives that support it::
.. 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, ``slides.txt``.
2. Run the command::
rst2s5.py slides.txt slides.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 ``slides.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: hidden slide-display
.. class:: incremental hidden slide-display
.. 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
:class: incremental
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/
* http://www.openlight.com/Python-S5-Theme.tar.gz
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 slides.txt slides.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 fit in a 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-url ui/<new-theme> <doc>.txt <doc>.html``".
.. class:: handout
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.
.. 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:: small
::
.. 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
.. container:: handout
This is how the example works.
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 total size of the container via a style.
Otherwise, the images and any following text will overlap.
These class values do the work:
animation
This wraps the container with styles that position the images
absolutely, overlaying them over each other. Only useful on a
container.
hidden
Unless overridden (by "slide-display", for example), these
elements will not be displayed. Only the last image will be
displayed in handout mode, when print, or when processed to
ordinary HTML, because it does *not* carry a "hidden" class.
slide-display
In conjunction with "hidden", these elements will only appear
on the slide, preventing clutter in the handout.
incremental
The second and subsequent images will appear one at a time.
The first image will already be present when the slide is
displayed, because it does *not* carry an "incremental" class.
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
Elements with ``class="print"`` attributes display their contents
when printed, overriding ``class="hidden"``.
.. class:: incremental
Example: the "target-notes" directive::
.. topic:: Links
:class: hidden print
.. target-notes::
:class: hidden print
.. 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 values
"hidden" and "print", so the entire topic will only be displayed
when printed. The "target-notes" directive also assigns a "class"
attributes with values "hidden" and "print" 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>``".
Useful Extensions For Firefox
=============================
* `Autohide`__
.. class:: handout
Automatically hides toolbars in full-screen mode.
__ http://www.krickelkrackel.de/autohide/autohide.htm
* `Web Developer`__
.. class:: handout
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.
__ 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: hidden print
.. target-notes:: :class: hidden print