%nicht vergessen: auch srd.tex ($Revision $) \"andern !

\part{Software Requirements Document}

This Software Requirements Document is structured along the modules

abstracted from the functionality defined in the User Requirements

Document. The User Requirements Document, however, is structured along

the different kinds of users envisaged. In order to establish

comfortable tracing, the $m:n$ relation between user requirements and

software requirements will be accurrately recorded in a double-linked

way.

\chapter{General requirements}

%One goal of this section is to achieve a smooth design and minimize the effort in development. Although \sisac consists of a number of (more or less) autonomous modules, a number of developments can be shared.

\section{Delopment environment,} standards and components, documentation and revision control are described in appendix \ref{AP:environment}.

\section{Decisions for underlying systems} have been done already.

As this requirements document shows, \sisac{} is a large system: thus it cannot be done from scratch, rather is has to use as much as components already available. The theorem prover Isabelle provides for both, a comprehensive frontend for interactive deduction (i.e. for definitions, axioms and proving theorems), and a hughe mathematics knowledge base. Both are under rapid development, which \sisac{} shall take advantage of. The kernel of Isabelle, however is relatively stable already, and thus the interfaces to \sisac s math engine (ME) are sufficiently stable.

{\bf\SR The deductive part is left to Isabelle. \label{deduct-isa}}

{\bf\SR \sisac s math engine closely cooperates with Isabelle \label{me-isa}\\}

Thus the math engine is already implemented in the same program language as Isabelle, SML.

%dropped: visitor canNOT calculate !

%

%\subparagraph{The call hierarchy} between the components underlies a severe restriction due to UR \ref{access-ab} and UR \ref{isac-www}: Because a browser can only deliver a HTTP-request, the worksheet must start browsers, too (and not only the dialog, as it would be desirable w.r.t. the system architecture).

%{\bf\SR Browsers are called by a 'master-browser' {\em and} by the worksheet. \label{}} ??? %WN2.12.02 ...... ausbessern !!!!

\section{The connection between Java and SML} has to be 'hand-made'. During the next few years there will be several changes at the interfaces between the

 \sisac-components belonging to these two language environments. 

{\bf\SR The SML-kernel is started by a java thread \label{}} which controls the time-out eventuall resulting from non-terminating loops in the knowledge interpreter.

{\bf\SR The SML standard-output channel is read by parsers, \label{}} one for the SML-structures, and one for the mathematics formulas embedded in the SML-structures.

\section{System requirements for the users:} Users (with exception of the math authors, which work directly on the SML-kernel) are expected to work on standard-browsers (UR \ref{browser}) and some additional software components.

{\bf\SR On the client-side a Java virtual machine version .... \label{}} must reside on the local computer of the learners and authors.

{\bf\SR On the server there is a Linux or Unix \label{}} operating system, Linux version ..., Unix ...

\section{Communication in the distributed system}

%WN050518---AK.p.58-61->isac-SRD--------BEGIN---please don't remove this line

\footnote{Begin of copy from \cite{AK04:thesis} p.58-61.}

\subsection{Choosing a Means of Communication}\label{AK:DESIGN:SYSTEM:DISTRIBUTE:comm}

For integration of the various components across several machines an off-the-shelf solution was sought with the following criteria in mind: 

\begin{description}

\item[Speed] Many of the user's requests originating on the Worksheet require processing in the Math Engine. With \isac{} being an interactive system, we need response times near the response times in normal human interaction.

\item[Security] With many of the features of \isac{} depending on the identity of the user and the enforcement of access rights, basic security features are a necessity.

\item[Mobility] Users might want to use \isac{} at work, in class or at home, even on computers they use only occasionally. This asks for communication robust against changing addresses of client and server computers, but still secure.

\item[Conformity to Standards] is especially important for the Worksheet, which runs on the user's machine. An ideal solution would build on standard resources available on the user's machine without the need of additional installation. If installation is required, it must be kept as simple as possible. 

With the goal of being open to cooperation with the tools of other projects, a standard solution would ease integration of the different systems.

In addition to that, a standard solution is preferred with the limited resources of the \isac{} project in mind. 

\end{description} 

Several options were reviewed to find a suitable means of communication, among them Java-RMI \footnote{http://java.sun.com/products/jdk/rmi/}, XML-RPC \footnote{http://www.xmlrpc.com/spec}, SOAP \footnote{http://www.w3.org/TR/SOAP} and Dinopolis \footnote{http://www.dinopolis.org/}.

While the Dinopolis approach looked most promising with respect to the aforementioned criteria, it was not yet available in a stable implementation.

Java-RMI was chosen for the implementation of the \isac{} prototype. The strongest arguments for Java-RMI were the seamless integration into the Java programming environment and the widespread use and accepted stability.

\subsection{The Dinopolis Middleware project}\label{AK:DESIGN:SYSTEM:DISTRIBUTE:dino}

% pl: Wie schon in meiner e-mail bemerkt, sollten Sie hier lieber Java-RMI

% skizzieren, das Sie benutzen und nicht Dinopolis, das Sie nicht benuetzen.

Dinopolis \cite{dino2002} is an object management middleware system aiming at object and component retrieval, security and run-time polymorphism. While not part of the current implementation of \isac{}, Dinopolis still played an important role during the design phase.

The main features of Dinopolis include:

\begin{description}

\item[Component and object management]

Extending the traditional data-and-operations view, Dinopolis objects have the following aspects, all handled by the middleware: 

\begin{description}

\item[Content] is the traditional data content.

\item[Meta-Data] can be used for administrative purposes which are not necessarily reflected by the content. 

\item[Interrelations] associate several objects, of equal or different types, in a m:n manner.

\item[Operations] manipulate the content of an object.

\item[Services] are GUI building blocks offered by an object to facilitate data manipulation by the user. Services can be viewed as the View and Controller parts of a MVC triple.

\end{description}

All of these aspects are handled transparently by the Dinopolis middleware according to the current run-time context, which not only takes burden from the programmer, but also allows for run-time dynamic typing as a key feature.

Objects and components are accessed through Globally Unique Handles (GUH), a mechanism allowing for unambiguous retrieval of objects independent of their physical locations  \cite{DOLSA}.

\item[Role-based security]

Dinopolis takes control over access to components, objects, their data and operations. Access control is based on the user and his role as opposed to the user's identity alone. With Dinopolis, the same user would have different access rights and therefore see different aspects and different behaviour of objects depending on whether he accesses \isac{} as administrator, teacher or student. All security-relevant operations are handled transparently by the Dinopolis middleware, so the only task left to \isac{} is to identify the user. As far as objects are concerned, the transparent security system may be considered a special case of dynamic typing described above.

\item[Ability to embed existing systems]

Existing systems can easily be integrated into Dinopolis by writing embedders for existing objects such as databases. This could ease integrating \isac{} with other projects without the need to define common data structures. In addition to that, the SML part of \isac{} could easily be integrated this way.

\item[Platform-independency]

At present, Dinopolis is being implemented in C++ and Java, but the protocols and algorithms are open to arbitrary programming languages.

\end{description} 

The features mentioned above make Dinopolis ideally suited for the needs of \isac{}, for communication of the various distributed components as well as for security and role-dependent behaviour of the system. Unfortunately, Dinopolis is still being developed and was not finished in time to base the current prototype of \isac{} on. The \isac{} team still hope to use the features of Dinopolis in future versions.

\subsection{Java-RMI}\label{AK:DESIGN:SYSTEM:DISTRIBUTE:rmi}

Java Remote Method Invocation provides for communication of processes running in different Virtual Machines, even if the VMs run on different computers. Basically, RMI provides invoking methods on remote objects and passing parameters to remote methods. RMI cannot be compared directly to Dinopolis, because RMI's purpose is communication between remote objects, but not object retrieval, system security or dynamic typing.

To invoke methods on a remote object, the remote object has to implement a public remote interface extending \texttt{java.rmi.Remote}. Every method in the remote interface has to declare to throw \texttt{RemoteException}. The remote object may implement other methods in addition to the remote interface, but only the methods in the remote interface can be invoked remotely.

Any objects implementing the \texttt{java.io.Serializable} interface can be passed as parameter. Unlike other distributed component systems, this is the only condition imposed on parameters.

Apart from the non-restrictive conditions listed, remote objects can be used like local objects once a connection is established. 

This tight integration into the Java programming environment is the key advantage of Java-RMI and one of its few drawbacks, as it is limited to Java as a programming language.

\footnote{End of copy from \cite{AK04:thesis} p.58-61.}

%WN050518---AK.p.58-61->isac-SRD--------END---please don't remove this line

\begin{verbatim}

-------- Original Message --------

Subject: Re: RK noch eine Bitte

Date: Thu, 31 May 2007 18:56:28 +0200

From: Walther Neuper <neuper@ist.tugraz.at>

To: isac@ist.tugraz.at

References: <465DA1BD.506@ist.tugraz.at> <465DECBF.5030607@sbox.tugraz.at>	<465EE077.9000504@ist.tugraz.at> <20070531175410.b9zz0p64g00cckgo@webmail.tugraz.at>

Robert Könighofer wrote:

> Zitat von Walther Neuper <neuper@ist.tugraz.at>:

> 

>> _noch_ eine Frage zu Eurer, Deiner und Nelles, Arbeit an der HTL: laut

>>

>>     http://java.sun.com/developer/onlineTraining/rmi/RMI.html

>>

>> sollte RMI bei Firewallproblemen _automatisch_ auf http-tunneling 

>> schalten (..it is blocked by the firewall. When this happens, the RMI 

>> transport layer automatically retries by encapsulating the JRMP call 

>> data within an HTTP POST request. etc..)

>>

>> Habt Ihr bei Eurer Arbeit davon bemerkt ?

> 

> Nein, leider.

> 

Ah, sehr interessant, dass das nicht so läuft ...

> Die einleitenden Worte würden schon irgendwie darauf hindeuten, dass das 

> alles automatisch passiert. Davon haben wir allerdings leider nichts 

> bemerkt. Vielleicht haben wir uns dieses feature auch unabsichtlich 

> selbst deaktiviert, als wir anstelle der Default Sockets zur 

> Kommunikation unsere eigenen Sockets mit fixierten Ports aktiviert haben.

> 

?!?!?

> [...]

> "If a client is behind a firewall, it is important that you also set the 

> system property http.proxyHost appropriately. Since almost all firewalls 

> recognize the HTTP protocol, the specified proxy server should be able 

> to forward the call directly to the port on which the remote server is 

> listening on the outside."

> 

... das gilt für die Firewall auf der Serverseite; wir brauchen aber nur 

die Firewall auf der Clientseite beachten, da der isacserver am IST 

_vor_ der Firewall (in der dmz) läuft !

> [...]

Vielleicht ist das Ganze einfacher, als wir denken !?!

> 

> lg RK

> 

lg Walther

-- 

------------------------------------------------------------------------

Walther Neuper                          Mailto: neuper@ist.tugraz.at

Institute for Software Technology          Tel: +43-(0)316/873-5728

TUG University of Technology,              Fax: +43-(0)316/873-5706

and HTL Ortweinschule, Graz, Austria      Home: www.ist.tugraz.at/neuper

------------------------------------------------------------------------

-------- Original Message --------

Subject: Re: RK noch eine Bitte

Date: Fri, 01 Jun 2007 12:35:28 +0200

From: Nebojsa Simic <nelle@sbox.tugraz.at>

To: Walther Neuper <neuper@ist.tugraz.at>

References: <465DA1BD.506@ist.tugraz.at> <465DECBF.5030607@sbox.tugraz.at>	<465EE077.9000504@ist.tugraz.at>	<20070531175410.b9zz0p64g00cckgo@webmail.tugraz.at>	<465EFE3C.5030502@ist.tugraz.at>

Quoting Walther Neuper <neuper@ist.tugraz.at>:

> Robert Könighofer wrote:

>> Zitat von Walther Neuper <neuper@ist.tugraz.at>:

>>

>>> _noch_ eine Frage zu Eurer, Deiner und Nelles, Arbeit an der HTL: laut

>>>

>>>    http://java.sun.com/developer/onlineTraining/rmi/RMI.html

>>>

>>> sollte RMI bei Firewallproblemen _automatisch_ auf http-tunneling  

>>> schalten (..it is blocked by the firewall. When this happens, the  

>>> RMI transport layer automatically retries by encapsulating the  

>>> JRMP call data within an HTTP POST request. etc..)

>>>

>>

> ... das gilt für die Firewall auf der Serverseite; wir brauchen aber  

> nur die Firewall auf der Clientseite beachten, da der isacserver am  

> IST _vor_ der Firewall (in der dmz) läuft !

Das grosste Problem ist dass ISAC Client gleichzeitig ein RMI Server ist ...

Um die Events (CalcChanged + doUIAction) die von Dialog->Worksheet  

gehen, der ISAC Client registriert einen RMI Server auf der Client  

Machine ... Und wenn der Server versucht, die Verbindung aufzubauen,  

dann scheitert das ganze am Client Firewall ...

Das alles schaut grob so aus :

WindowApplication                 ISAC Server

RMI Client        --------------> RMI Server( 1040, 1050 , ... )

RMI Server (3113) <-------------- RMI Client

Wir haben das ganze so umgeschrieben dass die RMI Sockets umgekehrt  

funktionieren ... Das ist eigentlich schwer zu erklären, aber es  

schaut das ganze so aus :

RMI Client              --------------> RMI Server( 1040, 1050 , ... )

Quasi RMI Server (3113) --------------> Quasi RMI Client

Das Problem da ist, dass ganze sehr empfindlich ist ... Falls die  

Verbindung aufgebrochen wird, gibt es kein mechanismus um die wieder  

aufzubauen und das System wartet ewig darauf ...

Beim letzten versuch im HTL war die kommunikation zwischen Client und  

Server schon aufgebaut (wir konnten alle browser fenster aufmachen),  

aber es war, wie schon gesagt, sehr instabil bzw. hat das System oft  

abgesturzt ....

Meine vermutung ist dass im ReverseClientSocket und  

ReverseServerSocket ein bug liegt oder dass man diese klassen  

irgendwie umbauen muss ...

-- 

lG,

Nelle

\end{verbatim}

\chapter{The worksheet}

A worksheet is the protocol of a more or less interactive calculation of an example, and it offers access to all services necessary to calculate the result of the example. 

\subparagraph{A calculation mirrors the structure of the prooftree.}

{\bf\SR The structure of a calculation is given by the ME. \label{}} Consequently any editing in a calculation affects the parts depending on the edited formula or tactic. Edit the worksheet w.r.t. UR \ref{edit} for publication etc. is done outside \sisac{} after having exported the calculation.

{\bf\SR Export a calculation to a standard format \label{}} preferably XML plus MathML. 

%{\bf\SR \label{}}

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

%--------------------------------------------------------------------------------------------------------

% FIXXME RK, Oct. 2006 old version:

% \chapter{The browser generators}

%  \sisac's mathematics knowledge (on (1)theories (2)problems (3)methods)

%  is held in SML datastructures. Here we describe all requirements

%  concerning the generation of the browsers written in Java, whereas

%  the generation of the math knowledge itself is described in the

%  'interfaces for authors of math knowledge'.

% 

% The browser generators provide the contents for the browsers. This

% means that a browser querys its respective browser generator about

% subnodes etc. whereas the further description is held outside the

% SML-engine. To maintain this connection, unique identifyer are needed.

% {\bf\SR browser-generators use locally unique identifyers \label{}} (locally unique within SML) for their informations (for each node of their structure).

% 

% \subparagraph{Data are structured hierarchically,} i.e. the problems, methods and examples. (The theories for a directed graph without cycles; thus it also can presented by a hierarchy.)

% {\bf\SR The hiearchy  displayed in a frame \label{}} in order to have it visible all the time.

% {\bf\SR The hierarchy has arbitrary levels. \label{}} For the headlines for each level see SR \dots SR \ref{expl-headlines}.

% {\bf\SR The hierarchy shows the position \label{}} of the related element displayed in the browser-window; for this purpose an additional button is required, because the 'back' and 'forward'-button on the browser may disconnect the relation.

% 

% 

% \section{The theory browser generator}

% The generation of the theory browser is already implemented by Isabelle. Within phase 1 of development, \sisac{} will take this component without any change.

% {\bf\SR The theory browser generator is given by Isabelle. \label{gen-isa}} 

% 

% \section{The problem and method browser generators}

% .

% 

% \section{The example browser generator}

% This authoring component comprises all tools necessary to generate the content displayed by the example browser. 

% 

% {\bf\SR The headlines of the example-hierarchy: \label{expl-headlines}} The hierarchy comprises the labels of the chapters, sections, subsections etc. plus the respective head line, and the blocks of examples with the respective labels -- all defined by the user (see UR \ref{UR161a}). 

% 

% {\bf\SR Integrated editors for text, formulas and figures. \label{}} This integration should be as smooth as possible; it includes an MathML-based formula-editor for the formalization.

% 

% \chapter{The knowledge browsers}

% \label{kbrowser}

% %W.N.: dieser Abschnitt ist f''ur A.G. + W.N.

% All browsers (Example-Browser and Knowledge-Browsers) present their

% output in a similar way. Textual descriptions have to be combined with

% images, formulas, formalisations, problems, \dots and links to further

% informations(UR\ref{URinterlink}). The structure of this informations

% has to be taken from the respective browser-generators. All kinds of

% information might be interlinked among each other, but not all parts

% of the information might be already present in the system when a new

% item is inserted. (e.g. a example might use the keyword

% \emph{is\_rooteq\_in} in its \emph{where}\/clause before the keyword

% is described in the system. If the example is viewed after a

% description became available, a link to the explanation should be

% provided automatically.) To support this feature, the browsers need a

% fast way to look up a special description.

% {\bf\SR fast look up for description (includes resolve of the

% identifyer and query for a description)}

% 

% \subparagraph{Groups of users} are usually 1-to-1 related to courses; members of courses get specific examples and specific advice by explanations.

% {\bf\SR Each user is assigned exactly one group during a session. \label{}} The user, however, may start another session as a member of another group.

% {\bf\SR There is a default group for visitors. \label{}}

% {\bf\SR \label{}}

% 

% \subparagraph{Additional data and visibility properties:} A considerable part of the data are additional to the data generated from the SML structures. The visibility concerns enabled or disabled links from problem and methods, and the access to examples from the hierarchy frame. There are respective time constraints on the visibility.

% {\bf\SR Additional data and visibility are course specific. \label{}}

% {\bf\SR Time constraints are given by intervals; \label{}} there are specific values for the limits of the interval indicanting infinity (contraint is given from the very beginning, or lasts forever).

% 

% 

% \section{The theory browser}

% The theory browser is already implemented by Isabelle. Within phase 1 of development, \sisac{} will take this component without any change.

% {\bf\SR the theory browser is given by Isabelle. \label{}} 

% 

% \section{The problem and method browsers}

% %\subparagraph{Static and dynamic views onto the KB} are provided by both browsers. Thus the (HTML-) presentation is generated dynamically. The dynamic view for problemjs concerns instantiation by a model of the current calculation on the worksheet. The dynamic view for methods concerns marking the tactic currently applied in a calculation.

% %{\bf\SR Browsers create the presentation in browser-windows dynamically. \label{}}

% 

% \subparagraph{Additional data} are explanations and typical examples which may be provided for each problem and each method. Both of these kinds of additional data are spcific for courses and may underly time constraints (UR \ref{expl-locked}, UR \ref{invisible}, UR \ref{restrict-know}). 

% 

% The primary contents are the respective problem and the respective method; {\em all} other data are reachable by links. This holds for special mathematical data (on rulesets etc.) from SML, too.

% {\bf\SR A problem-page consists of \label{problem-page}} the 

% \begin{tabbing}

% 12345\=123\=123\=\kill

% \>name of the problem\\

% \>the fields 'given', 'where', 'find' and 'relate'\\

% \>a link to the special math data\\

% \>a list of subordinated methods (only displayed in the hierarchy-frame)\\

% \>an arbitrary list of links to additional data

% \end{tabbing}

% The next lower and next higher level in the hierarchy can be found in the hierarchy-frame.

% {\bf\SR A method-page consists of \label{method-page}}

% \begin{tabbing}

% 12345\=123\=123\=\kill

% \>name of the method\\

% \>the script\\

% \>a link to the special math data\\

% \>a list of subordinated methods (only displayed in the hierarchy-frame)\\

% \>an arbitrary list of links to additional data

% \end{tabbing}

% {\bf\SR The links to additional data \label{}} have the following attributes:

% \begin{tabbing}

% 12345\=123\=123\=\kill

% \>text on the link\\

% \>the reference (to an explanation or to an example starting a worksheet)\\

% \>groups\\

% \>\>ID of first group\\

% \>\>\>locked: list of intervals\\

% \>\>\>???used by userID ---$>$ usermodel???\\

% \>\>ID of second group \dots

% \end{tabbing}

% %{\bf\SR Explanations and examples are optional. \label{}} For each problem and each method there is {\em one ???} link for the explanations and {\em one} link for the examples (which may be disabled).

% %{\bf\SR Access to explanations and examples of other courses \label{}} is possible by ... ??? (see UR \ref{other-courses}).

% 

% 

% 

% 

% \section{The example browser}

% In contrary to the problem and method browsers, the presentation of the contents of a browser-window is {\em not} generated automatically. UR \ref{expl-layout} requests for a layout 'handmade' by the course designer; there are, however, a lot of attributes invisible for the learner to be added by the course designer, too.

% 

% \subparagraph{Attributes of examples and collections} are numerous, and thus defaults help to safe space. There is only one collection, partitioned hierarchically into subcollections.

% {\bf\SR Default data \label{}} are filled in bottum up: A default is filled by the first non-default parent.

% {\bf\SR A subcollection has the attributes \label{coll-attr}}

% \begin{tabbing}

% 12345\=123\=123\=123\=123\=\kill

% \>headline of the collection (displayed also in the hiearchy-frame) \\

% \>description of the collection\\

% \>list of subcollections\\

% \>OR\\

% \>layout of examples belonging to this subcollection\\

% \>author\\

% \>copyright owner\\

% \>groups of users, for each group: \\

% \>\>ID of the group \\

% \>\>schemas \\

% \>\>\>error \\

% \>\>\>fill-in \\

% \>\>\> \\

% \>\>dialog \\

% %\>\>\>blackbox \\

% \>\>\>detail \\

% \>\>\>activity \\

% \>\>\>stepwidt \\

% \>\>\> \\

% \>\>invisible: list of intervals OR duration (? TODO !)\\

% \>\>locked: list of intervalsOR duration (? TODO !) \\

% \>\>evaluation \\

% \>\>\>TODO: difficulty, length, \dots \\

% \>\>\>finished-by: \\

% \>\>\>\>elements: list of mandatory examples (or groups) to be done \\

% \>\>\>\>number: number of (arbitrary) examples (or groups) to be done \\

% \>\>\>\>points: calculated from TODO: difficulty, length, \dots \\

% \end{tabbing}

% Pay attention to the entry 'list of subcollections OR ayout of examples belonging to this subcollection': This means that the subcollection {\em exactly one} hierarchy-level above the bottom of individual examples has a specific content, the graphical layout of the examples. This is in order to meet UR \ref{expl-layout}.

% 

% 

% {\bf\SR An example has the attributes \label{expl-att}}

% \begin{tabbing}

% 12345\=123\=123\=123\=123\=123\=\kill

% \>label \\

% \>reference ??? to the description of the example (in the layout ?)\\

% \>list of formalizations and specifications \\

% \>author\\

% \>copyright owner\\

% \>time stamp\\

% \>groups of users, for each group: \\

% \>\>ID of the group \\

% \>\>schemas \\

% \>\>\>error \\

% \>\>\>fill-in \\

% \>\>\> \\

% \>\>dialog \\

% \>\>\>blackbox \\

% \>\>\>detail \\

% \>\>\>activity \\

% \>\>\>stepwidt \\

% \>\>\> \\

% \>\>invisible: list of intervals OR duration (? TODO !) \\

% \>\>locked: list of intervals OR duration (? TODO !)\\

% \>\>evaluation \\

% \>\>\>TODO: difficulty, length, \dots \\

% \>\>???done by userID ---$>$ usermodel??? 

% \end{tabbing}

% {\bf\SR Hitting the label of the example starts the calculation. \label{}}

% 

% \subparagraph{Visibility of the examples} is defined in two levels: (1) 'locked' displays the text of the example, but doesn't allow to calculate it; and (2) 'invisible' desn't display the example at all.

% {\bf\SR {\em Only} visible examples are checked for being locked.\label{}}

% %{\bf\SR Authoring-/learner-mode:} the formalization and other attributes are shown/not shown, depending on the group the user belongs to.

% 

% %\subparagraph{}

% %{\bf\SR \label{}}

%WN050519---AG------old version replaced by RK below

%WN050519---RK->isac-SRD-----------------BEGIN---please don't remove this line

% FIXXME RK, Oct. 2006 new version:

\chapter{Views on Examples and Knowledge Items}

\footnote{Begin of \cite{ba-RK06} p....-- p....}

This chapter describes the software requirements for the browsers and the

browserdialogs controlling these browsers. 

All browsers (Example-Browser and Knowledge-Browsers) present their

output in a similar way. Textual descriptions have to be combined with

images, formulas, formalisations, problems, \dots and links to further

informations. All items of

information might be interlinked with each other.%WN061009??,but not all parts

%of the information might be already present in the system when a new

%item is inserted.

\section{General Requirements}

%NOTE: completely new:

{\bf\SR Unique identification by a GUH.\label{SR.RK-id-by-guh}}

Each item of the examples collection or the knowledge base is uniquely identified 

by a GUH (Global Unique Identifier).

The GUH is a String starting with \verb,'thy_', for theory elements, \verb,'pbl_', for problem elements,

\verb,'met_', for method elements and \verb,'exp_', for examples.

%NOTE: completely new:

{\bf\SR Presentation in a standard browser and in the \isac-browsers.\label{SR.RK-stand-and-isac-browser}} The knowledge elements and examples can be viewed in a standard browser as well

as in the \isac-browsers. Thus, knowledge elements have to be available in HTML

form in some way.

%NOTE: completely new:

{\bf\SR GUHs as links.\label{SR.RK-link-by-guh}}

Links between elements of the knowledge base are defined by the GUH of the link target.

To make the links work in a standard browser, some path information has to be added to the URL in the

HMTL representation of the knowledge elements.

%NOTE: something similar already existed: RIGHT: this is a USER-requirement

%{\bf\SR Additional information can be given to any element of the knowledge base or the

%examples collection.\label{SR.RK-add-info}}

%This information is not extracted from the SML structures, it is added by the course designer. 

%The additional information can contain links to

%examples or elements of the knowledge base. External links and images are possible as well.

%NOTE: completely new:

%WN061009 isn't that an (ugly!) _consequence_ of the present (ugly!) handling of the browsers contents ?!?

%{\bf\SR The \isac-browsers can display the content of HTML files on the local file system as

%well as files available over the World Wide Web.\label{SR.RK-html-local-web}} 

%NOTE: completely new:

{\bf\SR Asynchronous load of content.\label{SR.RK-browser-load-asynch}}  The \isac-browsers load the content to be displayed asynchronously. That means, that the

user interface does not block until the page is loaded. The page is loaded in an extra thread instead.

%NOTE: copied:

{\bf\SR The hierarchy is displayed in a frame \label{SR.RK-hier-in-frame}} in order to have it visible all the time.

%NOTE: copied:

{\bf\SR The hierarchy has arbitrary levels. \label{SR.RK-hier-arb-levels}}

%NOTE: copied:

{\bf\SR The hierarchy shows the position \label{SR.RK-hier-arb-levels}} of the related element displayed in the browser-window.

\section{The Knowledge Browsers}

The following enumerations do {\em not} show all items contained in the respective sml datastructure; rather it shows the 'most important' ones --- a preliminary decision, which will be overlayed by filtering due to the dialog-guide.

%NOTE: modified:

{\bf\SR A problem page consists of:\label{SR.RK-pbl-consists}}

%WN061009 problem content-page ? problem content ?

\begin{enumerate}

\item name of the problem or the 'CAS-command' (a short command similar to an algebra system; e.g. {\em solve})

\item a model consisting of the fields 'given', 'where', 'find' and 'relate'

\item explanations %WN see 'list of terms...' additional data

\item the authors

\item the position within the problem-hierarchy displayed in the hierarchy-frame)

\end{enumerate} 

%NOTE: modified:

{\bf\SR A method page consists of:\label{SR.RK-met-consists}}

\begin{enumerate}

\item the script

\item a name (only displayed in the hierarchy-frame)

\item a guard consisting of the fields 'given', 'where', 'find' and 'relate'

\item explanations %WN see 'list of terms...' additional data

\item the authors

\item the position within the method-hierarchy displayed in the hierarchy-frame\end{enumerate} 

%NOTE: completely new:

{\bf\SR A theorem page (within theories) consists of:\label{SR.RK-thm-thy-consists}}

\begin{enumerate}

\item the name of the theorem

\item the formula of the theorem

\item a link to the proof of the theorem within Isabelle %WN061009 TODO

\item explanations %WN see 'list of terms...' additional data

\item the authors (math authors and course designers)

\end{enumerate} 

%NOTE: completely new:

{\bf\SR A ruleset page (within theories) consists of:\label{SR.RK-rls-thy-consists}}

\begin{enumerate}

\item the identifier of the ruleset

\item the type of the ruleset ({\tt Rls, Seq, Rrls}) %WN061009 TODO: use tag <TYPE>

\item a list of rules and links to the rules. Rules can be theorems other rulesets or operations.

\item a rewrite order

\item explanations %WN see 'list of terms...' additional data

\item the authors (math authors and course designers)

\item the position within the theory-hierarchy displayed in the hierarchy-frame

\end{enumerate} 

%NOTE: completely new:

{\bf\SR A htmldata theory page consists of:\label{SR.RK-html-thy-consists}}

\begin{enumerate}

\item explanations %WN see 'list of terms...' additional data

\item the authors

\end{enumerate} 

%NOTE: completely new:

{\bf\SR Similar representation for static and dynamic content.\label{SR.RK-add-context-2-html}}

If elements of the knowledge base are shown in the \isac-browser, the

content can be enriched with dynamically generated context dependent information.

Any selected formula in the worksheet has a context to an element of the knowledge base.

This context information is inserted into the HTML content displayed in the browser if the

feature is activated.

%NOTE: completely new:

{\bf\SR Data and representation separated.\label{SR.RK-data-rep-sep}}

The knowledge data and its representation should be separated well.

%NOTE: completely new:

{\bf\SR Easy generation of different representations.\label{SR.RK-rep-to-data}} SR.\ref{SR.RK-data-rep-sep} 

The system must provide an easy way of generating different representations

of the same knowledge data. SR.\ref{SR.RK-data-rep-sep} is a precondition to

make this possible.

\section{The example browser} In contrary to the knowledge browsers,

the presentation of the contents of a browser-window is {\em not}

generated automatically. UR \ref{expl-layout} requests for a layout

'handmade' by the course designer; there are, however, a lot of

attributes invisible for the learner to be added by the course

designer, too.

{\bf\SR The headlines of the

example-hierarchy: \label{expl-headlines}} The hierarchy comprises the

labels of the chapters, sections, subsections etc. plus the respective

head line, and the blocks of examples with the respective labels --

all defined by the user (see UR \ref{UR161a}).

{\bf\SR Metadata for selecting examples: \label{SR.WN-exp-metadata}}

\subparagraph{Attributes of examples and collections} are numerous,

and thus defaults help to safe space.

{\bf\SR Visibility of examples: \label{SR.WN-exp-visible}} Visibility

of the examples is defined in two levels: (1) 'locked' displays the

text of the example, but doesn't allow to calculate it; and (2)

'invisible' doesn't display the example at all.

{\bf\SR {\em Only} visible examples are checked for being locked.\label{}}

\footnote{End of \cite{ba-RK06} p....-- p....}

%WN050519---RK->isac-SRD-----------------END---please don't remove this line

\chapter{The dialog guide}

%{\bf\SR A learner has a dialog state within the current session. \label{}}

%{\bf\SR Each learner has a history of all sessions. \label{}}

%{\bf\SR The history holds the condensed performance in calculations. \label{}}

%{\bf\SR The history holds requests into the knowledge. \label{}\\}

%\subparagraph{}

%{\bf\SR \\}

As of 2012, the dialog is still a stub which just passes input from

the learner on to the math engine, and results of calculation from the

math engine back to the learner. Presently, replacement of Java code

by a rule-based system in the dialog is under construction. A

UserLogger is being re-engineered in order to serve dialog guidance

planned for the future.

\section{Components of the dialog guide}

{\bf\SR A dialog consists of }\label{DG:components}

\begin{enumerate}

\item a {\em dialog profile} which initializes the dialog

\item a {\em dialog history} which records each step in problem solving

\item {\em dialog rules} which which determine the flow of interaction

\item a {\em dialog guide} which selects the {\em dialog rules};\\

  these rules determine what is called a 'dialog mode'

\item a {\em dialog state} which comprises the data from the current session

\item a {\em learner model} which abstracts from the {\em dialog state}s 

during a course.

\end{enumerate}

The above notions will be used without the initial 'dialog' in a respective 

context.

{\bf\SR A dialog profile determines initialisation}\label{xxx} of the

dialog guide at the first registration and also in case of an

'exclusive' profile (in exams etc). A dialog profile can be

'exclusive' in order to feature assessments: within explicit time

limits an exclusive profile inhibits all other sessions of this

student.

{\bf\SR The dialog history records {\em dialog atoms}}\label{xxx} ,

i.e. steps of problem solving (an input by the learner together with

the reaction of the math engine) or look-ups in the knowledge base.

{\bf\SR A set of dialog rules comprises {\em dialog

patterns}}\label{xxx} which in turn are composed from {\em dialog

atoms}.

{\bf\SR The dialog guide selects {\em dialog patterns}}\label{xxx}

according to the {\em user model} from previous sessions, from the

{\em dialog profile} at start of the current session and from the

dialog state modified during the current session.

{\bf\SR The dialog state comprises current data}\label{xxx}, i.e. the

{\em dialog history} of the current session and the sets of {\em

dialog rules} employed in the current session.

{\bf\SR The learner model abstracts over all sessions}\label{xxx} in a

course such that the next session can be started adapting to the

personal needs of the learner.

\\

%{\bf\SR xxx }\label{xxx}

$/------$ not revised since $1^{st}$ design phase in 2001 $------\backslash$

\section{The dialogstate} is read and updated during {\em one}

session. A dialog resumes the dialogstate from the previous session

done as a member of the same student-group.

{\bf\SR The last dialogstate is stored \label{}} at the end of a

student's session for each group the student is a member of. When

storing and replacing the previous dialogstate, this dialogstate is

transferred to the history of the usermodel (eventually after

compression).

{\bf\SR The dialogstate has the attributes \label{}}

{\small

\begin{tabbing}

12345\=123\=123\=123\=123\=123\=123\=123\=12345123\=123\=\kill

\>begin       \>\>\>\>\>\>\>\>\>timestamp of begin of session\\

\>provided-end\>\>\>\>\>\>\>\>\>e.g. for examinations\\

\>actual-end  \>\>\>\>\>\>\>\>\>empty, or timestamp of end of session\\

\>group       \>\>\>\>\>\>\>\>\>the user has started the session with\\

\>interactions, for each: \\

\>\>timestamp\\

\>\>label of example\>\>\>\>\>\>\>\>empty if \sisac{} entered via KB\\

\>\>input\>\>\>\>\>\>\>\>tactic, formula, command or label in KB\\

\>\>response\>\>\>\>\>\>\>\>??? of which part of system ???\\

\>\>pattern\>\>\>\>\>\>\>\>of dialog\\

\>\>\>activity\\

\>\>\>stepwidt\\

\>\>\>\dots TODO \dots\\

\end{tabbing}}

The use of these fields is shown by use-case UC TODO.

\section{The usermodel} consists of two parts: the settings of the

personal preferences and the history of (condensed) dialogstates. The

history is constructed from the dialogstates: before a dialogstate is

being replaced at the start of a new session, its data are

restructured and appended to the history.

{\bf\SR The usermodel has the attributes\label{}}

{\small

\begin{tabbing}

12345\=123\=123\=123\=123\=123\=123\=123\=12345123\=123\=\kill

\>settings\\  

\>\>patterns, for each:\>\>\>\>\>\>\>\>of dialog\\  

\>\>\>activity\\

\>\>\>stepwidt\\

\>\>\>\dots TODO \dots\\

\>history, for each session:\>\>\>\>\>\>\>\>\>\\  

\>\>begin\_end\>\>\>\>\>\>\>\>2 timestamps\\  

\>\>group\>\>\>\>\>\>\>\> the user has started the session with\\  

\>\>kb\_touchs, for each:\>\>\>\>\>\>\>\>\\  

\>\>\>label of KB item\\  

\>\>\>timestamps\\

\>\>examples, for each:\\  

\>\>\>label of example\\  

\>\>\>begin\_end\>\>\>\>\>\>\>2 timestamps\\  

\>\>\>finished\>\>\>\>\>\>\>yes/no\\

\>\>\>performance\>\>\>\>\>\>\>from example.evaluation.TODO and\\  

\>\>\>\>\>\>\>\>\>\>from dialog.interactions\\  

\end{tabbing}}

The use of these fields is shown by use-case UC TODO.

\\

$\backslash------$ not revised since $1^{st}$ design phase in 2001 $------/$