Difference between revisions of "User:Gregory Gauthier/JML"
(→Marking up the questions: add wrapping tags) |
(→Packet organization tags: +<subsection>) |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 27: | Line 27: | ||
The <code><packet></code> tag may contain one <code><format></code> 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 <code><packet></code> tag may contain one <code><format></code> 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 <code><packet></code> tag must contain one or more <code>< | + | The <code><packet></code> tag must contain one or more <code><section></code> tags. These are used to designate completely independent sections of the packet. Good examples are NHBB's and NAC's four-quarter formats. Two <code><section></code>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). Sections may have a <code>name</code> or <code>title</code> attribute; the name is intended for the format file's usage; the title, for labeling. A section may also have the <code>extra=true</code> attribute, this designates a specific section of extra or replacement questions. |
| − | Each <code>< | + | Each <code><section></code> tag contains stacks for each supported question type: <code><tossups></code> for tossup questions, <code><bonuses></code> for bonus questions, <code><directed></code> 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). |
| + | |||
| + | A <code><section></code> may also be divided into user-defined <code><subsection></code>s, which may be given format-specific meaning (such as allowing a team to choose a specific bonus category in NAC, or a lightning round category in NAC or NHBB). | ||
===Marking up the questions=== | ===Marking up the questions=== | ||
| Line 35: | Line 37: | ||
====General rules and attributes==== | ====General rules and attributes==== | ||
| − | Each question may have <code>category</code>, <code>subcategory | + | Each question may have <code>category</code>, <code>subcategory</code>, and <code>id</code> attributes. The <code><author></code> tag is intended to contain the name of the principal author of the question; the <code><reviewer></code> tag is intended to contain the name of a peer reviewer or editor. The <code>category</code>, <code>subcategory</code>, and <code>id</code> 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 <code><i></code> 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 <code><keyword></code> tag as a search aid or for frequency compilation; this should have no effect on the printed output. Pronunciation guides can use the <code><pron></code> tag about the written word or words, with the pronunciation guide in the <code>guide</code> 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 <code><note></code> tag. Other sorts of internal comments can be written in a <code><comment></code> tag; comments are not displayed in the packet. | Usage of HTML's <code><i></code> 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 <code><keyword></code> tag as a search aid or for frequency compilation; this should have no effect on the printed output. Pronunciation guides can use the <code><pron></code> tag about the written word or words, with the pronunciation guide in the <code>guide</code> 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 <code><note></code> tag. Other sorts of internal comments can be written in a <code><comment></code> tag; comments are not displayed in the packet. | ||
| − | ===Answer markup=== | + | ====Answer markup==== |
Answers are enclosed in an <code><answer></code> tag. The main answer should be directly contained in the <code><answer></code>. Other answers, promptable responses, and unacceptable responses should be wrapped as follows: | Answers are enclosed in an <code><answer></code> tag. The main answer should be directly contained in the <code><answer></code>. Other answers, promptable responses, and unacceptable responses should be wrapped as follows: | ||
*<code><accept></code> for also-acceptable answers | *<code><accept></code> for also-acceptable answers | ||
| Line 45: | Line 47: | ||
*<code><deny></code> for unacceptable answers that should not be prompted. | *<code><deny></code> for unacceptable answers that should not be prompted. | ||
In the first two cases above, use the <code><req></code> to mark the required parts of the answer (the parts that would be underlined in a packet) and <code><opt></code> 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). | In the first two cases above, use the <code><req></code> to mark the required parts of the answer (the parts that would be underlined in a packet) and <code><opt></code> 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). | ||
| + | |||
| + | ====Tossups==== | ||
| + | No tags are required for tossups. However, in formats that use powers (such as NAQT and NHBB), parts of the question that are in power should be enclosed by the <code><power></code> tag with <code>value</code> attribute the number of points awarded for a correct answer in power. These tags may be nested to account for super powers; the innermost power tag containing given question text determines the point value of a question correctly answered just after said text has been read: | ||
| + | <power value="20"> <power value="30"> Lorem ipsum dolor sit amet, consectetur adipisicing elit, | ||
| + | sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</power> Ut enim ad minim veniam, | ||
| + | quis nostrud exercitation ullamco</power> laboris nisi ut aliquip ex ea commodo consequat. For 10 points, | ||
| + | Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur? | ||
| + | |||
| + | The <code><tossup></code> tag may also have a <code>value</code> attribute indicating the number of points the tossup is generally worth. This is for circumstances where tossup value varies from question to question within a section (such as at NAC); most formats will not use this attribute. | ||
| + | |||
| + | ====Bonuses==== | ||
| + | Bonus lead-ins are enclosed by the <code><leadin></code> tag. Bonus parts are enclosed by <code><part></code> with <code>value</code> attribute corresponding to the total number of points available for that part. Partial credit parts should have scoring instructions stated in the question text, just as in ACF (JML does not support partial credit parts). | ||
Latest revision as of 20:04, 17 March 2013
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 <section> tags. These are used to designate completely independent sections of the packet. Good examples are NHBB's and NAC's four-quarter formats. Two <section>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). Sections may have a name or title attribute; the name is intended for the format file's usage; the title, for labeling. A section may also have the extra=true attribute, this designates a specific section of extra or replacement questions.
Each <section> 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).
A <section> may also be divided into user-defined <subsection>s, which may be given format-specific meaning (such as allowing a team to choose a specific bonus category in NAC, or a lightning round category in NAC or NHBB).
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, and id attributes. The <author> tag is intended to contain the name of the principal author of the question; the <reviewer> tag 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).
Tossups
No tags are required for tossups. However, in formats that use powers (such as NAQT and NHBB), parts of the question that are in power should be enclosed by the <power> tag with value attribute the number of points awarded for a correct answer in power. These tags may be nested to account for super powers; the innermost power tag containing given question text determines the point value of a question correctly answered just after said text has been read:
<power value="20"> <power value="30"> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</power> Ut enim ad minim veniam, quis nostrud exercitation ullamco</power> laboris nisi ut aliquip ex ea commodo consequat. For 10 points, Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur?
The <tossup> tag may also have a value attribute indicating the number of points the tossup is generally worth. This is for circumstances where tossup value varies from question to question within a section (such as at NAC); most formats will not use this attribute.
Bonuses
Bonus lead-ins are enclosed by the <leadin> tag. Bonus parts are enclosed by <part> with value attribute corresponding to the total number of points available for that part. Partial credit parts should have scoring instructions stated in the question text, just as in ACF (JML does not support partial credit parts).