Provided by: hovercraft_2.6-4_all
hovercraft - Hovercraft! Documentation Contents:
GUI tools are limiting I used to do presentations with typical slideshow software, such as OpenOffice/LibreOffice Impress, but these tools felt restricted and limiting. I need to do a lot of reorganizing and moving around, and that might mean changing things from bullet lists to headings to text to pictures and back to bullet lists over again. This happens through the whole process. I might realize something that was just a bullet point needs to be a slide, or that a set of slides for time reasons need to be shortened down to bullet points. Much of the reorganization comes from seeing what fits on one slide and what does not, and how I need to pace the presentation, and to some extent even what kinda of pictures I can find to illustrate what I try to say, and if the pictures are funny or not. Presentation software should give you complete freedom to reorganize your presentation on every level, not only by reorganizing slides. The solution for me and many others, is to use a text-markup language, like reStructuredText, Markdown or similar, and then use a tool that generates an HTML slide show from that. Text-markup gives you the convenience and freedom to quickly move parts around as you like. I chose reStructuredText, because I know it and because it has a massive feature set. When I read the documentations of other text-markup langages it was not obvious if they has the features I needed or not. Pan, rotate and zoom The tools that exist to make presentations from text-markup will make slideshows that has a sequence of slides from left to right. But the fashion now is to have presentations that rotate and zoom in and out. One open source solution for that is impress.js. With impress.js you can make modern cool presentations. But impress.js requires you to write your presentation as HTML, which is annoying, and the markup isn't flexible enough to let you quickly reorganize things from bullet points to headings etc. You also have to position each slide separately, and if you insert a new slide in the middle, you have to reposition all the slides that follow. Hovercraft! So what I want is a tool that takes the power, flexibility and convenience of reStructuredText and allows me to generate pan, rotate and zoom presentations with impress.js, without having to manually reposition each slide if I reorganize a little bit of the presentation. I couldn't find one, so I made Hovercraft. Hovercraft’s power comes from the combination of reStructuredText’s convenience with the cool of impress.js, together with a flexible and powerful solution to position the slides. There are four ways to position slides: 1. Absolute positioning: You simply add X and Y coordinates to a slide, in pixels. Doing only this will not be fun, but someone might need it. 2. Relative positioning to last slide: By specifying x and/or y with with a starting r,you specify the distance from the previous slide. By using this form of positioning you can insert a slide, and the other slides will just move to make space for the new slide. 3. Relative positiong to any slide: You can reference any previous slide by its id and specify the position relative to it. This will work for all positioning fields. However, you should not use r as a slide id since the positioning might not behave as you expect. 4. Automatically: If you don’t specify any position the slide will have the same settings as the previous slide. With a relative positioning, this means the slide will move as long as the previous slide moved. This defaults to moving 1600px to the right, which means that if you supply no positions at all anywhere in the presentation, you get the standard slide-to-the-left presentation. 5. With an SVG path: In this last way of positioning, you can take an SVG path from an SVG document and stick it into the presentation, and that slide + all slides following that has no explicit positioning will be positioned on that path. This can be a bit fiddly to use, but can create awesome results, such as positioning the slides as snaking Python or similar. Hovercraft! also includes impress-console, a presenter console that will show you your notes, slide previews and the time, essential tools for any presentation. Shortcut/Navigation Keys: A help popup appears upon launching a presentation; it shows the following shortcuts. · Space -> Forward · Left, Down, Page Down -> Next slide · Right, Up, Page Up -> Previous slide · P -> Open presenter console · H -> Toggle the help popup
DESIGNING YOUR PRESENTATIONS
There are several tricks to making presentations. I certainly do not claim to be an expert, but here are some beginners hints. Take it easy Don't go too heavy on the zoom. Having a difference between two slides in scale of more than 5 is rarely going to look good. It would make for a nice cool zooming effect if it did, but this is not what browsers are designed for, so it won't. And the 3D effects can be really cool if used well. But not all the time, it gets tiring for the audience. Try, if you can, to use the zoom and 3D effects when they make sense in the presentation. You can for example mention the main topics on one slide, and then zoom in on each topic when you discuss it in more detail. That way the effects help clarify the presentation, rather than distract from it. Custom fonts Browsers tend to render things subtly differently. They also have different default fonts, and different operating systems have different implementations of the same fonts. So to make sure you have as much control over the design as possible, you should always include fonts with the presentation. A good source for free fonts are Google Webfonts. Those fonts are free and open source, so you can use them with no cost and no risk of being sued. They can also be downloaded or included online. Online vs Downloaded If you are making a presentation that is going to run on your computer at a conference or customer meeting, always download the fonts and have them as a part of the presentation. Put them in a folder called fonts under the folder where your presentation is. You also need to define the font-family in your CSS. Font Squirrel's webfont generator will provide you with a platform-independent toolkit for generating both the varius font formats and the CSS. If the presentation is online only, you can put an @include-statement in your CSS to include Googles webfonts directly: @import url(http://fonts.googleapis.com/css?family=Libre+Baskerville|Racing+Sans+One|Satisfy); But don't use this for things you need to show on your computer, as it requires you to have internet access. Test with different browsers If you are putting the presentation online, test it with a couple of major browsers, to make sure nothing breaks and that everything still looks good. Not only are there subtle differences in how things may get positioned, different browsers are also good at different things. I've tested some browsers, all on Ubuntu, and it is likely that they behave differently on other operating systems, so you have to try for yourself. Firefox Firefox 18 is quite slow to use with impress.js, especially for 3D stuff, so it can have very jerky movements from slide to slide. It does keep text looking good no matter how much you zoom. On the other hand, it refuses to scale text infinitely, so if you scale too much characters will not grow larger, they will instead start moving around. Firefox 19 is better, but for 3D stuff it's still a bit slow. Chrome Chrome 24 is fast, but will not redraw text in different sizes, but will instead create an image of them and rescale them, resulting in the previous slide having a fuzzy pixelated effect. Epiphany Epiphany 3.4.1 is comparable to Firefox 19, possibly a bit smoother, and the text looks good. But it has bugs in how it handles 3D data, and the location bar is visible in fullscreen mode, making it less suitable for any sort of presentation.
Luckily, for most cases you don't need to create your own template, as the default template is very simple and most things you need to do is doable with css. However, I don't want Hovercraft! to set up a wall where it isn't flexible enough for your needs, so I added support to make your own templates. You need to create your own template if you are unsatisfied with the HTML that Hovercraft! generates, for example if you need to use another version of HTML or if the reStructuredText you are using isn't being rendered in a way that is useful for you. Although if you aren't happy with the HTML generated from the reStructuredText that could very well be a bug, so open an issue on Github for discussion. Hovercraft! generates presentations by converting the reStructuredText into XML and then using XSLT to translate the XML into HTML. Templates are directories with a configuration file, a template XSL file, and any number of CSS, JS and other resource files. The template configuration file The configuration file is normally called template.cfg, but if you have several configuration files in one template directory, you can specify which one to use by specifying the full path to the configuration file. However, if you just specify the template directory, template.cfg will be used. Template files are in configparser format, which is an extended ini-style format. They are very simple, and have only one section, [hovercraft]. Any other sections will be ignored. Many of the parameters are lists that often do not fit on one line. In that case you can split the line up over several lines, but indenting the lines. The amount of indentation doesn't make any difference, except aesthetically. The parameters in the [hovercraft] section are: · template The name of the xsl template. · css A list of CSS filenames separated by whitespace. These files will get included in the final file with "all" as the media specification. · css-<media> A list of CSS filenames separated by whitespace. These files will get included in the final file with the media given in the parameter. So the files listed for the parameter "css-print" will get "print" as their media specification and a key like "css-screen,print" will return media "screen,print". · js-header A list of filenames separated by whitespace. These files will get included in the target file as header script links. · js-body A list of filenames separated by whitespace. These files will get included in the target file as script links at the end of the file. The files impress.js, impressConsole.js and hovercraft.js typically need to be included here. · resources A list of filenames separated by whitespace that will be copied to the target directory, but nothing else is done with them. Images and fonts used by CSS will be copied anyway, but other resources may be added here. · resource-directories A list of directory names separated by whitespace. These will be treated like resources above, ie only copied to the target directory. The directory contents will be copied recursively, but hidden files (like files starting with a . are ignored. An example: [hovercraft] template = template.xsl css = css/screen.css css/impressConsole.css css-print = css/print.css js-header = js/dateinput.js js-body = js/impress.js js/impressConsole.js js/hovercraft.js resources = images/back.png images/forward.png images/up.png images/down.png The template file The file specified with the template parameters is the actual XSLT template that will perform the translation from XML to HTML. Most of the time you can just copy the default template file in hovercraft/templates/default/template.xsl and modify it. XSLT is very complex, but modifying the templates HTML is quite straightforward as long as you don't have to touch any of the <xsl:...> tags. Also, the HTML that is generated is XHTML compatible and quite straightforward, so for the most case all you would need to generate another version of HTML, for example strict XHTML, would be to change the doctype. But if you need to add or change the main generated HTML you can add and change HTML statements in this main file as you like. See for example how the little help-popup is added to the bottom of the HTML. If you want to change the way the reStructuredText is rendered things get slightly more complex. The XSLT rules that convert the reStructuredText XML into HTML are contained in a separate file, reST.xsl. For the most part you can just include it in the template file with the following code: <xsl:import href="resource:templates/reST.xsl" /> The resource: part here is not a part of XSLT, but a part of Hovercraft! It tells the XSLT translation that the file specified should not be looked up on the file system, but as a Python package resource. Currently the templates/reST.xsl file is the only XSLT resource import available. If you need to change the way reStructuredText is rendered you need to make a copy of that file and modify it. You then need to make a copy of the main template and change the reference in it to your modified XSLT file. None of the XSLT files need to be copied to the target, and should not be listed as a resource in the template configuration file.
2013-2019, Lennart Regebro