===========================================================
How to write presenations using Bruce the Presentation Tool
===========================================================

Configuration
-------------

Config options::

**bgcolor**
  Background color for all pages (default is black).

**charset=<charset>**
  Page content, **including flags** is encoded using the charset
  (default is ASCII).

**logo=<logo image>**
  A logo to display in the bottom-right of every page. 


Command file syntax
-------------------

Commands start with a triple-hyphen and space, ``--- ``::

    --- <page type>
      [page flags, one per line]

    [page content]

The arguments are preceeded by two spaces.

Every page may include the following flags::

**nofooter**
  Don't display a footer image

**sound=<sound file>**
  Sound is played when the page is displayed.

Lines in the input starting with '#' are always left out of displayed
content, but they are retained for the notes HTML output.

Pages consist of a start marker "--- <some name>" followed by lines of
content. If the start marker line has content itself, like
``--- image kitten.jpg`` then that content is considered the first line
of the page's content. This is convenient for page types that
only have one line of content like images and code.

Page Types
----------

**--- text** - a normal text page
    Each line in the text page is displayed on screen.

    Lines can start with one or more special characters. These include:

    . - "hidden". Each 'next' will display another hidden line.
    . = display as a title
    . : display in codefont (fixed width)
    . * display in bold
    . / display line in italics
    . < or > smaller or bigger (can have multiple)
    . \ no more special characters will be parsed on this line

    For example::

       ..text
       =The Page Title
       *a bold thing*
       -<<*a smaller bold thing not displayed immediately*

**--- image**
    Page content is the filename. The image will be not be scaled without
    without the zoom flag set.

    Flags include:

    **zoom** - zoom smaller image up to fit in screen

    **title=<text>** - set the image title, will appear above image in same
    style as text page title

    **caption=<text>** - set the image caption, will appear below the image
    in same style as text page

    For example::

        ..image
          zoom
          caption=A Screenshot
        screenshot.png

**--- video**
    Page content is the video filename.

    Flags include:

    **title=<text>** - set the video title, will appear above video

    **caption=<text>** - set the video caption, will appear below the video

    For example::

        ..video
          caption=A Screenshot
        video.mpg

**--- code**
    Display a text file contents. The page content is the filename to read
    content from.

    Flags can be:

    **title** - a title to display above the code

**--- html**
    Display a HTML text file contents. The page content is the filename
	to read content from.

**--- py**
    Run an interactive Python session.

    Flags can be:

    **title=<text>** - set the page title, will appear above shell in same
    style as text page title

    **sysver** - display the python version

**--- resource**
    Add a directory to the pyglet resources search path - used to find
    images you reference.

**--- config**
    Lines in config section set options for subsequent pages.

    Can specify colours as 0-255 values "R,G,B" or "R,G,B,A"

**--- blank**
    Nothing is displayed.

**--- <custom page>**
    Load a custom page class. The page specification above must end in
    the page class (see below for how to make custom pages). For example
    "..mypages.FancyPage" will attempt to load the FancyPage class from
    the mypages module.



Custom Pages
============

Custom pages subclass bruce.Page.

Flags are parsed as NAME=VALUE pairs and passed as keyword arguments to the
page constructor. The rest of the page is passed as a single string as an
argument to the page constructor.

Custom pages may define their own configuration variables too.

Bruce structure
---------------

The basic class is the Page class::

    class Page(object):
        flags = (
            # name        , takes arg?
            ('booleanflag', False),
            ('stringflag',  True),
        )

        def __init__(self, viewport, content, **flags):
            '''Initialise the page given the viewport (width, height) in
            pixels.
            '''

        def draw(self):
            '''Draw self - assume orthographic projection.
            '''

        def update(self, dt):
            '''Invoked periodically with the time since the last
            update()
            '''

        def on_enter(self):
            '''Invoked when the page is put up on the screen.
            '''

        def on_next(self):
            '''Invoked on the "next" event (cursor right or left mouse
            button). If the handler returns event.EVENT_HANDLED then
            the presentation does not leave this page.
            '''

        def on_previous(self):
            '''Invoked on the "previous" event (cursor left or right mouse
            button). If the handler returns event.EVENT_HANDLED then
            the presentation does not leave this page.
            '''

        def on_leave(self):
            '''Invoked when the page is removed from the screen.
            '''

        def as_html(self):
            '''Invoked to generate the HTML version of the presentation.
            '''

The Page is pushed onto the pyglet event stack when it is activated and
thus may have handlers for any standard pyglet.window events. A page's
life thus consists of:

1. __init__
2. on_enter
3. lots of update / draw
4. on_next or on_previous and optionally back to #3
5. on_leave


