<?xml version="1.0" encoding="UTF-8"?>
<!--$Id: tutor_message_v2.dtd,v 1.1.1.1 2012/10/24 23:23:21 mkomisin Exp $-->
<!--This DTD specifies a protocol for messages among tools and tutoring translators and agents.  The goal is to standardize the messaging format in order to simplify the translation process for simple tutors and pseudo-tutors and tools that want to use them.  Other kinds of programs that might use these messages include playback processors or other instances of collaborating tools.  Based on the model proposed in 'An Architecture For Plug-In Tutor Agents' (Ritter, Koedinger 1996)-->
<!--Tutor messages may be from educational tools or from optional tutoring software that observes user actions in the tool and may respond to them.-->
<!--The notion of separating ui events and semantic events is taken from the proposed IEEE LTSC specification (Ritter)-->
<!--The top-level element permits XML processors to create a well-formed document with a single root element from a collection of tutor_ or tool_messages. No tool or tutor needs to generate a tutor_related_message_sequence.-->
<!ELEMENT tutor_related_message_sequence (tool_message | tutor_message | curriculum_message | message)+>
<!--The version_number attribute should be an integer that represents the edition of this DTD to which this message set conforms.  Log readers may use this number to ensure that the reader software is compatible with this content. -->
<!ATTLIST tutor_related_message_sequence
	version_number CDATA #IMPLIED
>
<!--A tool_message is generated by a tool and typically describes a user action on that tool.-->
<!ELEMENT tool_message (meta?, problem_name?, (ui_event | semantic_event)+, event_descriptor*)>
<!--An attempt_id is used when a session id is not low enough granularity.  For example, when delivered through an LMS such as OLI, sessions may contain numerous uses of the same tool, thus the session is not unique enough of a grouping function.  Actual attempts must be grouped together.  All log entries for a particular tool use (with a single start_tutor message) should share the same attempt_id value.-->
<!ATTLIST tool_message
	attempt_id CDATA #IMPLIED
>
<!--A tutor_message conveys a tutors evaluation of an attempt, a hint or a scripting directive to the tool.-->
<!ELEMENT tutor_message (meta?, problem_name?, (ui_event | semantic_event)+, event_descriptor*, action_evaluation*, tutor_advice*, skill*, production*)>
<!--The attempt_id attribute for a tutor message has the same meaning as that for a tool_message.-->
<!ATTLIST tutor_message
	attempt_id CDATA #IMPLIED
>
<!--A problem_name identifies the transaction context in terms of the application.  The element's structure is loosely specified:  some applications may have a hierarchical problem-naming scheme and so would have to specify here course, unit and section in addition to a specific problem name.  Other applications might identify problems with a simple string or URI. The intent is to unambiguously tell what problem the student was working on. Some messages (lock widgets, e.g.) may be unrelated to any problem; in these cases the problem name may be omitted.-->
<!ELEMENT problem_name ANY>
<!--The ui_event element(s) makes available a place for a tool to log low-level user interface events.  It might want a special format for machine processing (aimed at fine-grained reproduction on playback, e.g.) or it could be a description intended for human readers.  Examples might include a single key press, a mouse movement, etc.  -->
<!ELEMENT ui_event ANY>
<!ATTLIST ui_event
	id CDATA #IMPLIED
>
<!--The semantic event is an event (at a higher level than a ui_event) of interest to, e.g., a tutor, a higher-level playback processor or a collaborating tool.  The content of the event is unspecified in this DTD:  it may be a human-readable or domain-specific representation of the event.  The id attribute uniquely identifies the event at least within the session.  The semantic_event_id attribute links this event to a trigger event, so that tutor messages generated in response to tool messages may be associated with the triggering event.  The name attribute labels the semantic event in a way significant to tutors or other message processors:  examples of tool events include ATTEMPT, HINT_REQUEST, START_TUTOR, STOP_TUTOR; examples of tutor events include RESULT, HINT_MSG.  The trigger attribute should be USER if the triggering event was a user action.-->
<!ELEMENT semantic_event ANY>
<!ATTLIST semantic_event
	id ID #REQUIRED
	semantic_event_id IDREF #IMPLIED
	name CDATA #IMPLIED
	trigger (USER | DATA) #IMPLIED
>
<!--An event_descriptor contains the details of a single observable (visible, audible, etc.) change in the state of a user interface.  This descriptor will usually detail changes initiated by users, but tutors, e.g., could change the state of a tool's interface. In particular, for hint responses, the event descriptor should describe the correct action on this step: the tool may highlight the indicated selection in conjunction with displaying the hint text.-->
<!ELEMENT event_descriptor (action*, selection*, input*)>
<!--Where multiple ui_events or semantic_events are in a message, an event_descriptor can point to the particular XXX_event via this reference.-->
<!ATTLIST event_descriptor
	event_id IDREF #IMPLIED
>
<!--Examples of tool actions could be ButtonPressed, UpdateTextArea, PourSolution, etc.  An example of a tutor action could be to update a textarea or highlight a tool widget.-->
<!ELEMENT action (#PCDATA)>
<!--Actions may have unique identifiers in addition to their values-->
<!ATTLIST action
	id CDATA #IMPLIED
>
<!--A selection is the user interface widget or other element indicated when a user takes an action.  Some actions will involve multiple selections; e.g. a PourSolution action in a lab might involve 2 selected solutions.-->
<!ELEMENT selection (#PCDATA)>
<!--Selection elements may have unique identifiers in addition to their names.-  A selection type may distinguish the role this particular selected item plays in an action having multiple selected items; e.g. a PourSolution action could have a solution of type "source" and one of type "recipient".-->
<!ATTLIST selection
	id CDATA #IMPLIED
	type CDATA #IMPLIED
>
<!--Input from a tool is generally user input, e.g., the text typed into a textarea widget. Input from a tutor might be text that the tool should display in a textfield.-->
<!ELEMENT input (#PCDATA)>
<!--Input elements may have unique identifiers in addition to their values-->
<!ATTLIST input
	id CDATA #IMPLIED
>
<!--An action_evaluation is the result of a tutor's check to see whether user input was correct.  Examples of action_evaluations include CORRECT, BUG, INCORRECT, HINT.-->
<!ELEMENT action_evaluation (#PCDATA)>
<!--An HINT action evaluation may have associated data.-->
<!ATTLIST action_evaluation
	current_hint_number CDATA #IMPLIED
	total_hints_available CDATA #IMPLIED
>
<!--The tutor_advice contains the body of a HINT_MSG, the success or buggy message for a RESULT, etc.-->
<!ELEMENT tutor_advice (#PCDATA)>
<!--Updates to skill level(s) may be generated by a tutor as a user completes a step in a problem. ** need an example ** -->
<!ELEMENT skill (#PCDATA)>
<!--Some skills can have an associated probability.-->
<!ATTLIST skill
	probability CDATA #IMPLIED
>
<!--A tutor might fire one or more productions to analyze a step in a problem. An example production [from WPI]: "G.1.8-understading-polygon-geometry".-->
<!ELEMENT production (#PCDATA)>
<!--A curriculum_message conveys information about the tutoring context:  it may describe the exercise in its global context of school, course, etc. It may include information that a curriculum management system needs to select a next exercise.-->
<!ELEMENT curriculum_message (meta?, school_name?, course_name?, unit_name?, section_name?, problem_name?, dfa*, skill*, production*)>
<!--The attempt_id attribute for a curriculum message has the same meaning as that for a tool_message.  The name attribute gives the message purpose; examples include START_PROBLEM, STOP_PROBLEM, UPDATE_SKILL_MASTERY.-->
<!ATTLIST curriculum_message
	attempt_id CDATA #IMPLIED
	name CDATA #IMPLIED
>
<!--An school is the institution or other organization where this activity is taking place.-->
<!ELEMENT school_name (#PCDATA)>
<!--A course is a course of study, such as 8th-grade mathematics or microeconomics or intermediate French, or the title of a textbook.-->
<!ELEMENT course_name (#PCDATA)>
<!--A unit is a high-level division of a course.-->
<!ELEMENT unit_name (#PCDATA)>
<!--A section is a lower-level division of a course.-->
<!ELEMENT section_name (#PCDATA)>
<!--Difficulty factors analysis is data associated with this problem.  We recommend data of this sort, if available, be included with information logged by a START_PROBLEM entry.-->
<!ELEMENT dfa ANY>
<!--The message element is a facility for arbitrary communications content to be accommodated in this DTD.  A message might contain one or more property elements.-->
<!ELEMENT message ANY>
<!--The attempt_id attribute for a message has the same meaning as that for a tool_message.-->
<!ATTLIST message
	attempt_id CDATA #IMPLIED
>
<!--A property is a name-value pair. The value might be a list of entries.-->
<!ELEMENT property (#PCDATA|entry)*>
<!ATTLIST property
	name CDATA #REQUIRED
>
<!--An entry is a single value in a list of entries.-->
<!ELEMENT entry (#PCDATA)>
<!--Meta level data.  This block of data may be known to the agents, translators or tools without needing it to be encoded in the message itself.  However, if such data is not available, it can be encoded in the message, although it is really part of the communication.  Given potential differences in location of agents and tools (often experienced with a web-based tool), time zone is required.-->
<!ELEMENT meta (user_id, time, time_zone, session_id)>
<!ELEMENT user_id (#PCDATA)>
<!ELEMENT time (#PCDATA)>
<!ELEMENT time_zone (#PCDATA)>
<!ELEMENT session_id (#PCDATA)>
