iProv XML File Format

XML is a file format where items are marked up with tags appearing between <angle-brackets>. You can read about XML on Wikipedia, but basically if you open and look at the file you'll get the idea.

The nice thing about XML is that it's human-readable. The not-so-nice thing about it is that even though you can tell what's going on, it's a pain to read and edit by hand.

So most likely working on this file is going to take some patience, and believe me, that patience is appreciated. If you know of or discover any good, free tools for editing the file (other than the ones mentioned on previous pages), please let me know and I'll post about them here.

Overall structure

<dataroot>
    <items>
        <itemName> ... </itemName>
        <itemText> ... </itemText>
        <variations> ... </variations>
        <aka> ... </aka>
        <seeAlso> ... </seeAlso>
        <tags> ... </tags>
    </items>
    
    <items>
        <itemName> ... </itemName>
        <itemText> ... </itemText>
        <variations> ... </variations>
        <aka> ... </aka>
        <seeAlso> ... </seeAlso>
        <tags> ... </tags>
    </items>
    
    <items>
        <itemName> ... </itemName>
        <itemText> ... </itemText>
        <variations> ... </variations>
        <aka> ... </aka>
        <seeAlso> ... </seeAlso>
        <tags> ... </tags>
    </items>

    ...
</dataroot>

• Every item MUST have both an itemName and an itemText. These serve as the name and the description of the item, respectively.
• The variations, aka (short for "also known as"), seeAlso and tags fields are all optional.
• Always search the file before creating new entries. Make sure that your game doesn't already exist under a different name (in which case you should list it as an AKA or a variation).
• When creating new entries, add them at the end of the file. Do not worry about alphabetization, as they can be sorted by other programs. (After a while, your new entry might be moved to an alphabetized location.)

Variations

• Where appropriate, these should be bulleted with the caret (^) symbol at the beginning of a line.
• A named variation may be created by bulleting with a ^ at the beginning of a line and entering the name followed by another ^ at the end of the name, followed by the rest of the description.
  • Named variations show up as their own entries on the iPhone application, but when selected show you the information screen for the main game.
  • See Freeze Tag for an example of this, or One Word Story for an example that combines both named variations and regular, unnamed bullets.

Also known as

On the iPhone application, the aliases will show up as their own entries but redirect when selected to the main entry.

Make sure the name you use isn't used anywhere else in the file! Lots of names are used differently in different regions, so make sure you aren't conflicting with something already in place.

See also

Make sure the name you add exists as the name of an item in the file, and is spelled correctly! Only use the proper itemName names of entries, not a named variation or a value from the aka field.

Tags

Guidelines for tagging:

• Don't create a new tag that's close in meaning to an existing one.
• Don't create a new tag unless you're prepared to go through the entire file and tag appropriate entries.
• Good tags will help identify a reasonable-sized chunk of items. A tag that identifies only a few or more than a handful of items loses its usefulness.
• There are, however, some exceptions to the previous rule, including but not limited to:
  • The shortform tag is used almost everywhere to identify shortform from longform (which doesn't appear much in the file yet). All entries should be tagged as either "shortform" or "longform".
  • The scene tag is used to identify any game that involves an actual scene being played, as opposed to a game. Generally speaking, all shortform entries should be tagged as either "scene" or "game".
• Double-check the spelling of your tags. Misspelled tags ruin Christmas for everyone, and are likely to cause your changes to be removed rather than anyone wanting to go through the headache of fixing your mistake.

Some common tags, and when you should use them:

• shortform: Tag EVERYTHING that can be considered shortform with this. (Likewise, be sure to tag anything that is longform.)
• scene and game: Just about anything shortform should have either one or the other to distinguish if it's scene-based or not.
• endowment: Things that prominently involve a characteristic being gifted to a performer. Includes "guessing games"; these are mostly distinguished by also having the timed and/or game tags.
• exercise: These are less performance-oriented and more suited towards skill development.
• directed: An MC or other improviser "controls" the scene, such as with a bell or by pointing at who is to act.
• narrated and narrative: narrated has a specific narrator accompanying the scene, where narrative has an especially storytelling-driven focus.
• toss-up: Useful as an elimination game in competetive improv

Most of the other tags should be self-explanatory.