Skip to content

Writing your own debate format XML file (schema version 1.1)

This information is now outdated, as of 4 July 2013. The new specification for debate format XML files is here.

Element names and attribute names are case-sensitive. To make things easy, all element and attribute names are in lower case.

The root element

<debateformat name="Name of style" schemaversion="1.1">

This is the root element of the XML file. Everything goes between these tags.  Both attributes are mandatory:

  • name is the name of the style, e.g. “Australs”, “British Parliamentary”.  This name is shown in the debate styles list.
  • schemaversion is the version number of the schema this file uses. The current version is 1.1, which added the <preptime> and <preptime-controlled> elements for version 0.9. Users of versions 0.8 and earlier will be advised to upgrade the app if they try to use a 1.1 format.

The information section

<info>...</info>

The information between these tags is displayed in the debate styles list (when the user picks a style). There are four sub-elements. The text goes between the start and end tags, and can be anything but obviously you should make the information useful.

  • <region>...</region>
    The geographic region(s) where this style is used, for example, “Australasia”, “United States”. You can have multiple <region> elements to describe a region each; the app will display all of them. But the regions should be mutually exclusive; if your region is “Australasia”, for example, users are probably smart enough to realise it’s also used in Australia, New Zealand, Korea and Singapore.
  • <level>...</level>
    The level(s) at which this style is used. I can only think of two: “University” and “School”. You can have multiple <level> elements to describe a level each; the app will display all of them.
  • <usedat>...</usedat>
    The major tournament(s) at which this style is used. You can have multiple <usedat> elements to describe a tournament each. It’s best to limit this to major tournaments, otherwise it’ll display a really long list.
  • <desc>...</desc>
    A very short description of the style, no more than about a dozen words. You should basically just include speech times and key features like whether POIs are allowed, similarly to the default styles. Don’t make it too long; you don’t want it to clutter the styles screen!

Preparation time

New in version 0.9. Use these elements to specify how much preparation time is allowed in a style. You can use either of these two elements. For debates that don’t have limited preparation time (e.g. American Parliamentary, Canadian Parliamentary), you should omit both these elements.

<preptime length="15:00" />
Use this element when preparation time is just a single amount of time. Most styles will use this element. The user’s prep time bells (as customised in Menu > Settings > Prep time bells) will apply.

<preptime-controlled length="15:00" firstperiod="something">...</preptime-controlled>
Use this element when the preparation time is controlled by the chair. The only style I know of where this is the case is the Easters style in New Zealand (where one team is allowed a minute to choose the moot, and then the other team is allowed a minute to choose which side they’ll take, and then the teams get five minutes to prepare their case). If you use this, you should populate the element with <bell> and <period> elements, as if it were a speech type (see below).

Definitions of speech types

<speechtype ref="something" length="7:00" firstperiod="firstmin">...</speechtype>

This element defines a type of speech.  You should create a speech type for each type of speech that has different bell times.  For example, the Australs format has two types of speeches: “substantive” and “reply”.  This element has three mandatory attributes (below) and can contain <bell>, <period> and <include> elements.

Every speech type must have at least a <bell> element that is at the finish time of the speech.  You can either use time="finish", or just set the bell time to the same as the speech type length.  If you don’t, the app will show an annoying warning message and default to two bells.  This is by design: debate format XML file authors should be explicit.  If you don’t want to hear a bell, put number="0" in the <bell> element.

  • ref is a reference for the speech.  Its primary purpose is to give the <speech> element a means of referencing this type.  It is only shown in the “More” dialogue box in the debate styles list.  If the style only has one speech type (e.g. British Parliamentary), I recommend using “all”.
  • length is the length of this speech, either in m:ss format or as a single number of seconds.
  • firstperiod is the reference of the <period> tag that this speech type should use at the beginning of the speech.
  • countdir was made obsolete in version 0.9. It is no longer supported, even for 1.0 files. It should be removed from existing files.

<resource ref="something">...</resource>

A “resource” is just a collection of other elements that you can include in speechtypes.  It can contain <bell> and <period> elements.  A resource must be defined before every speechtype in which it is included.

  • ref is a reference for the resource.  It isn’t shown to the user.  You specify this in the <include> element where you want to use this resource.  There is a special value “#all“, which will include the resource in all speechtypes after that resource is defined.

<period ref="firstmin" desc="First minute" bgcolor="#7700ff00" poisallowed="true/>

A “period” is a period between bells, or between the start of the speech and a bell, or after the last bell.  The ref attribute is mandatory.  The other two are optional; if you don’t specify them, they default to the special value “#stay“.

  • ref is a reference for the period, used in the firstperiod attribute of the <speechtype> element and the nextperiod attribute of the <bell> element.  It isn’t shown to the user.
  • desc is a human-readable description of the speech.  This is shown in small text at the top of the screen while this period is active.  The special value #stay means to stay on whatever description was there for the last period.
  • bgcolor is a background colour specified in a 32-bit hexadecimal format preceded by a hash: #77ffcc00.  The number is interpreted in the same way as integer colours in Android: The leftmost two digits are the “alpha” value, then red, green and blue respectively, so #AARRGGBB.  Human names like “green”, “blue” aren’t supported yet; that’ll be in a future release.  It’s better to saturate the RRGGBB parts fully (so that one of them is ff) and then use the alpha setting to control brightness—it looks better when the screen flashes white to indicate a bell.  The special value “#stay” means to stay on the background colour for the last period.
  • poisallowed, new in version 0.7is either true or false, and defaults to false (so you only need to specify it if it’s true).  It indicates whether the POIs timer should be enabled during this period.  For most parliamentary styles, only one period per speech will have this set to true, namely, the period in the middle (after the first minute and before the warning bell).

<bell time="6:00" number="1" nextperiod="warning" />

This element defines a bell.  The time attribute is mandatory.  All others are optional.

  • time is the time of the bell, either in m:ss format or as a single number of seconds.  If this is in a speechtype, it can also be “finish“, which will put the bell at the finish time of the speech (i.e. the same time as the length attribute of the enclosing speechtype).
  • number is how many bells to ring.  This is normally 1 for warning bells and 2 for finish bells.  It can be 0, in which case the bell doesn’t sound (you might want this to change periods without an audible bell).
  • nextperiod is the reference of the period that should apply straight after this bell.

<include resource="speeches" />

This element brings in all the elements inside the corresponding resource into the speechtype. The single attribute resource is mandatory and is the reference of the resource this element should bring in.

Listing the speeches

Now that you’ve defined all the speech types, you can list the speeches.

<speeches>...</speeches>

All speeches must go between these two tags, and these must come after all of the speech types, i.e. this must be the last element before the closing root tag (</debateformat>).

<speech name="Prime Minister" type="substantive" />

There should be one of these elements for each speech.  Both attributes are mandatory:

  • name is the human-readable name of the speech, for example, “1st Affirmative”, “Leader of the Opposition’s Rebuttal”
  • type is the reference of the speech type of this speech
No comments yet

Leave a comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: