presentation
| title: | Slideshow Tutorial |
|---|---|
| Author: | Lennart Regebro |
| description: | The Hovercraft! tutorial. |
| keywords: | presentation, restructuredtext, impress.js, tutorial |
This slide show is a sort of tutorial of how to use Hovercraft! to make presentations. It will show the most important features of Hovercraft! with explanations.
Hopefully you ended up here by the link from the official documentation at https://hovercraft.readthedocs.org/ . If not, you probably want to go there and read through it first.
This totorial is meant to be read as source code, not in any HTML form, so if you can see this text (it won't be visible in the final presentation) and you aren't seeing the source code, you are doing it wrong. It's going to be confusing and not very useful. Again, go to the official docs. There are links to the source code in the Examples section.
You can render this presentation to HTML with the command:
hovercraft positions.rst outdir
And then view the outdir/index.html file to see how it turned out.
Now then, on to the tutorial part!
The first thing to note is the special syntax for information about the presentation that you see above. This is in reStrcuturedText called "fields" and it's used all the time in Hovercraft! to change attributes and set data on the presentation, on slides and on images. The order of the fields is not important, but you can only have one of each field.
The fields above are meta-data about the presentation, except for the :css:-field. This meta data is only useful if you plan to publish the presentation by putting the HTML online. If you are only going to show this presentation yourself in a meeting you can skip all of it.
The title set is the title that is going to be shown in the title bar of the browser. reStructuredText also have a separete syntax for titles that is also supported by Hovercraft:
.. title:: Slideshow Tutorial
However that requires an empty line after it, and it looks better to use the same syntax for all metadata.
The :css: field will add a custom CSS-file to this presentation. This is something you almost always want to do, as you otherwise have no control over how the presentation will look. You can also specify different media for the CSS, for example "screen,projection":
:css-screen,projection: hovercraft.css
This way you can have different CSS for print and for display. You can only specify one CSS-file per field, however. If you want to include more you need to use the @import directive in CSS.
Once you have added metadata and CSS, it's time to start on the slides.
You separate slides with a line that consists of four or more dashes. The first slide will start at the first such line, or at the first heading. Since none of the text so far has been a heading, it means that the first slide has not yet started. As a result, all this text will be ignored in the output.
So lets start the first slide by having a line with four dashes. Since the first slide starts with a heading, that line is strictly speaking not needed, but it's good to be explicit.
Restructured text takes any line that is underlines with punctuation and makes it into a heading. Each type of undeline will be made into a different level of heading, but it is not the type that is important, but rather the order of which each type will be enountered.
So in this presentation, lines underlined with equal (=) characters will be made into a first-level (H1) heading.
You can choose other punctuation characters as your level 1 heading if you like, but this is the most common. Any if these character works:
= - ` : ' " ~ ^ _ * + # < > .
The drawback with reStructuredText is that you can't skip levels. You can't go directly from level 1 to level 3 without having a level 2 in between. If you do you get an error:
Title level inconsistent
All the normal reStructuredText functions are supported in Hovercraft!
-
Such as bulletlists, which start with a dash (-) or an asterisk (*). You can have many lines of text in one bullet if you indent the following lines.
-
And you can have many levels of bullets.
- Like this.
-
-
There is Emphasis and strong emphasis, rendered as <em> and <strong>.
- Numbered lists is of course also supported.
- They are automatically numbered.
- But only for single-level lists and single rows of text.
-
inline literals, rendered as <tt> and usually shown with a monospace font, which is good for source code. - Hyperlinks, like Python
You can insert an image with the .. image:: directive:
And you can optionally set width and height:
Some people like to have slideshows containing only illustrative images. This works fine with Hovercraft! as well, as you can see on the next slide.
This is the killer-feature of Hovercraft! as very few other tools like this support a presenter console. You add presenter notes in the slide like this:
Note
And then you indent the text afterwards. You can have a lot of formatting in the presenter notes, like emphasis and strong emphasis.
- Even bullet lists!
- Which can be handy!
But you can't have any headings.
You can also have text that is mono spaced, for source code and similar.
There are several syntaxes for that. For code that is a part of a sentence
you use the inline syntax with double backticks we saw earlier.
If you want a whole block of preformatted text you can use double colons:
And then you need to indent the block of text that should be preformatted
You can even have the double colons on a line by themselves:
And this text will now be rendered as preformatted text
But the more interesting syntax for preformatted text is the .. code:: directive. This enables you to syntax highlight the code.
def day_of_year(month, day):
return (month - 1) * 30 + day_of_month
def day_of_week(day):
return ((day - 1) % 10) + 1
def weekno(month, day):
return ((day_of_year(month, day) - 1) // 10) + 1The syntax highlighting is done via docutils by a module called Pygments which support all popular languages, and a lot of unpopular ones as well.
The coloring is done by CSS, if you want to change it, copy the CSS in the highlight.css file and override it in your custom CSS.
If you are including Python-code, then Manuel 1.7.0 and later can test the code for you. This enables you to have code in your presentation and make sure it works.
To do this properly you sometimes want setup and teardown code, code that should be executed as a part of the test, but not shown in the presentation.
To do that, you can simply set a class on the code block.
from datetime import datetimeAdd the hidden class in your css:
pre.hidden {
display: none;
}And your visible code will now be runnable with Manuel:
>>> datetime(2013, 2, 19, 12)
datetime.datetime(2013, 2, 19, 12, 0)That finishes the basic tutorial for Hovercraft! Next you probably want to take a look at the positioning tutorial, so you can use the pan, rotate and zoom functionality.