How to write presentations using Bruce the Presentation Tool

Bruce presentations are written as plain-text files in the ReStructuredText format with some extensions. If you have access to this HOWTO file in its original text format you may view it using Bruce (the HTML version is produced using the standard rst2html conversion tool.)

See the examples folder *.rst files for some samples, the simplest being "simple.rst" which displays plain text sentences centered on a white background (using the "big-centered" style):

.. load-style:: big-centered

Text displayed centered on the default white background.

----

A new page, separated from the previous using the four
dashes.

Ut enim ad minim veniam.

A Page Title
------------

Pages may optionally have titles which are displayed
centered at the top by default.

and so on.

There's a lot of examples in the examples/ directory, showing off most of Bruce's features.

More Detail

Pages in Bruce are defined as being the text contained in a section or between transitions (horizontal rules, ----). It is important that a blank surrounds the transition line, otherwise ReST might try to interpret it as a title (which will often mean resulting in a parsing error). See "examples/test_sectioning.rst" for a file that mixes section-based and transition-based page delimiting.

Bruce supports a large amount of ReStructuredText and some additional features:

inline markup for emphasis, strong, superscript, subscript and literal
literal blocks
line blocks
block quotes
bullet and enumerated lists (including nesting)
definition lists
images - inline and stand-alone
page titles (section headings)
interactive Python interpreter sessions
styling
backgrounds
transitions between pages

titles: Bruce will not line-wrap title text (doing so messes with layout way too much), so make sure your title fits in one line!
images: A :width: and/or :height: may be specified to scale the image when displayed. If only one is specified then the image's other dimension will be scaled to ensure the image aspect ration is retained.
video: Embedded in the same manner as images, and may be scaled in the same way. Additionally video may be asked to loop using the :loop: flag.
interpreter: Embeds a Python interpreter in the page. The options available are :width: and :height: (default 800 by 300). You may also have the optional flag :sysver: which will cause the standard Python interactive intepreter greeting with the Python version to be displayed.

Style Changes

The rendering stylesheet may be altered on the fly using the ..style:: directive. Changes made in this way are immediate and affect all subsequent text. The exception to this is the "layout" style which applies to the entire current and subsequent pages.

The stylesheet is broken up into sections: default, literal, emphasis, strong, title, footer, block_quote, line_block, literal_block, layout and transition.

Default, title and footer may specify a horizontal alignment.

Default, literal_block and line_block may specify margin_left, margin_right, margin_top and margin_bottom.

All sections except layout, transition and literal_block may specify character styling in color, background_color, font_size, font_name, old and italic.

The layout section specifies the background_color and vertical alignment for page contents.

The transition section specifies the name of the page transition and time to run it for.

color: Specified as an HTML-like RGB or RGBA hex value, eg. #ff00ff for red=255, green=0 and blue=255, ie. purple. May also use the common HTML color names like red, white, gray etc.
background_color: Specified as per color above, indicates the color to place behind the text.
font_size: Size in points of the font.
font_name: Name of the font. Must be loadable using pyglet.resource.font, so must be discoverable using pyglet.resource. Use the inspect_font.py tool in the pyglet distribution to discover a font file's name and other attributes if you're not sure. You may add new fonts using the resource directive.
bold: Use a font's bold variant. Use yes or no.
italic: Use a font's italic variant. Use yes or no.
alignment: One of left (default), center or right.
margin_left, margin_right, margin_top and margin_bottom: Margins surrounding paragraphs specified in pixels.
valign: Only valid in the layout section; one of top (default), center or bottom.
name: Only valid in the transition section; one of the transition names listed below. Default is none.
duration: Only valid in the transition section; gives the duration in seconds to run the current transition for. Default is 0.5.

The default stylesheet contains:

default.font_name = Arial
default.font_size = 20
default.margin_bottom = 12
default.align = left
default.color = black
emphasis.italic = yes
strong.bold = yes
literal.font_name = Courier New
literal.font_size = 20
literal.background_color = #e0e0e0
literal_block.margin_left = 20
line_block.margin_left = 40
block_quote.italic
title.font_size = 28
title.align = center
title.bold = yes
footer.font_size = 16
footer.align = center
footer.italic = yes
layout.background_color = white
layout.valign = top

The "default" group is used as a fallback when a particular style is looked up and no explicit attribute is set. Thus all text is rendered in Arial by default, except in literal text where CourierNew is used. You may set title.font_name to override the font used in the title or default.font_name to override the font used everywhere (except literal text). You may refer to defaults using bare style attributes, so default.font_name and font_name are both equivalent.

Style changes are specified using the style directive. To change the font to 64-point bold, you would:

.. style::
   :font_size: 64
   :bold: yes

To change a single style element you may have the declaration on a single line:

.. style:: :font_size: 64

Transition Names

none: No transition effect. Immediate page change, no delay.
fade: Fades to background color and then to next page.
jump_zoom: Zoom out current page and zoom in new page.
shrink_grow: Like jump_zoom but smoother.
roto_zoom: Rotate and zoom our current page, rotate and zoom in new page.
move_in_left, move_in_right, move_in_bottom, move_in_top: Move the next page in from the specified side.
slide_in_left, slide_in_right, slide_in_bottom, slide_in_top: Slide the current page off and new page on from the specified side.

The following do not work on all machines:

flip_x, flip_y, flip_angle
shuffle
turn_off_tiles
fade_top_right, fade_bottom_left, fade_up, fade_down
corner_move
envelope
split_rows, split_cols

Page Layout

The page layout may also be defined on the fly. Unlike the stylesheet which may be modified, the page layout must be specified entirely with each directive. The layout directive applies to the current and subsequent pages. The layout also controls the placement of the page title.

A blank layout directive ..layout:: will result in the default layout having a white layout and the page title centered at the top of the page.

Layout controls a few elements of display:

title positioning

The position of the title is controlled here. The style of the title is controlled by the stylesheet. The title is specified as:

title:x,y;hanchor;vanchor

The default title is:

title:w//2,h;center;top

Which positions the title at the top-center of the viewport, anchored in the center/top of the text.

footer positioning

The position of the footer is controlled here. The style of the footer is controlled by the stylesheet. The footer is specified as:

footer:x,y;hanchor;vanchor

The default footer is:

footer:w,0;right;bottom

Which positions the foorer at the bottom-right of the viewport, anchored in the right/bottom of the text.

viewport

You may restrict the size of the display usable by pages. By default some space is allocated so the page contents don't overwrite the page title and footer, if they are present and positioned in the usual top and bottom places. The viewport is specified as:

viewport:x,y,width,height

Giving the bottom-left corner x,y position and the width and height.

quad-based decoration

You may draw quads on the page which will appear under any content. The quads may have gradients by specifying different colors for each corner. The syntax for specifying a quad is:

quad:C<color spec>;Vx1,y1;Vx2,y2;Vx3,y3;Vx4,y4

Quad vertex color carries over if it's not specified for each vertex, allowing either solid color or blending.

Colors are specified in HTML format with either three or four channels (if three then the fourth, alpha channel is set to 255).

All positions (quad vertexes, title position, etc) may be Python expressions which will be evaluated. The expressions have the variables "w" and "h" available which are the width and height of the presentation viewport. To center the title, for example, the width could be specified as w//2.

Which will divide the width by two producing an integer (always try to produce an integer as it will result in more pleasing rendering).

Resource Discovery

Bruce can display images and video found in the same directory as the presentation source. You may enable Bruce to search additional paths to find images and video. Additionally you may load new fonts for display by referring to TrueType Font files. You do so using the ..resource:: directive.

adding a directory of resources:

.. resource:: <path to directory>

adding a font file:

.. resource:: <font filename>.ttf

To refer to the font later you'll need to know its name, which may differ from the filename. You may use the inspect_font.py tool in the pyglet source to do so.