metarace report printing
------------------------

Printed reports can be customised on a per-event basis by
including a print template file in the event configuration path. 
The template file is a standard ConfigParser file named 'template.ini'
with the sections and options described below.

Please refer to 'template.ini' and 'example.ini' in this
directory for example usage.

Sections:
---------

	[page]		Page defaults, and element list
	[elements]	graphic element definitions
	[fonts]		typeface definitions
	[strings]	text string declarations
	[colours]	colour definitions

All inputs are optional, errors are silently ignored.

Page Reference:
---------------

Recognised options:

	width		LEN, total page width 
	height		LEN, total page height
	lineheight	LEN, line height for text rows
	secheight	LEN, height of section headings
	sidemargin	LEN, left and right margins to body text
	endmargin	LEN, top and bottom margins to body text
	pagemargin	LEN, sets clip region for each page
	minbreak	ALIGN, set the default page break threshold 
	elements	ELEMS, list of whitespace separated element ids

Graphical elements are placed on each output page after provisional
markings are added but before any content is written. The order 
elements are listed in the 'elements' option will be the order they
are written to each page.

Element Reference:
------------------

Each option in the [elements] section defines a single graphical element
on the page. The identifier must be a single alphanumeric word in keeping
with the ConfigParser specification and the value is a comma separated
list of option arguments. The first argument defines the type of element
and the remaining arguments configure the element:

  identifier = type, argument1, argument2, ...

Where type is one of the following:

	line	A straight line segment
	box	A box, optionally filled and/or outlined
	arc	A circular segment, filled and/or outlined
	image	An SVG image scaled and aligned to fit a defined area
	text	A blob of text
	group	A group of element identifiers

All types are documented below.

Element Type Reference:
-----------------------

line, x1, y1, x2, y2, width, colour, dash

   Draw a line of 'width' in 'colour' applying the 'dash'
   from (x1,y1) to (x2,y2). Arguments:

   x1,y1,x2,y2	REL page relative coordinates
   width	LEN absolute length	(default is 1pt)
   colour	COL a defined colour	(default is black)
   dash		DASH list of whitespace separated absolute lengths

box, x1, y1, x2, y2, fill, width, colour, dash

   Draw a box with corners (x1,y1) and (x2,y2). Optionally fill with
   solid colour 'fill' and/or stroke outline with a line of 'width'
   in 'colour' and applying 'dash'. Arguments:

   x1,y1,x2,y2	REL page relative coordinates
   fill		COL a defined colour	(default is no fill)
   width	LEN absolute length	(default is no line)
   colour	COL a defined colour	(default is fill or black)
   dash		DASH list of whitespace separated absolute lengths

arc, cx, cy, r, a1, a2, fill, width, colour, dash

   Draw a circular path centered at (cx,cy) with radius r from angle
   a1 clockwise to angle a2. Optionally fill with solid colour 'fill'
   and/or stroke outline with a line of 'width' in 'colour' and applying
   'dash'. Arguments:

   cx,cy	REL page relative coordinates
   r		LEN absolute length
   a1,a2	ANGLE an angle
   fill		COL a defined colour	(default is no fill)
   width	LEN absolute length	(default is no line)
   colour	COL a defined colour	(default is fill or black)
   dash		DASH list of whitespace separated absolute lengths

image, x1, y1, x2, y2, halign, valign, source

   Draw the SVG image from 'source' scaled to fit the box defined by
   (x1,y1), (x2,y2), aligned horizontally according to 'halign' and
   vertically by 'valign'. Arguments:

   x1,y1,x2,y2	REL page relative coordinates
   halign	ALIGN an alignment value (default is 0.5)
   valign	ALIGN an alignment value (default is 0.5)
   source	FILE image source filename

text, x, y, align, fontid, colour, source

   Place the text defined in 'source' on the page at position (x,y)
   aligned according to 'align' in the defined 'fontid' and 'colour'.
   Arguments:

   x,y		REL page relative coordinates
   align	ALIGN an alignment value (default is 0.0)
   fontid	FONT a defined font (default is pango default)
   colour	COL a defined colour (default is black)

group, elem1, elem2, elem3, ... , elemn

   Place each of the pre-defined elements in the order listed. Recursion
   is silently ignored.

Option Argument Types:
----------------------

REL	A relative coordinate. Positive floats specify offset from
        top or left of page. Negative values specify offset from bottom
	or right of page. Recognised units are: mm, pt, cm, in. Default
	units are mm. Two special lengths are recognised:
          max	will be equivalent to the page width or height
	  mid	equivalent to half width or height of page

LEN	An absolute length. Recognised units are: mm, pt, cm, in. Default
        units are mm

ANGLE	An absolute angle. Recognised units are:
	  rd	radians, eg: 1.5708rd
	  dg	degrees, eg: 90dg
	  pi	multiples of pi, eg: 0.5pi
	Default units are degrees, eg: 90  (above are roughly equivalent).

ALIGN	A floating point alignment value between 0 and 1. 
          0	Top or Left
	  1	Bottom or Right
        Values outside the range are clamped.

COL	Identifier of a colour defined in the [colours] section. Undefined
	colours are substituted with the context default.

FONT	Identifier of a font defined in the [fonts] section. Undefined
	fonts are ignored, and the pango default used instead.

STRING	Identifier of a string defined in the [strings] section, or
	provided by the event. Special strings exported by an event
	are as follows:
	  title                stage or tour title
	  subtitle             stage or tour subtitle
	  datestr              state date
	  docstr               document identifier or stage title for tour
	  diststr              stage distance
	  pagestr              page n (of m)
	  commstr              commissaire
	  orgstr               organiser
	A default value may be defined in the template, but it will
        be overridden by a stage configuration, if present.

DASH	A whitespace separated list of LENs which defines the line/space
	pattern for the dash.

