File r37/packages/mathml/mathml.tex artifact ce0bbea45f part of check-in 3af273af29


\documentclass{article}
\title{REDUCE-MathML Interface}
\author{Luis Alvarez-Sobreviela \\ alvarez@zib.de \\ \\
	Konrad--Zuse--Zentrum f\"ur Informationstechnik Berlin \\
        Takustra\ss e 7 \\ D-14195 Berlin-Dahlem} 
\date{November 10, 1998}

\begin{document}

\maketitle

\section{Introduction}

MathML is intended to facilitate the use and re-use of mathematical and
scientific content on the Web, and for other applications such as computer
algebra systems. For this reason we believe MathML is an important step
for the scientific community considering the widespread use of the
Internet. We found necessary to include REDUCE in this trend, and
developed the MathML-REDUCE interface.

The MathML interface for REDUCE provides an easy to use series of
commands, allowing it to evaluate and output MathML. This manual is
therefore intended to give the user a good guideline on how to make of it a
proper use. 
\\

The principal features of this package can be resumed as:  
\begin{itemize}
\item Evaluation of MathML code. Allows REDUCE to parse MathML expressions
and evaluate them. 
\item Generation of MathML compliant code. Provides the printing of REDUCE
expressions in MathML source code, to be used directly in web page
production. 

\end{itemize}

We assume that the reader is familiar with MathML. If not, the
specification\footnote{This specification is subject to change, since it is
not yet a final draft. During the two month period in which this package was
developed, the specification changed, forcing a review of the code. This
package is therefore based on the Nov 98 version.} 
is available at:
\\

{\tt http://www.w3.org/TR/WD-math/ }

\section{Getting Started}

\subsection{Loading}

The MathML-REDUCE interface package is under the name {\tt mathml}, and so is
loaded by supplying {\tt load mathml;}.

\subsection{Switches}

There are two switches which can be used alternatively and incrementally.
These are {\bf mathml} and {\bf both}. There use can be described as
follows:

\begin{description}
\item[{\tt mathml}:] All output will be printed in MathML.
\item[{\tt both}:] All output will be printed in both MathML and normal
REDUCE.
\item[{\tt web}:] All output will be printed within an HTML <embed> tag. This is
for direct use in an HTML web page. Only works when {\tt mathml} is on.
\end{description}

MathML has often been said to be too verbose. If {\bf both} is on, an easy
interpretation of the results is possible, improving MathML readability.

\subsection{Entering MathML}

The MathML-REDUCE interface gives the user various ways of providing input.
This can be done via a file containing MathML, by writing MathML directly
in the prompt, or by simply writing as usual in the prompt. \\

\subsubsection{Reading MathML from a File: {\tt MML}}

When reading from a file the command {\bf mml} is used. {\bf mml} takes as
argument the name of the file containing the MathML. \\

{\tt mml}(FILE:{\it string}):{\it expression} 

\paragraph{Example:} As long as the file given contains valid MathML, no
errors should be produced.  

{\tt 1:  mml "ex.mml";}


\subsubsection{Reading MathML from Prompt: {\tt PARSEML}}

By using the function {\bf parseml} it is possible to introduce a series of
valid mathml tokens to the prompt. {\bf parseml} takes no arguments,
although once it is called it will prompt you to enter mathml tags starting
with {\tt $<$mathml$>$} and ending with {\tt $<$/mathml$>$}. It then returns
an
expression resulting from evaluating the input. \\

\paragraph{Example:} Here is an extract of a REDUCE session where {\tt
parseml()} is used:

{\tt 2: parseml(); 

2: <math> 

2: <apply><plus/> 

2: <cn>3</cn> 

2: <cn>5</cn> 

2: </apply> 

2: </math> 
\\

\hspace*{1cm}  8 \\

3: } \\

If for some reason you do not want to continue typing in at the prompt, and
cancel what has already been typed, it is possible to exit by calling 
control {\tt C} or control {\tt D}.

Although it is simpler to edit a file and then use {\tt mml}, we still
added {\bf parseml} for completeness.     

\subsubsection{Reading Normal Input from the Prompt}

If you wish to simply type in expressions in the normal fashion, without
using MathML, then it is possible. Just use REDUCE as you normally would. If
you wish to see the resulting expressions in MathML, then use the switches as
described earlier in this text. In this way, you will be allowed to evaluate
expressions and to generate MathML code, without needing to worry about how
familiar you are with MathML. You can always switch {\bf both} on to check if
the MathML output corresponds to what you expect. 


\section{The Evaluation of MathML}


MathML is evaluated by the interface always before outputting any results.
Just in the same way as REDUCE normally does. The program works in the same
way as the {\tt algebraic} mode. Undefined variables remain undefined,
and it is possible to use all normal REDUCE switches and packages.

\paragraph{Example:}

\noindent The following MathML:\\
\\
{\tt 
\hspace*{0mm}<math>

\hspace*{1mm}<relation><gt/>

\hspace*{6mm}<ci>x</ci>

\hspace*{6mm}<ci>y</ci>

\hspace*{1mm}</relation>
\\
\hspace*{0mm}</math>}
\\
\\
will evaluate to {\tt (gt x y)}. This only states that x is greater than y.
\\
The interesting characteristic, is that we can set the values of x and y.
\\
Suppose we enter the following:
\\

{\tt 5: x:=3; y:=2;
\\

x := 3
\\

y := 2}
\\
\\
If we once again enter and evaluate the above piece of MathML we will have as
result:
\\

{\tt t}
\\
\\
because it is true that 3 is greater than 2. It is important to note that
it is also possible to set only one of the two variables x or y above, say
{\tt y:=4}. The expression will then not evaluate completely, and we will
have:  \\

{\tt (gt x 4)}
\\
\\
When one of the switches is on, the MathML output will be:
\\
\\
{\tt 
\hspace*{1mm}<math>\\
\hspace*{5mm}   <relation><gt/>\\
\hspace*{9mm}      <ci>x</ci>\\
\hspace*{9mm}      <cn type="integer">4</cn>\\
\hspace*{5mm}   </relation>\\
\hspace*{1mm}</math>\\}

Hence, it is possible when dealing with a MathML formula representation in
which there are a set of undefined variables to set each variable to the
desired value and evaluate it. Let us consider a second example to make sure
everything is clear.

\paragraph{Example:}

Let the file {\tt ex.mml} contain the following mathml:
\\
\\
{\tt               <math>\\
\hspace*{2mm}       <apply><int/>\\
\hspace*{5mm}        <apply><fn><ci>F</ci><fn>\\
\hspace*{9mm}         <ci>x</ci>\\
\hspace*{5mm}        </apply>\\
\hspace*{5mm}        <bvar>\\
\hspace*{9mm}         <ci>x</ci>\\
\hspace*{5mm}        </bvar>\\
\hspace*{2mm}       </apply>\\
                  </math>}  \\
\\
If we do the following:\\

{\tt 1: mml "ex.mml";}\\
\\
This is what we get:
\\
\\
{\tt int(f(x),x);}\\
\\
It is clear that this has remained unevaluated. We can now set the function
{\tt f(x)} as follows:\\

{\tt for all x let f(x)=2*x**2;}\\
\\
If we then enter '{\tt mml "ex.mml"}' once again, we will have the
following result:\\

{\Large \( \frac {2*x^{3}}{3}\)}
\\
\\
Hence the MathML-REDUCE interface allows the user to set a value to a
variable in order to manipulate the evaluation of the MathML, without needing
to edit the MathML itself.

\subsection{Using Boolean Values}

Boolean values are not defined in MathML, despite their importance in REDUCE.
To get around this problem, we can set a variable's value to a boolean value,
and when evaluating, the MathML-REDUCE interface will use the boolean value
of the variable.
\\
Suppose we want to evaluate the following expression:
\\
\\
{\tt and(t,nil);}
\\
\\
Then all we do, is we create a file with the following MathML:
\\
\\
{\tt          $<$mathml$>$\\
\hspace*{2mm} $<$apply$>$$<$and/$>$\\
\hspace*{5mm}         $<$ci$>$ a $<$/ci$>$\\
\hspace*{5mm}         $<$ci$>$ b $<$/ci$>$\\
\hspace*{2mm}      $<$/apply$>$\\
        $<$/mathml$>$\\}
\\
And before evaluating it we set {\tt a} to {\tt true} and {\tt b} to {\tt
nil}. When evaluating the MathML, it will produce the same result as the
equivalent REDUCE expression.

\section{Interpretation of Error Messages}

The MathML-REDUCE interface has a set of error messages which aim to help the
user understand and correct any invalid MathML. Because there can exist many
different causes of errors, such error messages should be considered merely
as advice. Here we shall consider the most important error messages.

\paragraph{Missing tag:}

Many MathML tags go by pairs, such as {\tt $<$apply$>$$<$/apply$>$,
$<$relation$>$$<$/relation$>$}, {\tt $<$ci$>$$<$/ci$>$}, etc\ldots. In the
case
where the ending tag is missed out, or misspelled, it is very probable that an
error of this type will be thrown. 

\paragraph{Ambiguous or Erroneous Use of {\tt $<$apply$>$}}

This error message defines an undefined error. When this error message
appears, it is not very clear to the interface where exactly lies the error. 
Probable causes are a misuse of the {\tt $<$apply$>$$<$/apply$>$} tags, or a
mispelling of the tag preceding the {\tt $<$apply$>$}. However, other types
of errors may cause this error message to appear. 

Tags following an {\tt $<$apply$>$} tag may be misspelled without causing an
error message, but they will be considered as operators by REDUCE and
therefore evaluate to some unexpected expression.

\paragraph{Syntax Errors}

It is possible that the input MathML is not syntactically correct. In such
a situation, the error will be spotted, and in some cases a solution might be
presented. There are a variety of syntax errors messages, but relying on
their advice might not always be helpful. 
\\

Despite the verbose nature of the error messages and their recommended
solutions, we do recommend that in most situations reference to the MathML
specification is made. 

\section{Limitations of the Interface}

Not all aspects of MathML have been perfectly fitted into the interface.
There are still some problems unsolved in the present version of the
interface:

\begin{itemize} 
\item MathML Presentation Markup is not supported. The
interface will treat every presentation tag as an unknown tag, or a REDUCE
operator. We found presentation markup not prioritary when dealing with
computer algebra systems, although in the future, parsing of presentation
markup within content markup shall be supported.  
\item Certain MathML tags
do not play an important role in the REDUCE environment. Such tags will not
evaluate or affect in anyway the interface's behaviour. They will be parsed
correctly, although their action will be ignored. These tags are: 
\begin{enumerate} 
{\tt 
\item $<$interval$><$/interval$>$ 
\item $<$inverse$><$/inverse$>$ 
\item $<$condition$><$/condition$>$ 
\item $<$compose$><$/compose$>$ 
\item $<$ident$><$/ident$>$ 
\item $<$forall/$>$
\item $<$exists/$>$} 
\end{enumerate} 

Although {\tt $<$condition$><$/condition$>$} and {\tt
$<$interval$><$/interval$>$} tags are supported when used within the
following tags:  
\begin{enumerate} 
{\tt 
\item $<$int/$>$ 
\item $<$limit/$>$
\item $<$sum/$>$ 
\item $<$product/$>$} 
\end{enumerate} 
\item The {\tt $<$declare$>$} construct takes one or two arguments. It sets
the first argument to the value of the second. In the case where the second
argument is a vector or a matrix, an obscure error message is produced. It is
clearly something which must be fixed in the future.\\ \item The program
throws an error when it encounters {\tt nil} between {\tt $<$ci$><$/ci$>$}
tags. It is not possible to use boolean values directly.  Please refer to the
above subsection treating this matter.  
\end{itemize}

\section{Examples}

We would like to present a series of examples which will illustrate the
possibilities of the interface.

\paragraph{Example 1} Type in the following and observe the resulting
expression:

\begin{verbatim}
23: on mathml;

24: solve({z=x*a+1},{z,x});
\end{verbatim}
\paragraph{Example 2}Have a file {\tt ex2.mml} containing the following
MathML source code:\\
\\
{\tt                 $<$mathml$>$\\
\hspace*{1mm}      $<$apply$>$$<$sum/$>$\\
\hspace*{5mm}       $<$apply$>$$<$fn$>$$<$ci$>$F$<$/ci$>$$<$fn$>$\\
\hspace*{9mm}         $<$ci$>$x$<$/ci$>$\\
\hspace*{5mm}       $<$/apply$>$\\
\hspace*{5mm}       $<$bvar$>$\\
\hspace*{9mm}         $<$ci$>$x$<$/ci$>$\\
\hspace*{5mm}       $<$/bvar$>$\\
\hspace*{1mm}      $<$/apply$>$\\
                  $<$/mathml$>$\\}
\\
and type:\\
\\
{\tt mml "ex2.mml"}

\paragraph{Example 3} This example illustrates how practical the switch
{\bf both} can be for interpreting verbose MathML.
Introduce the following MathML source into a file, say {\tt ex3.mml}\\
\\
{\tt $<$mathml$>$\\
\hspace*{1mm}  $<$apply$>$$<$int/$>$\\
\hspace*{5mm}    $<$apply$>$$<$sin/$>$\\
\hspace*{9mm}      $<$apply$>$$<$log/$>$\\
\hspace*{13mm}       $<$ci$>$x$<$/ci$>$\\
\hspace*{9mm}      $<$/apply$>$\\
\hspace*{5mm}    $<$/apply$>$\\
\hspace*{5mm}    $<$bvar$>$\\
\hspace*{9mm}      $<$ci$>$x$<$/ci$>$\\
\hspace*{5mm}    $<$/bvar$>$\\
\hspace*{1mm}  $<$/apply$>$\\
$<$/mathml$>$ \\}
\\
then do the following:

\begin{verbatim}

2: on both;

3: mml "ml";

\end{verbatim}

\section{An overview of how the Interface Works}

The interface is primarily built in two parts. A first one which parses
and evaluates MathML, and a second one which parses REDUCE's algebraic
expressions and prints them out in MathML format. Both parts work by
recursive parsing, using Top-Down Recursive Descent parsing with one token
look ahead.

The BNF description of the MathML grammar is to be defined informally in
APPENDIX E of the current MathML specification. It is with this document that
we have developed the MathML parser. The MathML parser evaluates all
that is possible and returns a valid REDUCE algebraic expression. When {\bf
mathml} or {\bf both} are on, this algebraic expression is fed into the
second part of the program which parses these expressions and transforms them
back into MathML. 

The MathML generator parses through the algebraic expression produced by
either REDUCE itself or the MathML parser. It works in a very
similar way as the MathML parser. It is simpler, since no evaluation is
involved. All the generated code is MathML compliant. It is important to note
that the MathML code generator sometimes introduces Presentation Markup tags,
and other tags which are not understood by the MathML parser of the
interface\footnote{The set of tags not understood by the MathML parser are
detailed in section {\bf Limitation}.}.

\end{document}



REDUCE Historical
REDUCE Sourceforge Project | Historical SVN Repository | GitHub Mirror | SourceHut Mirror | NotABug Mirror | Chisel Mirror | Chisel RSS ]