Skip to content

Writing your own custom debate format file

Jump to bottom
Chuan-Zheng Lee edited this page Oct 10, 2021 · 20 revisions

This page reflects schema version 2.2, which will be supported by Debatekeeper version 1.3, which is currently in beta. Schema 2.2 is backwards-compatible with schema 2.1, but Debatekeeper will ask if you want to update the app, and the update isn't yet available. The only difference is the <version> element, so just exclude that and bump your file down to schema version 2.1 in the meantime. Submissions to the new repository should contain the <version> element and be marked as schema version 2.2.

(Schema 2.2 also includes multilingual support, but it's backwards-compatible, in that if languages are all omitted it's still a valid file.)

If you'd like to see the beta preview, you can join the beta testing programme here.

Debatekeeper can time according to any format you like—not just the styles that come built in to the app.

You can specify your own debate format for Debatekeeper to use. Debate formats are written in XML, according to the specifications on this page.

You need to write an XML file on your computer, and load it into your phone (e.g. via USB). In future versions I intend to implement a mechanism to easily share custom formats between phones, but I don't intend to include a format editor within the app.

Note: The current schema version is 2.2. Support for schema 1.0 will be removed in the next version of Debatekeeper, so if you have a schema 1.0 file, you should convert it to a 2.2 file. There's a Python script in the repository that'll help you do that.

Note: In the user interface we call it a "debate style", and in the source code we call it a "debate format". On this page I use the terms interchangeably.

Quick start

The easiest approach to creating a custom format is the following:

  1. Go to formats folder in the official formats repository.
  2. Copy the file for the style that is the most similar to yours. Save it as your-format-name.xml.
  3. Edit it in your favourite XML or text editor. The files are quite self-explanatory, so for small changes, it should be obvious what to do. A full specification is below.
  4. Send it to yourself and open it on your phone. Debatekeeper will ask you whether you want to import it.

Where to put the file

Warning: This is changing in an upcoming version of Debatekeeper!

Debatekeeper version 1.2 (most people): You should create a directory called debatekeeper in (the root directory of) your phone, and place the XML file in there. It must have the file extension .xml. If you give your file the same name as one of the built-in styles, then your custom file will override the built-in style. Otherwise, Debatekeeper will just add it to the list.

The easiest way to do this is with a USB cable and your computer. But you could also e-mail it to yourself or load it in through cloud storage like Dropbox or Google Drive, so long as you can find a way to save it to the "debatekeeper" directory.

Debatekeeper version 1.3 (beta): Just open the XML file on your phone. Your phone should send it to Debatekeeper, which will import it, i.e. save it in its own directory. This is an Android-managed location that will be deleted if you uninstall Debatekeeper, so be sure to keep a copy of the XML file somewhere else as well. (It is possible to access the Android-managed location—see Custom format changes in version 1.3.)

Want to contribute your debate format to the official release? Please do! Submit it to the official debate formats repository.

What goes in the XML file

Note: Element names and attribute names are case-sensitive. All are in lower case. Mind the hyphens—they're important too!

Root element

<debate-format schema-version="2.2">...</debate-format>

This is the root element of the XML file. Everything goes between these tags.

  • schema-version is the version number of the schema this file uses. The current version is 2.2.

Name of debate style

<name>...</name>

Write the name of the debate style here, e.g. "British Parliamentary".

New in schema version 2.2: This element supports translations. To support multiple languages, include this element multiple times, with the xml:lang attribute in each one. See the multilingual formats section for more details. See the bp.xml file for an example.

<short-name>...</short-name>

New in schema version 2.1. This is a shorter name that's used in the title bar of the main screen. It should be used if the full name of the format is too long to fit, and if used, it should be a common short name for the format. For example, "American Parliamentary" shortens to "APDA". If the full name fits into the title bar while most phones are in portrait orientation, this should be omitted, so for example "Asian Parliamentary" is not shortened. If omitted, it defaults to what was in the <name>...</name> element.

New in schema version 2.2: This element supports translations. To support multiple languages, include this element multiple times, with the xml:lang attribute in each one. See the multilingual formats section for more details. See the bp.xml file for an example.

Version of file

<version>...</version>

New in schema version 2.2. This version number must be an integer, like "1" (not "1.0"). It's used by the online repository to check whether an update is available, i.e. whether the version in the repository is newer than the version stored on the user's device. The first version should be "1", and it should be incremented whenever a new version is submitted to the online repository.

Languages supported

<languages>
    <language>...</language>
    <language>...</language>
</languages>

Optional, new in schema version 2.2. A list of languages supported by the file. This must be specified for all files that support two or more languages. The text in the <language> elements must be a language code as defined by BCP 47 language tag. These should be specified in order of preference. For example, if the format has a "native" language (e.g., English for British Parliamentary; German for Open Parliamentary), that should be specified first.

See the multilingual formats section for more details. See the bp.xml file for an example.

Information section

<info>
    <region>...</region>
    <level>...</level>
    <used-at>...</used-at>
    <description>...</description>
</info>

The information between these tags is displayed in the debate styles list. There are four sub-elements. The text in them 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 elements to describe a region each; the app will display all of them. But the regions should be mutually exclusive; for example, if your region is "Australasia", 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.

  • <used-at>...</used-at>

    The major tournament(s) at which this style is used. You can have multiple <used-at> elements to describe a tournament each. It's best to limit this to major tournaments, otherwise it'll display a really long list.

  • <description>...</description>

    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!

New in schema version 2.2: The <info> element supports translations. To support multiple languages, include the entire <info> element (and its subelements) multiple times, with the xml:lang attribute in each one. Do not include the xml:lang attribute in the subelements. See the multilingual formats section for more details. See the bp.xml file for an example.

Custom period types

This is optional, and is needed only if the built-in period types aren't enough for your format.

<period-types>...</period-types>

All custom <period-type> elements, if any, go between these tags.

<period-type ref="reference" pois-allowed="true">
    <name>...</name>
    <display>...</display>
    <default-bgcolor>...</default-bgcolor>
</period-type>

Use one of these elements for each custom period type you need to define. The element has two attributes and three sub-elements.

  • ref="reference"

    A unique reference that is used by elements to refer to this period. This name should be globally unique, as future releases may give users the ability to customise background colours. To ensure global uniqueness, I recommend prefixing references with the name of the file, e.g. easters.moot. If you use the same period in two or more files, then you can give them the same name. (This doesn't really matter now, but in future Debatekeeper will treat them as the same type for user customisation purposes.) However, you must still define a custom period type in each file in which it is used.

  • pois-allowed="true"

    Set this to true if points of information are allowed in this period type. Omit or set to false if not.

  • <name>...</name>

    A human-readable name for your period type. This isn't currently used, but it's still mandatory. In the future it may be used to allow users to customise period type colours themselves.

    New in schema version 2.2: This element supports translations. To support multiple languages, include this element multiple times, with the xml:lang attribute in each one. See the multilingual formats section for more details. See the bp.xml file for an example.

  • <display>...</display>

    The phrase that gets displayed on the screen during periods of this type. If blank, nothing is displayed. If omitted, whatever was written there in the previous period stays there. (Note that blank and omitted are not the same thing.)

    New in schema version 2.2: This element supports translations. To support multiple languages, include this element multiple times, with the xml:lang attribute in each one. See the multilingual formats section for more details. See the bp.xml file for an example.

  • <default-bgcolor>...</default-bgcolor>

    The background colour used during periods of this type. Must be in HTML colour code format, i.e. #rrggbb where each two digits is a hexadecimal value for red, green and blue respectively.

    Note: Background colours in schema 2.0 are always opaque—the alpha value is not used.

Preparation time

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.

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

<prep-time-controlled length="15:00" first-period="something">
    <bell .../>
    <bell .../>
</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. If you use this, you should populate the element with elements, just like a <speech-type> (see below).

Definitions of speech types

<speech-type ref="something" length="7:00" first-period="firstmin">
    <name>...</name>
    <bell .../>
    <bell .../>
</speech-type>

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 attributes and one or more <bell> 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 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.

  • first-period, optional but recommended, is the reference of period type that this speech type should use at the beginning of the speech.

<name xml:lang="en">...</name>

Optional, new in schema version 2.2: Names of speech types are optional. If omitted, the ref attribute will be used instead. The main purpose of this element is to support translations in the format info screen.

To support multiple languages, include this element multiple times, with the xml:lang attribute in each one. See the multilingual formats section for more details. See the bp.xml file for an example.

Note: All <name> elements must come before all <bell> elements.

<bell time="6:00" number="1" next-period="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 speech type).
  • 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).
  • next-period is the reference of the period that should apply straight after this bell. This can be either a built-in period type or a custom period type (specified by its reference).

Built-in period types

The built-in period types are:

  • normal, which is a black background.
  • pois-allowed, which is a green background with points of information allowed.
  • warning, which is an orange background and should be used after a warning bell is rung.
  • overtime, which is a red background and should be (explicitly) used after the finish bell is rung. Note that Debatekeeper does not use this period automatically for finish bells; it does, however, colour the time text light red when in overtime regardless of the active period type.

The built-in period types are specified in an XML file in the source, if you want to see what they look like. If these aren't enough for you, you can always add your own custom period types.

Listing the speeches

<speeches>
    <speech>...</speech>
    <speech>...</speech>
</speeches>

All speeches go between these two tags.

<speech type="substantive" >
    <name>...</name>
</speech>

There should be one of these elements for each speech. Both the type attribute and the <name> element are mandatory.

  • <name>...</name> is the human-readable name of the speech, for example, "1st Affirmative", "Leader of the Opposition's Rebuttal"

    New in schema version 2.2: This element supports translations. To support multiple languages, include this element multiple times, with the xml:lang attribute in each one. See the multilingual formats section for more details. See the bp.xml file for an example.

  • type is the reference of the speech-type of this speech

Multilingual formats

New in schema version 2.2.

If a format is practised in multiple languages, or if the format should be translated into the user's language, the human-readable elements in format files can be specified in multiple languages. Where this is done, only one language will be shown to the user, so the different versions should all be translations of each other.

To support multiple languages, a file should:

  1. Declare the languages it supports in the <languages>...</languages> element (see above).
  2. Provide translations of all human-readable strings into each of those languages, using the xml:lang attribute.

Languages are specified as BCP 47 language tags. Type "BCP 47" into your favourite search engine to learn more. To give some common examples: English is en, Spanish is es, German is de, Chinese is zh, French is fr, Arabic is ar.

It is not necessary to declare the xml namespace. Where multiple translations of a text element are provided, those elements should all be next to each other in the file.

For example, the bp.xml file includes:

  <name xml:lang="en">British Parliamentary</name>
  <name xml:lang="es">Parlamentario Británico</name>
  <version>1</version>
  <languages>
    <language>en</language>
    <language>es</language>
  </languages>

For the <info>...</info> element, the <info> element should carry the xml:lang attribute. Its subelements, like <region>, should not specify the xml:lang attribute, because it's implied by its parent <info>.

For all other elements with human-readable text, like <name> and <display>, the xml:lang attribute should be included in that element.

It makes sense for the languages provided to be consistent throughout the file, and the official online repository enforces this. However, if a particular string is missing a language or has an extraneous one, Debatekeeper will still figure out what to do with it silently by choosing the best option among those available.

Clone this wiki locally