============================================================
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 ``Courier New`` 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.

