User:Gregory Gauthier/JML

This is a working draft of the JAGUARS markup language. It is currently unused, but the intent is to make a standard to supersede the de facto standard of .DOC files that is (1) readable on any computer, (2) easy for a computer to process, and (3) hard for neophytes to deviate from in subtle ways.

(The alpha version of JAGUARS currently uses a hackish, hard-to-maintain, and user-unfriendly system of parsing an HTML file generated from a .DOC file through the program LibreOffice.)

Tools that ought to be made

• A WYSIWYG editor that saves in JML.
• Converters to
  • .DOC
  • .ODT
  • NAQT's markup language
  • LaTeX
• A way to display a packet of JML formatted questions in rich text so they can be saved as a .DOC file.

Tags

(Based on QBML. This is based off of a 2009 Aegis file; since then, I have thought of some improvements. Also, I am well aware of xkcd's admonition against creating new standards without good reason.)

All JML files are XML; therefore, a starting tag like

<?xml version="1.0" encoding="UTF-8"?>

is required.

Packet organization tags

The outer tag is the <packet> tag. Optional attributes are title, year, tournament, and number, which should be self-explanatory.

The <packet> tag may contain one or more <author> tags, which surround each author. These authors may be individuals or organizations.

The <packet> tag may contain one <format> tag. Originally, the intent was to encode all relevant aspects of the format into this tag; however, it may be easier to use this tag to instead name a format (ACF, NAQT, NHBB, IHSA, NAC, CAC, WRAL Brain Game, practice, etc.), the computerized version of whose gameplay rules can be retrieved from a standard library of format files.

The <packet> tag must contain one or more <part> tags. These are used to designate completely independent parts of the packet. Good examples are NHBB's and NAC's four-quarter formats. Two <part>s may be used for IHSA packets (due to matched bonuses). ACF and NAQT-format packets should use only one of these tags for its regulation questions (ACF does not segregate the bonuses by half, and NAQT does not segregate any questions by half). Parts may have a name or title attribute; the name is intended for the format file's usage; the title, for labeling. A part may also have the extra=true attribute, this designates a specific part of extra or replacement questions.

Each <part> tag contains stacks for each supported question type: <tossups> for tossup questions, <bonuses> for bonus questions, <directed> for any sort of directed round wherein the questions are read to a designated team (lightning round, It's Academic-style team round, worksheet round).

Marking up the questions

Each question is wrapped in a <tossup>, <bonus>, or <directedround> tag.

General rules and attributes

Each question may have category, subcategory, author, reviewer, and id attributes. The author attribute is intended to contain the name of the principal author of the question; the reviewer attribute is intended to contain the name of a peer reviewer or editor. The category, subcategory, and id attributes are user-defined. (It might be interesting to have a common taxonomy for questions, but this is probably not manageable, and most freely-available questions that could benefit from such a common taxonomy will probably already use ACF-style categories.)

Usage of HTML's <i> tag to mark up titles of works that ought to be italicized is encouraged. Any word in a question may be marked up with a <keyword> tag as a search aid or for frequency compilation; this should have no effect on the printed output. Pronunciation guides can use the <pron> tag about the written word or words, with the pronunciation guide in the guide attribute. (And if someone wants to try nesting pronunciation guides in a JML-formatted packet, I'm going to _____.) Moderator notes can be wrapped in a <note> tag. Other sorts of internal comments can be written in a <comment> tag; comments are not displayed in the packet.

Answer markup

Answers are enclosed in an <answer> tag. The main answer should be directly contained in the <answer>. Other answers, promptable responses, and unacceptable responses should be wrapped as follows:

• <accept> for also-acceptable answers
• <prompt> for promptable answers
• <deny> for unacceptable answers that should not be prompted.

In the first two cases above, use the <req> to mark the required parts of the answer (the parts that would be underlined in a packet) and <opt> for optional parts of the answer (parts that are acceptable but that the moderator should not read; think of the parenthesized parts of an NAQT answer line). For more than the most simple answer lines, I can't think of a straightforward way to markup the answer both for quiz bowl standards and for computer judging (such as on an IRC channel or automatically graded online quiz).