============================================================
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
- decorations


**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 and literal_block.

Default, title and footer may specify an alignment.

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

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

**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.

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.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


Page Decoration
---------------

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

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

Decorations actually control a few elements of display:

**background color**
   The background color is specified using the HTML-like notation used in styles.
   The color is specified using::

        bgcolor: <color spec>

**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.


