\documentclass{article}
\usepackage{graphicx}
\usepackage{hyperref, url, moreverb}
\begin{document}
\title{The AcroWeb script collection}
\author{Robert Ma\v r\'\i k}
\date{\today}
\maketitle

\section{Introduction}

\subsection{What is AcroWeb}
The teacher of mathematics can use pdf\LaTeX{} and Acro\TeX{}
eDucation bundle\footnote{\LaTeX{} package written by D. P. Story} to
prepare interactive tests for students. Tests produced in this way
are unique in several points.
\begin{itemize}
\item Each test is a PDF file. Only free Adobe Reader and no extra
  software and no Internet access is required when working out the
  test.
\item The author of the test has a possibility to ask not only
  multichoice questios, but also fill-in questions, where the answer
  is a mathematical formula (function, equation, vector).
\item The author of the test can change the function which is used to
  compare the correct and user's answers. Thus you can ask questions
  where the answer is not unique, but unique up to an aditive constant
  factor (useful in integral calculus, for example).
\end{itemize}
For more details about Acro\TeX{} see \url{http://www.acrotex.net}. 
The AcroWeb bundle is a collection of PHP and perl scripts and
\LaTeX{} templates which
\begin{itemize}
\item read a plain text database of mahematical problems with
  multichoice questions or fill-in questions (the answer is not
  a string, but mathematical formula!)
\item select randomly given number of problems from this database
  (databases)
\item build \LaTeX{} file which is compiled by pdf\LaTeX{} and sent to the
  user's www browser.
\end{itemize}

Roughly speaking, AcroWeb is an interface to build Acro\TeX{} tests on
web from a database of problems.

The templates of PHP and Perls scripts are included in the AcroWeb
collection and the maintainer of the database need not to know these
languages. The structure of Acro\TeX{} commands is hidden to the
author of the database, but the author of the test has to put some
commands relating these tests into preamble of the \TeX{} file and
he should be familiar with Acro\TeX. However, he/she can start with
customizingthe templates distributed with AcroWeb.

\subsection{How AcroWeb looks like}
\begin{figure}
  \centering
  \includegraphics[width=8cm]{test1.jpg}
  \caption{Multichoice test}
  \label{fig:1}
\end{figure}
\begin{figure}
  \centering
  \includegraphics[width=8cm]{test2.jpg}
  \caption{Fill-in test}
  \label{fig:2}
\end{figure}
The demo tests distributed with AcroWeb bundle are shown on Figures
\ref{fig:1} and \ref{fig:2}.  The user clicks the Begin Quizz
button, answers the questions and clicks End quizz button. The user's
score (the number of correct answers) appears in the field Score. If
the user clicks Corect button, he can see correct answers to all
questions.

\subsection{How AcroWeb works}
We assume that the author of educational tests runs http server with
PHP, \LaTeX{} and Perl.  The user clicks a link on author's web page
which points to the corresponding php script and this php script
starts the job:
\begin{itemize}\item 
  A temporary directory in \verb+/tmp+ is created. The name of this
  directory is unique for each process and starts with word
  \verb+acrotex+, e.g. \verb+/tmp/acrotex6892/+.
\item \TeX{} file \verb+test.tex+ is created in temporary
  directory. This file is produced by perl script which reads the
  database of problems, translates the problems into notation suitable
  for Acro\TeX and selects randomly given number of problems and (for
  multichoice questions) a given number of incorrect answers which
  accompany a correct answer. 
\item The file \verb+test.tex+ is compiled by pdf\LaTeX{} and the
  resulting PDF file is opend in the user's browser.
\item Finally we clean the temporary directory and write simple log
  information. These two steps are performed by the function
  \verb+compile_acroweb+ defined in the file \verb+acroweb.php+. 
\end{itemize}
The demo page \verb+demo.html+ contains links to php scripts which
build the PDF file and to several examples how the database and \TeX{}
files look like.

\subsection{How to try AcroWeb} The demo site is
\url{http://www.mendelu.cz/user/marik/acroweb}. This site is in Czech,
but it contains link to demo file in English. This demo file is
included also in the AcroWeb distribution.

\subsection{How to install AcroWeb} 
Installation of Acroweb is pretty simple. The administrator has to put
the \verb+acroweb+ directory (contains \verb+*.html+, \verb+*.pl+,
\verb+*.pm+, \verb+*.head+, \verb+*.tail+, \verb+*.txt+ and
\verb+*.tex+ files) into directory visible from http server, unzip the
\verb+phpfiles.zip+ also into this directory (this extracts
\texttt{acroweb.php}, \texttt{demo1.php}, \texttt{demo2.php},
\texttt{template2.php} and \texttt{template.php} files) and open the
\verb+demo.html+ file in browser. For example, if you put the
\verb+acroweb+ directory to \verb+/var/www/+, open the page
\url{http://your.server.domain/acroweb/demo.html} in your browser. If
you put the directory to local computer (running apache server and
php), open the page
\url{http://localhost/acroweb/demo.html}\footnote{If the page is not
  displayed in your browser, check that you have the files in correct
  path and that your apache server is running.} A table with several
demo tests appears. If you click links pointing to php file (the
second column), a PDF file \verb+test.pdf+ should compile and appear
in your browser or in Adobe Reader (depending on the configuration of
your computer).\footnote{Do \textit{not} open the PDF file in
  \textit{another PDF viewer} than Adobe Reader, since Adobe Reader is
  these days the only PDF browser capable to handle java scripts in
  the tests.} If the PDF file is not compiled, check that PHP and
\LaTeX{} with all necessary packages are installed. If this does not
help, read the section Troublesooting which describes how to catch the
resulting \TeX{} file and the output of pdf\LaTeX{} compiler. Finally,
check that users from the Internet have write access to the \verb+log+
directory and file \verb+acroweb.log+ in this directory. This file is
used to store simple information with time, date, IP address and the
descripton of the test.

\begin{center}
  \fbox{\textbf{Works? You can create your own database of problems now}.}
\end{center}
\section{Writing database and customizing scripts for compilation}

\subsection{Multichoice question}


\subsubsection{Database of problems}

The format of the database is inspired by the format which is used in
eLearning section of University information system at Mendel
University in Brno\footnote{And also at Technical University in Bratislava and
other universities with the same information system.}:

\begin{boxedverbatim}
The first problem - on one line (which can be very very long)
+correct answer
-incorrect answer number 1
-another incorrect answer
-yet another incorrect answer
-the fourth incorrect answer
-the last incorrect answer
<one blank line>
The second problem - no more than one line again
-incorrect answer number 1
-another incorrect answer
-yet another incorrect answer
+correct answer
-the fourth incorrect answer
-the last incorrect answer
<one blank line>
\end{boxedverbatim}

Here \verb+<one blank line>+ means \textit{blank line, no spaces and
  no tabs}. The order of answers is arbitrary, the number of answers
can be bigger or equal to the number of answers used in the test. The
file should end with one blank line again. You can use \LaTeX{}
commands including mathematics, text faces and also commands defined in the
head of the \TeX{} file which produced (see below and files
\verb;*.head; in the distribution) during he compilation.

\subsubsection{PHP script}

The philosophy is the following
\begin{itemize}
\item We have a Perl script which reads the database, selects randomly
  given numer of problems with given number of answers and sends the
  \TeX{} file to the standard output.
\item We have a PHP script which calls the Perl script from the
  preceeding item and redirects output to a \TeX{} file in temporary
  directory. This script runs pdf\LaTeX{} compiler and sends the PDF
  file to the browser using \verb+header+ and \verb+readfile+
  directives.
\end{itemize}
The PHP script \verb+template2.php+ looks as follows:

\begin{boxedverbatim}
<?php
require ("./acroweb.php");
$directory="/tmp/acrotex".getmypid();
system("mkdir $directory");
system("perl template2.pl > $directory/test.tex");
compile_acroweb("some name",$adresar); 
?>
\end{boxedverbatim}

On the first line we read the file \verb+acroweb.php+ which defines
\verb+compile_acroweb+ function. On the second line we derive the name
of the working directory from the number of the process running and on
the third line we create this directory. The next line calls perl
script which outputs the \TeX{} file -- the output is redirected to the
file \verb+test.tex+ in the working directory. On the last line we
call the function \verb+compile_acroweb+ which runs pdf\LaTeX, sends
the PDF file to browser and writes simple log information containing
date, time, IP address and the name of the test in the form

\begin{boxedverbatim}
08.Oct.2007, 22:12:17, IP: 127.0.0.1, test: some name
\end{boxedverbatim}

where "the name of the test" is the first parameter of the
\verb+compile_acroweb+ function. This function also removes the
working directory. However, if the script fails for some reason (due
to errors in compilatoin, for example), the temporary directory
remains on the server. It is suggested to clean \verb+/tmp+ directory
regularly in a cron script.

\subsubsection{Perl script -- multichoice tests}
The task for the perl script is to read the problems from database, to
select given number of problems from this database and send the \TeX{}
file to the standard output. (The output is redirected to a file in
the corresponding PHP script.) The perl script \verb+template2.pl+
looks as follows.

\begin{boxedverbatim}
use acroweb_eng;
system("cat template2.head");
@outA=genrandom("template.txt",4,4,0);
@outB=genrandom("template2.txt",4,4,0);
@out=(@outA, @outB);
print permutemyfield(@out);
system("cat template2.tail");
\end{boxedverbatim}

On the first line we read the library with macros.  We build the
\TeX{} file from three parts: the first part which precedes the
questions is stored in the file \verb+template2.head+. The
\verb+*.head+ file should end with \verb+\begin{questions}+ command
  and we send the contetns of this file to standard output using
  \verb+cat+ command. Then we write the second part of \TeX{} file,
  where we transform selected problems of the database into the form
  which may looks as follows.

\begin{boxedverbatim}
\problem{This is question number $6$}
\begin{answers}{1}
\Ans0 incorrect answer number 1\\[5pt]
\Ans0 incorrect answer number 2\\[5pt]
\Ans0 incorrect answer number 4\\[5pt]
\Ans1 this is correct answer\\[5pt]
\Ans0 incorrect answer number 5
\end{answers}

\problem{This is question number $3$, series $2$}
\begin{answers}{1}
\Ans0 incorrect answer number 3\\[5pt]
\Ans0 incorrect answer number 1\\[5pt]
\Ans0 incorrect answer number 4\\[5pt]
\Ans0 incorrect answer number 2\\[5pt]
\Ans1 this is correct answer
\end{answers}

\end{boxedverbatim}

  We finish the \TeX{} file by \verb+template2.tail+ (this file should
  start with \verb+\end{questions}+)

Now we describe in more details how the database transforms into
second part of the \TeX{} file.  The library \verb+acroweb_eng.pm+
defines three functions: \verb+genrandom+, \verb+filtruj+ and
\verb+permutemyfield+. The function
\verb+genrandom("template.txt",4,4,0);+ reads the file
\verb+template.txt+ and returns $4$ randomly selected problems (the
second parameter). Each parameter has one correct and $4$ incorrect
answers (the third parameter).

The last parameter is a flag which takes value $0$ or $1$ or $2$. The
value $0$ means: we select $4$ incorrect answers, one correct answer
and write them in random order. The value $1$ works in a similar way,
but the last answer is replaced by the phrase "another answer". The
value $2$ is used for fill-in questions (see below). 

The function \verb+genrandom+ calls the function \verb+filtruj+
first. This function reads the database and writes the problems with
solutions into the form suitable for Acro\TeX.  After this we randomly
select given number of problems and return these problems as strings
in a field. If we have one source of the problems (one file) we print
this field and finish the file with \verb+*.tail+ file. In
\verb+template2.pl+ we read problems from two files and mix them
up. From this reason we put these problems into one field named
\verb+@out+ and call

\begin{boxedverbatim}
print permutemyfield(@out);
\end{boxedverbatim}

function to print elements of this field in random order.

\subsection{Math fill-in test}

The format ot the database for fill-in questions is 

\begin{boxedverbatim}
Question on one line
+ correct solution (math formula for acrotex)
- interval where we check the solution
<blank line>
Question on one line
+ correct solution (math formula for acrotex)
- interval where we check the solution
<blank line>
\end{boxedverbatim}

(see also \verb+demo2.tex+).  We use flag $2$ in the \verb+genrandom+
function in the corresponding perl script and The other parts of the
compilatoin process are the same as for multichoice problems. For
example, the file \verb+demo2.pl+ has only four rows.

\begin{boxedverbatim}
use acroweb_eng;
system("cat demo2.head");
print genrandom("demo2.txt",8,0,2);
system("cat demo2.tail");
\end{boxedverbatim}

Using flag $2$, the database is compiled into the form which may look
as follows.

\begin{boxedverbatim}
\problem{${(x^2+1)^3} $}
\interval{[1,2]}\correctanswer{6*x*(x^2+1)^2}

\problem{${(x+1)\ln(x^2+1)}$}
\interval{[1,2]}\correctanswer{ln(x^2+1)+(x+1)*2*x/(x^2+1)}

\problem{$\cos \left( 2\,x-1 \right) $}
\interval{[0,1]}\correctanswer{-2*sin(2*x-1)}

\end{boxedverbatim}

It is supposed that user defines macros \verb+\problem+,
\verb+\interval+, \verb+\correctanser+ which build the question and
the field for student's answer --- see the file \verb+demo2.head+ or
invoke

\begin{boxedverbatim}
perl demo2.pl > /tmp/file.tex
\end{boxedverbatim}

and check the file \verb+/tmp/file.tex+.

\section{Questions and troubleshooting}

\subsection{How to check the \TeX{} file produced?}
The directory with \TeX{} file is removed when the script is
finished. Hence you cannot view this file. If you wish to see the tex
file, change the line which calls the perl script in the PHP file into
something like

\begin{boxedverbatim}
system("perl template2.pl > $directory/test.tex && cp $directory/test.tex /tmp");
\end{boxedverbatim}

and the file \verb;test.tex; will be copied into \verb+/tmp+ directory.

\subsection{I get no PDF file, how to find what gets wrong?}
\begin{enumerate}
\item You can use the preceding hint and check that the file
  \verb+test.tex+ appears in the \verb+/tmp+ directory and this file
  can be compiled with pdf\LaTeX.
\item You can change the line of the PHP script into

\begin{verbatim}
system("perl template2.pl");
\end{verbatim}

  and the \TeX{} file appears in your browser. But remember that the
  linebreaks in the \TeX{} file are destroyed.
\item You can call the perl script in command line, redirect the
  output into \verb;tex; file and compile by hand. For example, you
  can issue the following commands

\begin{verbatim}
 perl demo1.pl > myfile.tex && pdflatex myfile.tex
\end{verbatim}

\item The output of the pdf\LaTeX{} compiler is redirected into a file
  by default. You can send the output of this compilaion to the
  browser. To do this change the line in \verb+acroweb.php+ from 

\begin{verbatim}
  $command="cd $adresar && pdflatex test.tex>nothing && .......";
\end{verbatim}

  into 

\begin{verbatim}
  $command="cd $adresar && pdflatex test.tex && .......";
\end{verbatim}

  and the output of the compilation should appear in the browser. If
  not, you may need to call pdf\LaTeX{} with full path,
  e.g. \verb+/opt/texlive2007/bin/i386-linux/pdflatex+.
\item Check the log file of appache server, e.g. check the file
  \verb+/var/log/appache2/errors.log+ on Debian server.
\end{enumerate}  

\subsection{How to print the whole set of problems?}
To print the whole set of problems with all answers run the script
\verb+printacroweb.pl+ from the \verb+script+ subdirectory. You have
to redirect the standard input from the database and redirect the
standard output into a \TeX{} file and compile. You can run e.g.

\begin{boxedverbatim}
perl printacroweb.pl < ../demo1.txt > all.tex && pdflatex all.tex
\end{boxedverbatim}

from the \verb+script+ subdirectory. The script \verb;printacroweb.pl;
work for multichoice questions, a similar script
\verb;printacrowebmath.pl; works for file with math fill-in questions.

\subsection{What is the future of AcroWeb?}
\begin{enumerate}
\item The scripts which read the database of problems should be
  improved. We should allow to write the formulation of the problem on
  more than one line, we should treat more blank lines as single blank
  line and treat lines with blank spaces as blank lines. However,
  these restrictions are marginal for me. Thus if I get no feedback
  from users, I may keep the scripts in the current form.
\item The log file from compilation by pdf\LaTeX{} should be parsed
  automatically and if an error occurs, the log file should be sent to
  the maintainer of the database as e-mail.
\end{enumerate}

\section{Feedback from AcroWeb users}
Do you have any suggestions to AcroWeb? Do you use these scripts on
your site? Do you have some other comments, ideas or hints? Let me
know, please. My email address is \url{mailto:marik@mendelu.cz}.

\section{Changelog}
\begin{description}
\item[version 0.79] October 2007: the first public version. 
\end{description}
\end{document}

% LocalWords:  PDF PHP acroweb pdflatex perl tex pl adresar printacroweb
% LocalWords:  multichoice Acrotex