summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/eq2db/doc/eq2dbman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'texmf-dist/source/latex/eq2db/doc/eq2dbman.tex')
-rw-r--r--texmf-dist/source/latex/eq2db/doc/eq2dbman.tex1347
1 files changed, 1347 insertions, 0 deletions
diff --git a/texmf-dist/source/latex/eq2db/doc/eq2dbman.tex b/texmf-dist/source/latex/eq2db/doc/eq2dbman.tex
new file mode 100644
index 00000000..201474bc
--- /dev/null
+++ b/texmf-dist/source/latex/eq2db/doc/eq2dbman.tex
@@ -0,0 +1,1347 @@
+\RequirePackage[use=usebw]{spdef}
+\documentclass{article}
+\usepackage[fleqn]{amsmath}
+\usepackage{graphicx,longtable,array}
+%\usepackage[dvipsone,designvi,tight]{web} % dvipsone, dvips, pdftex, dvipdfm
+\usepackage[designv,latextoc,forcolorpaper,centertitlepage]{web}
+\usepackage[nodljs,execJS]{exerquiz} %,preview
+\usepackage[altbullet]{lucidbry}
+\usepackage{pifont}
+\usepackage{fancyvrb}
+%\usepackage{calc}
+
+\usepackage[active]{srcltx}
+
+%\setlongtables
+\def\AEBBook{\textsl{{Acro\!\TeX} eDucation System Tools: {\LaTeX} for interactive PDF documents}}
+
+\hyphenation{Java-Script}
+
+\def\AcroT{Acro\!\TeX}\def\cAcroT{{\textcolor{blue}{\AcroT}}}
+\def\AcroEB{\AcroT{} eDucation Bundle}\def\cAcroEB{\textcolor{blue}{\AcroEB}}
+\def\AcroB{\AcroT{} Bundle}\def\cAcroB{\textcolor{blue}{\AcroB}}
+\def\bUrl{http://www.math.uakron.edu/~dpstory}
+
+% Colors
+\ifusebw
+\universityColor{black}
+\sectionColor{black}
+\quesNumColor{black}
+\tocColor{black}
+\fi
+
+\makeatletter
+\ifusebw
+\def\@linkcolor{black}
+\def\@citecolor{black}
+\def\@filecolor{black}
+\def\@urlcolor{black}
+\fi
+\let\bslash=\@backslashchar
+%\renewcommand{\paragraph}{\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
+\renewcommand{\paragraph}
+ {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}
+ {\normalfont\normalsize\bfseries}}
+\renewcommand{\subparagraph}
+ {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}%
+ {\normalfont\normalsize\bfseries}}
+\def\FitItIn{\eq@fititin}
+\def\endredpoint{\FitItIn{{\large\ifusebw\color{black}\else\color{red}\fi$\blacktriangleleft$}}}
+\def\chgCurrLblName#1{\def\@currentlabelname{#1}}
+\makeatother
+
+\hypersetup{linktocpage}
+
+\def\cs#1{\texttt{\bslash#1}}
+\newcommand\redpoint{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi
+\vskip\medskipamount\noindent
+ \makebox[\parindent][l]{\large\ifusebw\color{black}\else\color{red}\fi$\blacktriangleright$}}
+\newcommand\handpoint{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi
+\vskip\medskipamount\noindent
+ \makebox[\parindent][l]{\large\ifusebw\color{black}\else\color{blue}\fi\ding{042}}}
+
+\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$}
+\def\meta#1{\textit{\texttt{#1}}}
+\let\pkg\textsf
+\let\env\texttt
+\let\opt\texttt
+\let\app\textsf
+\def\AEB{\textsf{AeB}}
+\def\AcroTeX{Acro\!\TeX}
+\def\HTML{HTML}\def\FDF{FDF}
+\def\PDF{PDF}\def\URL{URL}
+\let\amtIndent\leftmargini
+\def\bNH{\begin{NoHyper}}\def\eNH{\end{NoHyper}}
+\def\nhnameref#1{\bNH\nameref{#1}\eNH}
+\def\nhNameref#1{\bNH\Nameref{#1}\eNH}
+\def\nhurl#1{\bNH\url{#1}\eNH}
+\def\grayV#1{\textcolor{gray}{#1}}
+\def\darg#1{\{#1\}}
+\def\parboxValign{t}
+\renewcommand*{\backrefalt}[4]{%
+ See page\ifcase #1\or
+ ~#2.\else s~#2.\fi
+}
+\newenvironment{aebQuote}
+ {\list{}{\leftmargin\amtIndent}%
+ \item\relax}{\endlist}
+\newcommand{\FmtMP}[2][0pt]{\mbox{}\marginpar{%
+ \raisebox{.5\baselineskip+#1}{%
+ \expandafter\parbox\expandafter[\parboxValign]%
+ {\marginparwidth}{\aebbkFmtMp#2}}}}
+\def\aebbkFmtMp{\kern0pt\itshape\small
+ \ifusebw\color{gray}\else\color{blue}\fi
+ \raggedleft\hspace{0pt}}
+\def\dps{$\mbox{$\mathfrak D$\kern-.3em\mbox{$\mathfrak P$}%
+ \kern-.6em \hbox{$\mathcal S$}}$}
+
+\title{\texorpdfstring{Acro\!\TeX}{AcroTeX} eDucation Bundle\texorpdfstring{\\}{: }
+ The \texorpdfstring{\pkg{eq2db}}{eq2db} Package}
+\author{D. P. Story}
+\subject{Manual of Usage for eq2db Distribution}
+\keywords{AcroTeX, LaTeX, PDF, ASP, Database, Email, quizzes}
+
+\university{{\AcroT} Software Development Team}
+%\university{THE UNIVERSITY OF AKRON\\
+% Theoretical and Applied Mathematics}
+\email{dpstory@acrotex.net}
+\version{2.0}
+\copyrightyears{1999-\the\year}
+
+% \def\OpenToHere{\OpenAction{\JS{this.gotoNamedDest("Here")}}}
+% \def\OpenHere{\hypertarget{Here}{\strut}}\OpenToHere
+
+\reversemarginpar
+
+\makeatletter
+\let\web@copyright\@gobble
+\let\web@revision\@gobble
+\renewcommand\webdirectory
+{%
+ \par\ifeqforpaper\else\minimumskip\fi\vspace{\stretch{1}}%
+ \begin{flushleft}\textbf{\large\web@directory}%
+ \vspace{-3pt}
+ \begin{itemize}\setlength{\itemsep}{-3pt}%
+ \bfseries
+ \item \leavevmode\hyperlink{webtoc}{\web@toc}%
+ \item Begin \hyperlink{\web@Start.1}{Documentation}
+ \item \href{aeb_man.pdf}{\AcroEB}
+ \item \textsf{\href{eformman.pdf}{eForm}} Support
+ \end{itemize}
+ \end{flushleft}
+}
+\def\maketitle@trailer@ul{\web@copyright\ \copyright\ \webcopyrightyears\ \webversion}
+\def\maketitle@trailer@ll{\web@revision\ \@date}
+\def\maketitle@trailer@ur{\url{http://www.acrotex.net}}
+\def\maketitle@trailer@lr{\href{mailto:\webemail}{\webemail}}
+
+%\renewcommand\titlepageTrailer
+%{%
+% \web@copyright\ \copyright\ \webcopyrightyears\ \webversion
+% \hfill\url{http://www.acrotex.net}\\
+% \web@revision\ \@date \hfill\href{mailto:\webemail}{\webemail}
+%}
+\makeatother
+
+\newcounter{exampleno}
+\def\theexampleno{\arabic{exampleno}}
+\newcommand\Example{\refstepcounter{exampleno}%
+\paragraph*{Example.}}
+
+\begin{execJS}{execjs}
+aebTrustedFunctions(this, aebAddWatermarkFromFile, {
+ bOnTop: false,
+ cDIPath: "C:/Users/Public/Documents/ManualBGs/Manual_BG_Print_AeB.pdf"
+})
+aebTrustedFunctions(this, aebSaveAs, "Save")
+\end{execJS}
+
+
+\begin{document}
+
+\maketitle\tableofcontents
+
+\section{Introduction}
+
+\emph{Short Summary:} Converts a self-contained \pkg{exerquiz} \env{quiz} to one that is
+submitted to a server-side script.\endredpoint
+
+\medskip
+The \pkg{eq2eb} package is meant to be used with the \pkg{exerquiz} package,
+one of the components of the \textbf{{Acro\!\TeX} eDucation Bundle}
+(\texttt{ctan.org/pkg/acrotex}). The package redefines the `End Quiz' button
+(of the \env{quiz} environment) appropriately so that when the user clicks
+the `End Quiz' control, the results of the quiz are sent to a server-side
+script. The \pkg{eq2db} Package has six options:
+\begin{questions}
+\item \texttt{\hyperref[eqRecordOption]{eqRecord}}: Save quiz data
+ to a database, such as Microsoft Access. (Supported for FDF submission.)
+\item \texttt{\hyperref[eqEmailOption]{eqEmail}}: Email quiz data
+ to the instructor. (Supported for FDF and HTML submission.)
+\item \texttt{\hyperref[eqTextOption]{eqText}}: Save quiz data
+ to a tab-delimited text file. Can then be opened and analyzed
+ using Microsoft Excel. (Supported for FDF and HTML submission.)
+\item \texttt{\hyperref[customOption]{custom}}: A hook for developers
+ to use \texttt{eq2db} with their own script.
+\item \texttt{\hyperref[taggedOption]{tagged}}: Write quiz data in an XML-like
+ data stream.
+\item \texttt{submitAs=\meta{\upshape FDF|HTML|XML}}: (new in v2.0) The
+ \texttt{submitAs} option allows the document author to submit as FDF,
+ HTML, or XML. The scripts provided by this package are designed FDF
+ submittal and HTML submittal. Scripts for an XML submittal type are left
+ as an exercise.
+
+ With regard to HTML submission, read Section~\ref{s:IntroHTMLSub} below.
+\end{questions}
+
+For FDF submittal, accompanying each of the first three options listed above
+is a server-side script. These are ASP pages written with \app{VBScript}.
+A \app{Windows} server running Microsoft IIS is required; Adobe \textsl{FDF Toolkit}
+is also required to be installed on the server.
+
+\subsection{Introduction to HTML submission}\label{s:IntroHTMLSub}
+
+My upcoming book (if it ever comes), \AEBBook~\cite{book:AEBB}, has a rather extensive chapter
+titled ``Server-side Scripting and the \pkg{eq2db} Package.'' In the course
+of writing that chapter, I decided to throw in the towel on the \textsl{FDF
+Toolkit}, the mainstay for FDF submission, and to look at HTML submission.
+Yes, PDF form data can be submitted as HTML form data. As result, I wrote a
+number of scripts for general purpose PDF form documents and for quiz
+documents (see Tables~\ref{table:QuizScripts1} and~\ref{table:QuizScripts2});
+identical functioning scripts were written for the \app{Windows}
+server-platform using \app{ASP} and \app{VBScript} and for the \app{Linux}
+server-platform using \app{PHP}.
+
+\paragraph*{{\AEB} demonstration websites.}\label{para:SSDemoPages}\leavevmode
+These two websites were created to illustrate server-side concepts and examples brought up
+in the book. The links on these pages demonstrate the two sets of scripts
+listed in Tables~\ref{table:QuizScripts1} and~\ref{table:QuizScripts2}, and much more.
+\begin{quote}
+\nhurl{http://faculty.nwfsc.edu/web/math/storyd/dps/}
+\end{quote}
+The above Web page is on a \app{Windows} server hosted by Northwest Florida State
+College (NWFSC). The server-side
+script is written as ASP pages using VBScript.
+\begin{quote}
+\nhurl{http://www.acrotex.net/dps/}
+\end{quote}
+This Web page is on a \app{Linux} server hosted by {\AcroTeX.Net}. The
+server-side script is written with PHP.
+
+A parallel development of all scripts is maintained for these two server
+platforms. You are invited to navigate your Web browser to each of these
+{\URL}s and experience forms submission from a {\PDF} document.
+
+
+\section{The Distribution and Requirements}
+
+The \pkg{eq2db} Package is distributed with the following files:
+\begin{questions}
+ \item \texttt{eq2dbman.pdf}: This document, the documentation for
+ the {\LaTeX} package \pkg{eq2db} and its related files.
+ \item \texttt{eq2db.dtx} and \texttt{eq2db.ins}: The {\LaTeX} package
+ with its installation file.
+ \item \textsf{eqRecord.asp}: An \textsf{ASP} script for saving \pkg{exerquiz}
+ quizzes to a data\-base.
+ \item \textsf{eqEmail.asp}: An \textsf{ASP} script for forwarding \pkg{exerquiz}
+ quizzes via e-mail.
+ \item \textsf{eqText.asp}: An \textsf{ASP} script for saving \pkg{exerquiz}
+ quizzes to a tab-delimited file.
+ \item \texttt{quiz1.tex}, \texttt{quiz2.tex}, \texttt{quiz3.tex},
+ \texttt{quiz4.tex} (quizzes~1 and~2 demo use the \texttt{eqRecord}
+ option; \texttt{quiz3} demos \texttt{eqEmail}, and \texttt{quiz4}
+ demos \texttt{eqText}.)
+ \item \texttt{eqQuiz.mdb}: A Microsoft Access 2000 database is used
+ with the demostration files \texttt{quiz1.tex} and \texttt{quiz2.tex}.
+\end{questions}
+
+The \pkg{eq2db} package requires the \pkg{exerquiz} package to create online
+quizzes and to create supporting buttons and text fields. The \pkg{exerquiz}
+package, in turn, assumes a number of packages; a listing of these can be
+found in the documentation for the \AcroEB.
+
+\section{The \texttt{eqRecord} option}\label{eqRecordOption}
+
+In this section we describe how to create an online quiz that is to be
+submitted to the server-side script \app{eqRecord.asp}\footnote{The script
+\textsf{eqRecord.asp} comes with absolutely \emph{no guarantees}. Extensive
+testing should be made on your own system to assure yourself script is
+reliable enough to use in practice. Feel free to modify the script to suite
+your needs.}. For this option, quiz results are saved to a database. The
+\opt{eqRecord} option and its corresponding script \app{eqRecord.asp} require
+that Adobe's \textsf{FDF Toolkit} is installed on
+your \app{Windows} server\FmtMP[\baselineskip]{FDF Toolkit required}.
+
+\redpoint \texttt{quiz1.tex} and \texttt{quiz2.tex} are the demo
+files for this option.
+
+\paragraph*{In the preamble.}
+The steps to create a quiz to be submitted to
+\textsf{eqRecord} are simple enough. First, the preamble of your
+document should look something like this:
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small,commandchars=!()]
+\documentclass{article}
+\usepackage[designi]{web}
+\usepackage{exerquiz}
+\usepackage[eqRecord!grayV(,tagged)]{eq2db}
+\end{Verbatim}
+You may have other packages loaded, as well as other options for \pkg{web}
+and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in
+the following sense: If the \pkg{eq2db} package is not loaded, then an
+\pkg{exerquiz} \env{quiz} is self-contained, that is, it is not submitted to
+a server-side script; if \pkg{eq2db} package is loaded, then the quizzes are
+submitted to a server-side script. The \opt{tagged} option may be optionally
+included in the option list of \pkg{eq2db}, shown in gray.
+
+\paragraph*{In the body.} Next, you write your \pkg{exerquiz} \env{quiz}:
+\begin{equation}
+\begin{minipage}{336pt}
+\begin{Verbatim}[fontsize=\small]
+\eqSubmit{http://www.example.edu/scripts/eqRecord.asp\#FDF}
+ {QuizIt}{Math101}
+\begin{quiz*}{Quiz1}
+Answer each of the following. Passing is 100\%.
+\begin{questions}
+\item ...
+...
+\item ...
+\end{questions}
+\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
+\end{Verbatim}
+\end{minipage}\label{display:BodyEqRec}
+\end{equation}
+Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz},
+it takes three parameters.
+\begin{equation}
+\begin{minipage}{225pt}
+\begin{Verbatim}[fontsize=\small,commandchars=!()]
+\eqSubmit{!meta(submitURL)}{!meta(dbName)}{!meta(dbTable)}
+\end{Verbatim}
+\end{minipage}\label{display:SubmitRec}
+\end{equation}
+
+\subparagraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential
+information use by the server-side scripts. The parameters of \cs{eqSubmit}
+are briefly described.
+\begin{aebQuote}\rightskip0pt
+\begin{description}\def\NH{\relax\hspace*{-\labelsep}}%
+\item\NH\meta{submitURL} is the {\URL} to the script \texttt{eqRecord.asp\#FDF}.
+ Internally, the value of this parameter is saved in the text macro
+ \cs{eq@CGI}. Note that the name of the script \texttt{eqRecord.asp} has
+ \texttt{\#FDF} appended (the hash mark `\texttt{\#}' followed by the fragment
+ identifier {\FDF}\index{fragment identifier (FDF)@fragment identifier (FDF)}).
+
+\item\NH\meta{dbName} is the name of the database to use. My examples use
+ ODBC, with \texttt{QuizIt} as the DSN (data source name).
+
+\item\NH\meta{dbTable} is the name of the
+table into which the data record is to be inserted (this is \texttt{Math101}
+in the example above).
+\end{description}
+\end{aebQuote}
+The three arguments of the command \cs{eqSubmit} are used to define the
+values of \cs{db@Name}, \cs{db@Table} and \cs{eq@CGI}, respectively, the
+values of which are used to populate the hidden fields.
+
+Assuming \textsf{eqRecord.asp} is installed on your web server, and the
+\textsl{FDF Toolkit} has also been installed (see Section~\ref{settingup}),
+we are ready to submit the quiz.
+
+\subsection{Field Values Processed by \textsf{eqRecord.asp}}\label{eqRfieldvalues}
+
+The \textsf{eqRecord} script processes two classes of field data: certain
+``\hyperref[hardwired]{hard-wired}'' field data; and field data having a
+\hyperref[hierarchalfields]{hierarchal} name with a root of either
+\anglemeta{dbName} or \texttt{IdInfo}, e.g., \texttt{Quiz1.numQuestions} or
+\texttt{IdInfo.Name.Last}. Details of each of these follow.
+
+\subsubsection{``Hard-wired'' Fields}\label{hardwired}
+
+When you compile your source document using the package
+\pkg{eq2db} with the \texttt{eqRecord} option, the package
+creates three hidden text fields, with field titles of
+\texttt{dbName}, \texttt{dbTable} and \texttt{quizName}. These
+hidden fields are created under the `End Quiz' button. At submit time,
+these fields are populated and submitted. Below is an enumerated list
+of these three fields with a brief description of each:
+\begin{enumerate}
+ \item \texttt{dbName}: The name of the database to which the
+ data is to be saved. (I've been using ODBC to reference the database.)
+ \item \texttt{dbTable}: The name of the table within \texttt{dbName} where the data
+ is to be stored.
+ \item \texttt{quizName}: The name of the quiz or test. Name would uniquely characterize
+ the quiz/test the student has taken.
+\end{enumerate}
+The first two hidden fields are populated by the second and third arguments,
+respectively, of \cs{eqSubmit}, as defined in
+display~\eqref{display:SubmitRec}. The third piece of data,
+\texttt{quizName}, is obtained from the first required argument of the
+\env{quiz} environment. See the skeleton example in
+display~\eqref{display:BodyEqRec}, there you'll see
+\verb~\begin{quiz*}{Math101}~. The argument `\texttt{Math101}' is the quiz
+name and is passed to the server-side script as the value of the
+\texttt{quizName} hidden text field.
+
+
+\subsubsection{Fields with Hierarchal Names}\label{hierarchalfields}
+
+Other than the fields described in \nameref{hardwired}, \textsf{eqRecord.asp} processes
+only fields with hierarchal names that have a root name of \anglemeta{quizName}
+(see \nhnameref{hardwired} on page~\pageref{hardwired}) or a root name of \texttt{IdInfo}.
+
+\paragraph*{\texttt{quizName} (\cs{currQuiz}):} \texttt{quizName} is the field title of one of the hidden fields,
+its value is picked up as the first argument of the \env{quiz}
+environment; the value is stored in the text macro \cs{currQuiz}.
+
+In addition to the ``hard-wired'' hidden fields described earlier, there are actually three
+more hidden fields (under the `End Quiz' button) with root name \anglemeta{quizName}. These are
+\begin{itemize}
+ \item \cs{currQuiz.numQuestions}: The number of questions in the quiz
+ \item \cs{currQuiz.numCorrect}: The number of correct questions
+ \item \cs{currQuiz.Responses}: a list of all the responses of the user
+\end{itemize}
+The values of these fields are also sent to \textsf{eqRecord.asp}.
+There is a mechanism for creating more hidden fields the values of
+which are sent to the script. The technique for doing this will be
+discussed later.
+
+\paragraph*{\texttt{IdInfo}:}\chgCurrLblName{IdInfo}\label{para:IdInfo} As mentioned earlier, \textsf{eqRecord.asp} processes fields
+that use a hierarchal naming convention, with root name of \anglemeta{quizName} or \texttt{IdInfo}.
+Fields whose root name is \texttt{IdInfo} are meant to hold information about the person
+taking the quiz: first name, last name, student number, etc.
+
+For example, you can create fields the user fills in for
+self-identifi\-cation. In the preamble, you can define new commands:
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+% User's First Name
+\newcommand\FirstName[2]{\textField{IdInfo.Name.First}{#1}{#2}}
+
+% User's Last Name
+\newcommand\LastName[2]{\textField{IdInfo.Name.Last}{#1}{#2}}
+
+% User's SSN
+\newcommand\SSN[2]{\textField[\MaxLen{11}
+ \AA{\AAKeystroke{AFSpecial_Keystroke(3);}
+ \AAFormat{AFSpecial_Format(3);}
+ }]{IdInfo.SSN}{#1}{#2}}
+\end{Verbatim}
+\noindent Note that I've defined these fields so that their names
+follow a hierarchal name structure, with a root of
+\texttt{IdInfo}. The two required arguments are the dimensions of
+the text field being constructed. For example,
+\verb+\FirstName{100bp}{10bp}+ creates a text field with a title of
+\texttt{IdInfo.Name.First} which is \texttt{100bp} wide and \texttt{10bp} high.
+
+\redpoint See the demo file \texttt{quiz1.tex} for examples.
+
+\medskip\noindent
+Additional \texttt{IdInfo} fields can be constructed.
+
+\subsection{Mapping PDF Field Names onto DB Field Names}\label{mappdf2db}
+
+\textsf{eqRecord.asp} is a quasi-general script for mapping the values of PDF fields
+into corresponding fields in a database. The way \textsf{eqRecord} is set up, the
+DB field name is derived from the PDF field name. For example, the value of the PDF field
+\texttt{Quiz1.numQuestions} is stored in the DB under the DB field name of \texttt{numQuestions}.
+
+For field names such as \texttt{IdInfo.Name.Last}, we can't map
+this into the DB field name \texttt{Name.Last} because for some
+databases (notably, Microsoft Access) database field names
+containing a `dot' are not legal. As a work around,
+\textsf{eqRecord.asp} strips all dots from the field name, and
+replaces them with the value of the VB Script variable
+\texttt{dotReplace}. The definition of \texttt{dotReplace} in \textsf{eqRecord.asp} is
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+Dim dotReplace : dotReplace = "_"
+\end{Verbatim}
+\noindent That is, a `dot'(\texttt.) is replaced by an `underscore' (\texttt\_).
+
+\medskip\noindent
+The table below illustrates the mapping of PDF field name onto database field
+names. Suppose the \texttt{quizName} is \texttt{Quiz1}:
+
+\medskip
+\begin{longtable}{>{\ttfamily}l>{\ttfamily}ll}
+\multicolumn1{>{\bfseries}l}{PDF Field Name}&\multicolumn1{>{\bfseries}l}{DB Field Name}&\multicolumn1{>{\bfseries}l}{Required}\\\hline\endfirsthead
+\multicolumn1{>{\bfseries}l}{PDF Field Name}&\multicolumn1{>{\bfseries}l}{DB Field Name}&\multicolumn1{>{\bfseries}l}{Required}\\\hline\endhead
+quizName (e.g.,\,Quiz1) & quizName & Yes\\
+Quiz1.numQuestions & numQuestions & Yes\\
+Quiz1.numCorrect & numCorrect & Yes\\
+Quiz1.Responses & Responses & Yes\\
+IdInfo.Name.Last & Name\_Last& No\\
+IdInfo.Name.First& Name\_First & No\\
+IdInfo.SSN & SSN & No\\
+\multicolumn1l{N/A} & TimeOfQuiz & Yes\\
+\end{longtable}
+\noindent The last entry needs comment: \textsf{eqRecord.asp} generates a time stamp when a quiz is processed. This time stamp
+is stored in a field with a name of \texttt{TimeOfQuiz}. This is a required field in your database.
+
+
+\subsection{Adding more Hidden Fields}\label{moreHiddenFields}
+
+When you add fields with a hierarchal name with a root of
+\cs{currQuiz} or \texttt{IdInfo}---whether hidden or
+not---the values of these fields will be submitted and processed
+by \textsf{eqRecord.asp}. When you add fields in your document,
+there should be a corresponding DB field to receive this data
+(see Section~\ref{mappdf2db} for naming conventions). You can also
+add hidden fields to transmit information about the quiz that the
+user does not need to see.
+
+\Example Suppose you have a point value to each question and want to report
+the point score (rather than the number missed). In this case, you would use
+the \cs{PointsField} field instead of the \cs{ScoreField} (though you could
+use both).
+
+\cs{PointsField} has a hierarchal name, but its root
+does not begin with \cs{currQuiz}; consequently, the value
+of this field is not submitted to \textsf{eqRecord.asp}. (The
+value of this field is a string what is meant to be read by the
+user; it reads, for example, ``Score: 16 out of 20''; we don't
+want this string submitted anyway, we would want the point score
+(16) and the total points (20) submitted.) We want to transmit the
+points scored and the total number of points to the server-side
+script.
+
+The \pkg{eq2db} package defines two helper commands for
+creating hidden fields (these hidden fields are hidden under the
+`End Quiz' button); these are \cs{addHiddenField} and
+\cs{populate\-HiddenField}.
+
+Suppose we had a quiz, \texttt{Quiz1}, in which we wanted to
+report points scored and total points. First, we need to add two
+hidden fields, we'll call them \texttt{Quiz1.ptScore} and
+\texttt{Quiz1.nPointTotal}; we create the hidden fields using
+\cs{addHiddenField}:
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+\addHiddenTextField{Quiz1.ptScore}{}
+\addHiddenTextField{Quiz1.nPointTotal}{\theeqpointvalue}
+\end{Verbatim}
+\noindent The first parameter is the title (name) of the field,
+the second parameter is the default value. For the first line, no
+default value is given; for the second line, a default value of
+\cs{theeqpointvalue} is given. The counter \cs{eqpointvalue}
+contains the total number of points for the quiz so we can insert
+that value at \texttt{latex} compile-time.
+
+The value of the first field added, \texttt{Quiz1.ptScore}, is not
+known until a user takes a quiz and submits results. The \pkg{eq2db} command
+\cs{populateHiddenField} inserts the necessary
+JavaScript that would populate the specified field. For example,
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+\populateHiddenField{Quiz1.ptScore}{ptScore}
+\end{Verbatim}
+The first parameter is the field name, the second is the value the field
+is to hold when the user clicks on `End Quiz'. The command
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+\populateHiddenField{fieldname}{fieldvalue}
+\end{Verbatim}
+expands to,
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+this.getField("fieldname").value = fieldvalue;
+\end{Verbatim}
+which is the JavaScript for populating the field,
+is inserted into the code just prior to the submission of the
+data.
+
+\redpoint
+See second quiz in the sample file \texttt{quiz1.tex} for
+a complete example of creating a quiz with weight set for each
+question, and for reporting the point score and total points.
+\endredpoint
+
+\medskip\noindent The table below lists some variables (both \LaTeX{} and
+JavaScript) that might be useful in extracting desired information from
+quiz for submittal.
+
+\begin{longtable}{>{\ttfamily}l>{\PBS\raggedright}p{.55\linewidth}}
+\multicolumn1{>{\bfseries}l}{Variable}&\multicolumn1{>{\bfseries}l}{Description}\\\hline\endfirsthead
+\multicolumn1{>{\bfseries}l}{Variable}&\multicolumn1{>{\bfseries}l}{Description}\\\hline\endhead
+Score & Score of the user with one point per problem. This value is always reported in the hidden text field
+\texttt{quizName.numCorrect}. This is a JavaScript variable known when the user finishes the quiz.
+This value is always reported in \texttt{quizName.numQuestions}, the hidden text field.\\
+\cs{thequestionno} & The number of questions in the current quiz. A \LaTeX{} macro; known at compile-time.\\
+Responses & A comma-delimited list of all responses of the user. A JavaScript variable known when
+the user finishes the quiz. Always reported in the hidden field
+\texttt{quizName.Responses}\\
+ptScore & The point score of the user's quiz. A JavaScript variable, known when the user finishes quiz.\\
+\cs{theeqpointvalue} & The total number of points in the current quiz. A \LaTeX{} macro, known at
+compile-time.\\
+pcScore& The score expressed as a percent. A JavaScript variable known when the user finishes the quiz. \\
+quizGrade & The letter grade of the user's quiz. A JavaScript variable, known at ``run-time''. \\
+\cs{eqGradeScale} & The grade scale for the quiz. A \LaTeX{} macro, known at ``compile-time''.\\
+\end{longtable}
+
+%\redpoint Other useful variables---perhaps at developers request---will be
+%added in the future. \endredpoint
+
+
+\subsection{Setting Up}\label{settingup}
+
+In this section, we briefly discuss configuring your server and setting up
+the demo files that accompany this distribution.
+
+\subsubsection{Configuring the Server}
+
+On the server side, in order for \textsf{eqRecord.asp} to run
+correctly, Microsoft Internet Information Server (IIS), version
+4.0 or greater, is needed. The script \textsf{eqRecord.asp} needs to be
+placed where ASP scripts have execute permissions.
+
+The \textsf{eqRecord.asp} uses the \textsl{Adobe FDF Toolkit}\footnote{Currently located at the
+\href{http://partners.adobe.com/public/developer/acrobat/devcenter.html}{Acrobat Family Developer Center}.}, version
+6.0. Follow the directions for installation contained in the
+accompanying documentation.
+
+Install \textsf{eqRecord.asp} in a folder (perhaps called
+\texttt{Scripts}) designated to execute scripts. If you don't
+have such a folder, then the following steps explain how to
+create a virtual directory through IIS that points to this folder.
+
+\begin{enumerate}
+\item Create a new folder on the system (\texttt{Scripts}, for example). Its
+recommended location is inside the \texttt{Inetpub} folder.
+
+\item Place \textsf{eqRecord.asp} in this newly created folder.
+
+\item In the MMC snap-in for IIS, create a virtual directory by
+right-clicking on the Default Web Site and selecting
+\texttt{New\;>\;Virtual Directory}.
+
+\item Type ``Scripts'' (or whatever the name of the folder you
+created in~Step~1) as the alias for the virtual directory, and
+then link it to the physical directory you created in Step~1.
+
+\item Make sure that ``Script execution'' privileges are enabled.
+If not, enable them.
+\end{enumerate}
+
+\subsubsection{Set Up the Demo Files}
+
+Place the Access 2000 database, \texttt{QuizIt.mdb}, in a folder
+that is accessible by the server, such as the root level of your
+web server, or perhaps, a folder dedicated to database files.
+Register the database with the ODBC Data Source Administrator as a
+System DSN under the System Data Source Name of ``QuizIt''.
+
+Modify the first parameter of \cs{eqSubmit} in \texttt{quiz1.tex}
+and compile (\texttt{latex}), then create \texttt{quiz1.pdf} using
+\textsf{Acrobat Distiller}, \textsf{pdftex} or \textsf{dvipdfm},
+and place it on your server. Test by opening \texttt{quiz1.pdf}
+in your web browser and taking a sample test. Good luck, I hope it works!
+
+\subsubsection{Comments on Demo Files}\label{demofiles}
+
+\paragraph*{\texttt{quiz1.tex}:} This file has two quizzes,
+\texttt{Quiz1} and \texttt{Quiz2}. \texttt{Quiz1} has no frills,
+the user enters his/her name and SSN, takes the quiz, and results
+are saved to the \texttt{eqQuiz.mdb} Access database.
+\texttt{Quiz2} is a bit more interesting as it demonstrates how to
+assign points to each question, and how to report the results. The
+techniques used in this quiz were discussed in
+Section~\ref{moreHiddenFields}.
+
+\paragraph*{\texttt{quiz2.tex}:} The quizzes of \texttt{quiz1.tex}
+did not check whether the user is enrolled in the class, and as
+such, is allowed to take the quiz. The demo file
+\texttt{quiz2.tex} demonstrates how to\dots
+\begin{questions}
+ \item check whether the user has entered a valid SSN, that is, the
+ SSN of someone enrolled in the class, or is permitted to take the quiz
+
+ \item set a deadline date to take the quiz
+
+ \item set a time limit to take the quiz
+\end{questions}
+Other variations are possible.
+
+
+\subsection{Accessing Results in the DB}
+
+The database that is to hold quiz results is placed on a
+web-server and consequently, is not easily accessible by the
+instructor. The ASP script \textsf{GenericDB}\footnote{\url{http://www.genericdb.com/}} developed by Eli Robillard, is
+a tool that can be used to access the database through your web
+browser. Using \textsf{GenericDB}, you can view, edit, update, add
+new and delete database records---and it's free! Check it out!
+
+
+\section{The \texttt{eqText} Option}\label{eqTextOption}
+
+In this section, we describe how to submit your data to a server-side script
+that save the data to a tab-delimited text field. The \opt{submitAs} option
+can be used with the \env{eqText} option. With \texttt{submitAs=FDF}, the
+form data is submitted in the FDF format, the native form data format for
+PDF, the target script should be \app{eqText.asp}. When
+\texttt{submitAs=HTML} is used, the form data is submitted as ordinary HTML
+form data, which can then be processed by any public domain script;
+alternately, you can use one of the scripts in
+Table~\ref{table:QuizScripts1}. These four scripts are available on the
+CD-ROM that accompanies the book \AEBBook~\cite{book:AEBB}.
+
+
+\begin{table}[htb]\centering
+\begin{tabular}{r>{\ttfamily\raggedright}p{1.5in}}
+\multicolumn{1}{>{\bfseries}r}{Option and return type}&%
+\multicolumn{1}{>{\bfseries}l}{Script Files for \app{Windows} \& \app{Linux}}\\
+\texttt{eqText}, {\HTML} return&eqText\_h.asp
+eqText\_h.php\tabularnewline[3pt]
+\texttt{eqText}, {\FDF} return&eqText\_hf.asp\#FDF\penalty0
+eqText\_hf.php\#FDF
+\end{tabular}
+\caption{Scripts for \opt{eqText} \& \texttt{submitAs=HTML} options}\label{table:QuizScripts1}
+\end{table}
+
+
+\subsection{Submit as FDF}
+
+We describe how to create an online quiz that is
+to be submitted to the server-side script
+\textsf{eqText.asp}\footnote{The script \textsf{eqText.asp} comes
+with absolutely \emph{no guarantees}. Extensive testing should be
+made on your own system to assure yourself script is reliable
+enough to use in practice.}. With this option, you save your quiz data to
+a tab-delimited file. The \textsl{FDF Toolkit}\FmtMP[\baselineskip]{FDF Toolkit required} is required to be installed on the
+\app{Windows} server.
+
+\redpoint The demo file for this option is \texttt{quiz4.tex}.
+
+\paragraph*{In the preamble.} Begin the document with the usual preamble for an
+\pkg{exerquiz} document, but include the \pkg{eq2db} package with the
+\opt{eqRecord} option.
+\begin{equation}
+\begin{minipage}{355pt}
+\begin{Verbatim}[fontsize=\small,commandchars=!()]
+\documentclass{article}
+\usepackage{amsmath}
+\usepackage[!grayV(!anglemeta(driver)),designi]{web} % driver: dvips, pdftex, xetex
+\usepackage{exerquiz}
+\usepackage[!grayV(submitAs=FDF,)eqText]{eq2db}
+\end{Verbatim}
+\end{minipage}\label{display:PreamEqText}
+\end{equation}
+Shown in gray are the \anglemeta{driver} and \opt{submitAs} options. The
+\opt{pdflatex} and \opt{xelatex} applications are automatically detected, so
+only \opt{dvips} needs to be specified if you are building your PDF with
+\app{Acrobat Distiller}. The submission type is FDF by default, so
+\opt{submitAs=FDF} need not be listed in the options of \pkg{eq2db}.
+
+\paragraph*{In the body.} The following is a rough outline of an \pkg{exerquiz}
+quiz document that submits to \app{eqRecord.asp}, the preamble declarations of
+display~\eqref{display:PreamEqText}.
+\begin{equation}
+\begin{minipage}{330pt}
+\begin{Verbatim}[fontsize=\small]
+\eqSubmit{http://www.example.edu/scripts/eqText.asp\#FDF}
+ {c:/Inetpub/Data/math101.txt}{Math101}
+\begin{quiz*}{Quiz1} Answer each of the following. Passing
+is 100\%.
+\begin{questions}
+\item ...
+...
+\item ...
+\end{questions}
+\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
+\end{Verbatim}
+\end{minipage}\label{display:eqTextTemplate}
+\end{equation}
+Notice that `\texttt{\#FDF}' is appended to the path, this informs the PDF viewer to expect
+the server-side script to return FDF form data.
+
+\medskip
+Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz},
+it takes three parameters.
+\begin{equation}
+\begin{minipage}{276pt}
+\begin{Verbatim}[fontsize=\small,commandchars=!()]
+\eqSubmit{!meta(submitURL)}{!meta(pathToTabFile)}{!meta(courseName)}
+\end{Verbatim}
+\end{minipage}\label{display:SubmitTxt}
+\end{equation}
+\subparagraph*{Description of the parameters.} The \cs{eqSubmit} command
+provides essential information use by the server-side scripts. Its parameters
+are briefly described.
+\begin{description}
+\item\meta{submitURL} is the {\URL} to the server-side script
+ \texttt{eqText.asp}. Internally, the value of this parameter is saved in
+ the text macro \cs{eq@CGI}.
+
+\item\meta{pathToTabFile} is the path to the tab-delimited file on the
+ server where the script is to save the data. On \app{Windows},
+ \meta{pathToTabFile} is the physical (absolute) path to the file, on
+ \app{Linux} it can be a relative path (relative to the folder containing
+ the executing script). Internally, this value is saved in the text macro
+ \cs{db@Name}.\footnote{Choice for
+ the names of \cs{db@Name} and \cs{db@Table} were originally based on the
+ \texttt{eqRecord} option where data is saved to a database.}\xdef\fnNameChoice{\thefootnote}
+
+\item\meta{courseName} is the course name of the class taking the quiz.
+ Internally, this value is saved in the text macro
+ \cs{db@Table}.${}^\text{\fnNameChoice}$
+\end{description}
+
+
+\subsubsection{Field Values Processed by \textsf{eqText.asp}}\label{eqTfieldvalues}
+
+The \textsf{eqText} script processes two classes of field data:
+certain ``\hyperref[hardwiredText]{hard-wired}'' field data; and field data
+having a \hyperref[hierarchalfieldsText] {hierarchal} name with a root of either
+\anglemeta{dbName} or \texttt{IdInfo}, e.g., \texttt{Quiz1.numQuestions} or
+\texttt{IdInfo.Name.Last}. Details of each of these follow.
+
+\paragraph*{``Hard-wired'' Fields.}\label{hardwiredText}
+When you compile your source document with the package \pkg{eq2db} with the
+\texttt{eqText} option, the package creates a number of hidden text fields.
+These hidden fields are created under the `End Quiz' button. At submit time,
+these fields are populated and submitted along with the quiz data. Below is
+an enumerated list of these hidden fields with a brief description of each:
+\begin{enumerate}
+ \item \texttt{pathToTxtFile}: The value of second argument of
+ \cs{eqSubmit} populates this text field.
+ \item \texttt{courseName}: The value of the third parameter of
+ \cs{eqSubmit} populates this text field.
+ \item \texttt{quizName}: The name of the quiz or test, this is
+ \cs{currQuiz}. Name should uniquely characterize the quiz/test the
+ student is taking.
+\end{enumerate}
+The first two hidden fields are populated by the second and third arguments,
+respectively, of \cs{eqSubmit}, as defined in
+display~\eqref{display:SubmitTxt}. The third piece of data,
+\texttt{quizName}, is obtained from the first required argument of the
+\env{quiz} environment. See the skeleton example in
+display~\eqref{display:eqTextTemplate}, there you'll see
+\verb~\begin{quiz*}{Math101}~. The argument `\texttt{Math101}' is the quiz
+name and is passed to the server-side script as the value of the
+\texttt{quizName} hidden text field.
+
+\paragraph{Fields with Hierarchal Names.}\label{hierarchalfieldsText}
+
+Other than the fields described in \nameref{hardwired}, \textsf{eqText.asp} processes
+only fields with hierarchal names that have \cs{currQuiz} as a root name
+(see \nhnameref{hardwired} above) or a root name of \texttt{IdInfo}.
+
+\subparagraph*{\texttt{quizName} (\cs{currQuiz}):} \texttt{quizName} is the
+field title of one of the hidden fields, its value is picked up as the first
+argument of the \env{quiz} environment; the value is stored in the text
+macro \cs{currQuiz}.
+
+In addition to the ``hard-wired'' hidden fields described earlier, there are
+actually five more hidden fields (under the \textsf{End Quiz} button) with
+root name \cs{currQuiz}. These are,
+\begin{itemize}
+ \item \cs{currQuiz.numQuestions}: The number of questions in the quiz.
+ \item \cs{currQuiz.numCorrect}: The number of correct questions.
+ \item \cs{currQuiz.Responses}: A list of all the responses of the user.
+ \item \cs{currQuiz.ptScore}: The point score the student received on
+ completion of the quiz.
+ \item \cs{currQuiz.nPointTotal}: The total number of points in the
+ quiz.
+\end{itemize}
+The values of these fields are also sent to the server-side script for the
+\texttt{eqText} option. There is a mechanism for creating more hidden fields
+the values of which are sent to the script. The technique for doing this is
+discussed in \Nameref{moreHiddenFields}.
+
+\subparagraph*{\texttt{IdInfo}:}\label{spara:IdInfoText}
+As mentioned earlier, the \textsf{eqText} scripts process fields that use a
+hierarchal naming convention, with root name of \cs{currQuiz} or
+\texttt{IdInfo}. Fields whose root name is \texttt{IdInfo} are meant to hold
+information about the person taking the quiz: first name, last name, student
+number, and so on. Refer to the paragraph titled \textbf{\nhnameref{para:IdInfo}}
+on page~\pageref{para:IdInfo} for more information.
+
+\subsubsection{Setting up the Script}
+
+On the server side, in order for \textsf{eqText.asp} to run
+correctly, Microsoft Internet Information Server (IIS), version
+4.0 or greater, is needed. The script \textsf{eqText.asp} should
+be placed where ASP scripts have execute permissions.
+
+\subsection{Submit as HTML}
+
+When the \opt{eqText} and \opt{submitAs=HTML} options are specified for
+\pkg{eq2db}, the form data are submitted as ordinary HTML form data. For the
+\opt{eqText} option, it is meant that the server-side script save the form
+data as a tab-delimited file. You can develop your own script for doing this,
+or you can use one of the scripts of Table~\ref{table:QuizScripts1},
+available on the CD-ROM of the book \AEBBook~\cite{book:AEBB}. The advantage of submitting as
+HTML is that the \textsl{FDF Toolkit} is not needed, and the techniques for
+writing a server-side script are well known.
+
+The preamble of your document should look something like the following.
+\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
+\documentclass{article}
+\usepackage[designi]{web}
+\usepackage{exerquiz}
+\usepackage[eqText,submatAs=html,tagged]{eq2db}
+\end{Verbatim}
+The \opt{tagged} option is recommended for the \opt{eqText} option but
+no required. You may have other packages loaded, as well as other options for
+\pkg{web} and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be
+seamless in the following sense: If the \pkg{eq2db} package is not loaded,
+then an \pkg{exerquiz} quiz is self-contained, that is, it is not submitted
+to a server-side script; if \pkg{eq2db} package is loaded, then the quizzes
+are submitted to a server-side script.
+
+In addition to the introduction of the \pkg{eq2db} package in the preamble,
+there are two more important commands:
+\begin{equation}
+\begin{minipage}{300pt}
+\begin{Verbatim}[commandchars=!()]
+\eqSubmit{!meta(submitURL)}{!meta(pathToTabFile)}{!meta(courseName)}
+\rtnURL{!meta(returnURL)}
+\end{Verbatim}
+\end{minipage}\label{display:eqSubmitT}
+\end{equation}
+\cs{eqSubmit}, defined in \pkg{exerquiz}, is required; \cs{rtnURL}, defined
+in \pkg{eq2db}, is required only when the return from the server is an
+{\HTML} page, but is recommended.
+
+\paragraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential
+information use by the server-side scripts, \cs{rtnURL} provides a return
+{\URL} that points to where the student should navigate after the quiz.
+Their parameters, as indicated in display~\eqref{display:eqSubmitT}, are briefly described.
+\begin{description}
+\item\meta{submitURL} is the {\URL} of one of the server-side scripts in
+ Table~\ref{table:QuizScripts1}. Internally, the value of this parameter
+ is saved in the text macro \cs{eq@CGI}.
+
+\item\meta{pathToTabFile} is the path to the tab-delimited file on the
+ server where the script is to save the data. On \app{Windows},
+ \meta{pathToTabFile} is the physical (absolute) path to the file, on
+ \app{Linux} it can be a relative path (relative to the folder containing
+ the executing script). Internally, this value is saved in the text macro
+ \cs{db@Name}.${}^\text{\fnNameChoice}$
+
+\item\meta{courseName} is the course name of the class taking the quiz.
+ Internally, this value is saved in the text macro
+ \cs{db@Table}.${}^\text{\fnNameChoice}$
+
+\item\meta{returnURL} is the {\URL} of the page the student should return
+ to after finishing the quiz. The value of \cs{rtnURL} is required when
+ the script returns an {\HTML} page, and is useful when the return is
+ {\FDF}. Internally, \cs{rtnURL} defines the text macro \cs{thisRtnURL}
+ to hold \meta{returnURL}.
+\end{description}
+
+\paragraph*{The scripts.} The \meta{submitURL} points to the server-side script that is to process the form data.
+The scripts of Table~\ref{table:QuizScripts1} were written for the upcoming book
+{\AEBBook} and are available on the accompanying CD-ROM. Refer the book for the details of
+implementing these scripts.
+
+\paragraph*{HTML versus FDF return.} The scripts of Table~\ref{table:QuizScripts1} are of two types:
+HTML return and FDF return. In the first case, after the student has submitted his/her quiz,
+the server-side script returns an HTML page to the browser window with an assessment of the
+student's efforts on the quiz. In the second case, the script sends back an alert dialog box message saying
+the data is received and saved; the quiz is self-marking for the student to review.
+Details are laid out in {\AEBBook}~\cite{book:AEBB}.
+
+\section{The \texttt{eqEmail} Option}\label{eqEmailOption}
+
+In this section, we describe how to submit your data to a server-side script
+that in turn sends an email message to a list of recipients, the body of the
+messages contains the student's quiz results. The \opt{submitAs} option can
+be used with the \env{eqEmail} option. With \texttt{submitAs=FDF}, the form
+data is submitted in the FDF format, the native form data format for PDF, the
+target script should be \app{eqEmail.asp}. When \texttt{submitAs=HTML} is
+used, the form data is submitted as ordinary HTML form data, which can then
+be processed by any public domain script; alternately, you can use one of the
+scripts in Table~\ref{table:QuizScripts2}. These four scripts are available
+on the CD-ROM that accompanies the book \AEBBook~\cite{book:AEBB}.
+
+\begin{table}[htb]\centering
+\begin{tabular}{r>{\ttfamily\raggedright}p{1.5in}}
+\texttt{eqEmail}, {\HTML} return&eqEmail\_h.asp\penalty0eqEmail\_h.php\tabularnewline[3pt]
+\texttt{eqEmail}, {\FDF} return&eqEmail\_hf.asp\#FDF\penalty0
+eqEmail\_hf.php\#FDF
+\end{tabular}
+\caption{Scripts for \opt{eqEmail} \& \texttt{submitAs=HTML} options}\label{table:QuizScripts2}
+\end{table}
+
+
+\subsection{Submit as FDF}
+
+We describe how to create an online quiz that is
+to be submitted to the server-side script
+\app{eqEmail.asp}\footnote{The script \textsf{eqEmail.asp} comes
+with absolutely \emph{no guarantees}. Extensive testing should be
+made on your own system to assure yourself script is reliable
+enough to use in practice. Feel free to modify the script to
+suite your needs. If your improvements are noteworthy, please
+allow me to incorporate them into the basic \textsf{eqEmail.asp}
+for others to use. }. For this option, quiz results are e-mailed
+to the instructor. The \textsl{FDF Toolkit} is required to be installed on the
+\app{Windows} server\FmtMP[\baselineskip]{FDF Toolkit required}.
+
+\redpoint \texttt{quiz3.tex} is the demo file for this option.
+
+\medskip\noindent The steps to create a quiz to be submitted to
+\textsf{eqEmail} are simple enough. First, the preamble of your
+document should look something like this:
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+\documentclass{article}
+\usepackage[designi]{web}
+\usepackage{exerquiz}
+\usepackage[eqEmail]{eq2db}
+\end{Verbatim}
+\noindent You may have other packages loaded, as well as other
+options for \pkg{web} and \pkg{exerquiz}. The \pkg{eq2db}
+package was designed to be seamless in the following sense: If the
+\pkg{eq2db} package is not loaded, then an \pkg{exerquiz}
+\env{quiz} is self-contained, that is, it is not submitted to a
+server-side script; if \pkg{eq2db} package is loaded, then the
+quizzes are submitted to a server-side script.
+
+Next, you write your \pkg{exerquiz} \env{quiz}:
+
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+\eqSubmit{http://www.example.edu/scripts/eqEmail.asp\#FDF}
+ {dpspeaker@example.edu}{Math101}
+\begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%.
+\begin{questions}
+\item ...
+...
+\item ...
+\end{questions}
+\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
+\end{Verbatim}
+Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz}.
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small,commandchars=!()]
+\eqSubmit{!meta(submitURL)}{!meta(recipients)}{!meta(courseName)}
+\end{Verbatim}
+The first parameter is the URL to the server-side script, in the example
+above, we have \texttt{http://www.example.edu/scripts/eqEmail.asp\#FDF} (note
+the suffix of \texttt{\#FDF}); the second parameter, \meta{recipients},
+is the e-mail address of the person to receive the quiz results; the third
+parameter, \meta{courseName} is the course name. In the above example,
+the course name is \texttt{Math101}.
+
+\redpoint If meta{recipients} is a comma-delimited list of e-mail addresses, then
+\textsf{eqEmail.asp} will parse the list, and use the first e-mail in the list in the
+\texttt{From} field of the e-mail. Other email addresses in the list also receive copies
+of the quiz results.\endredpoint
+
+\medskip
+There is another parameter of importance. The first argument of
+the \env{quiz} environment is the \texttt{quizName} of the quiz, this is
+\texttt{Quiz1} in the above example.
+
+Assuming \textsf{eqEmail.asp} is installed on your web server, and
+the \textsl{FDFToolkit} has also been installed (see
+Section~\ref{settingup}), we are ready to submit the quiz. Below
+is the body of one of my test e-mails I made using
+\texttt{quiz3.pdf}:
+
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+Course Information
+ Course Name: Math101
+ Quiz: Quiz1
+ TimeOfQuiz: 8/23/2003 8:12:40 PM
+
+Student Results
+ Name_First: Don
+ Name_Last: Story
+ SSN: 121212121
+ Responses: Leibniz,2x e^(x^2),-1,-cos(x)
+ numCorrect: 4
+ numQuestions: 4
+\end{Verbatim}
+\noindent If you add more fields, as described in
+Section~\ref{moreHiddenFields}, this information should be appended to
+the body of the e-mail.
+
+\subsubsection{Field Values processed by \textsf{eqEmail.asp}}
+
+Actually, \textsf{eqEmail.asp} is a variation of
+\textsf{eqRecord.asp} and many of the details of this section are
+the same \hyperref[eqRfieldvalues]{Section~\ref*{eqRfieldvalues}}.
+
+The ``hard-wired'' fields are \texttt{mailTo}, \texttt{courseName}
+and \texttt{quizName}. These fields are hidden under the `End
+Quiz' button, and are populated at submit time. As in the \texttt{eqRecord}
+option, the value of the \texttt{quizName} field comes from the argument of
+the \env{quiz} environment:
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+\eqSubmit{http://www.example.edu/scripts/eqEmail.asp\#FDF}
+ {dpspeaker@example.edu}{Math101}
+\begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%.
+\begin{questions}
+\item ...
+...
+\item ...
+\end{questions}
+\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
+\end{Verbatim}
+In this quiz, the field with name \texttt{quizName} will have a value of \texttt{Quiz1}.
+
+\medskip See paragraph ``\nameref{hierarchalfields}'', page~\pageref{hierarchalfields}, as well as
+Section~\ref{moreHiddenFields} on page~\pageref{moreHiddenFields} for
+the \texttt{eqRecord} option, the details are the same.
+
+\subsubsection{Setting up and Modifying the Script}
+
+On the server side, in order for \textsf{eqEmail.asp} to run
+correctly, Microsoft Internet Information Server (IIS), version
+4.0 or greater, is needed. The script \textsf{eqEmail.asp} should
+be placed where ASP scripts have execute permissions. There are
+two methods of sending e-mail:
+\begin{questions}
+ \item \texttt{CDONTS}: This method (which is commented out by default) can be used on
+ an NT server. Uncomment if you want to use CDONTS, and comment out the CDOSYS code lines
+ that follow.
+ \item \texttt{CDOSYS}: This can be run on a Win2000 or WinXP server.
+\end{questions}
+
+The script needs to be modified appropriate to your server, in particular, search down
+in \texttt{eqEmail.asp} for the configuration line
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+eqMail.Configuration.Fields.Item
+ ("http://schemas.microsoft.com/cdo/configuration/smtpserver")
+ = "mySMTP"
+\end{Verbatim}
+\noindent replace \texttt{mySMTP} with your SMTP server.
+
+The subject heading of the returning e-mail has the following format:
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+Quiz Results: Quiz1 of Math101
+\end{Verbatim}
+If you want another subject format, modify \texttt{eqMail.Subject} as
+desired.
+
+\subsubsection{References}
+
+The following links were used as a reference in the development of the
+\texttt{Email.asp} script.
+\begin{itemize}
+ \item CDOSYS:
+ \begin{itemize}
+ \item \href{http://invisionportal.com/show_tutorial.asp?TutorialID=160}{Invision Portal} Tutorial: CDOSYS email tutorial
+ \item \href{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cdosys/html/_cdosys_imessage_interface.asp}
+ {MSDN}: CDO for Windows 2000. The IMessage Interface. (Use MIE to view this page.)
+ \item \href{http://www.asp101.com/articles/john/cdosmtprelay/default.asp}{ASP 101} Sending Email Via an External SMTP Server Using CDO
+ \end{itemize}
+ \item CDONTS
+ \begin{itemize}
+ \item \href{http://www.juicystudio.com/tutorial/asp/cdonts.html}{Juicy Studio} The ASP CDONTS Component
+ \item \href{http://www.devasp.com/Samples/mail.asp}{DevASP} Sending Mail from ASP with CDONTS.NewMail Object
+ \end{itemize}
+\end{itemize}
+
+\subsection{Submit as HTML}
+
+When the \opt{eqEmail} and \opt{submitAs=HTML} options are specified for
+\pkg{eq2db}, the form data are submitted as ordinary HTML form data. For the
+\opt{eqEmail} option, it is meant that the server-side script should take the
+incoming form data, build an email the body of which reports the quiz
+results, and send the message to a list of recipients. You can develop your
+own script for doing this or you can use the scripts provide with the book
+\AEBBook~\cite{book:AEBB}. The advantage of submitting as HTML is that the \textsl{FDF
+Toolkit} is \emph{not needed}, and the techniques for writing a server-side
+script are well known.
+
+The preamble of your document should look something like the following.
+\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
+\documentclass{article}
+\usepackage[designi]{web}
+\usepackage{exerquiz}
+\usepackage[eqEmail,submatAs=html]{eq2db}
+\end{Verbatim}
+The \opt{tagged} option is \emph{not recommended} for the \opt{eqEmail}. You
+may have other packages loaded, as well as other options for \pkg{web} and
+\pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in the
+following sense: If the \pkg{eq2db} package is not loaded, then an
+\pkg{exerquiz} quiz is self-contained, that is, it is not submitted to a
+server-side script; if \pkg{eq2db} package is loaded, then the quizzes are
+submitted to a server-side script.
+
+In addition to the introduction of the \pkg{eq2db} package in the preamble,
+there are two more important commands:
+\begin{equation}
+\begin{minipage}{300pt}
+\begin{Verbatim}[commandchars=!()]
+\eqSubmit{!meta(submitURL)}{!meta(recipients)}{!meta(courseName)}
+\rtnURL{!meta(returnURL)}
+\end{Verbatim}
+\end{minipage}\label{display:eqSubmitE}
+\end{equation}
+\cs{eqSubmit}, defined in \pkg{exerquiz}, is required; \cs{rtnURL}, defined
+in \pkg{eq2db}, is required only when the return from the server is an
+{\HTML} page, but is recommended.
+
+\paragraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential
+information use by the server-side scripts, \cs{rtnURL} provides a return
+{\URL} that points to where the student should go to next after the quiz.
+Their parameters, as indicated in display~\eqref{display:eqSubmitE}, are briefly described.
+\begin{description}\def\NH{\relax\hspace*{-\labelsep}}%
+\item\NH\meta{submitURL} is the {\URL} of one of the server-side scripts in
+ Table~\ref{table:QuizScripts1}. Internally, the value of this parameter
+ is saved in the text macro \cs{eq@CGI}.
+
+\item\NH\meta{recipients} is a comma-delimited list of email addresses to
+ whom the quiz results are sent. For example,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+dpspeaker@talking.edu,taofdps@talking.edu
+\end{Verbatim}
+The first email address is picked off and used in the `From' field of the
+email while the whole list is entered into the `To' field. Internally, this
+value is saved in the text macro
+\cs{db@Name}.${}^{\text{\fnNameChoice}}$
+\item\NH\meta{courseName} is the course name of the class taking the quiz.
+ Internally, this value is saved in the text macro
+ \cs{db@Table}.${}^{\text{\fnNameChoice}}$
+
+\item\NH\meta{returnURL} is the {\URL} of the page the student should return
+ to after finishing the quiz. The value of \cs{rtnURL} is required when
+ the script returns an {\HTML} page, and is useful when the return is
+ {\FDF}. Internally, \cs{rtnURL} defines the text macro \cs{thisRtnURL}
+ to hold \meta{returnURL}.
+\end{description}
+
+\paragraph*{The scripts.} The \meta{submitURL} points to the server-side script that is to process the form data.
+The scripts of Table~\ref{table:QuizScripts2} were written for the upcoming book
+\AEBBook~\cite{book:AEBB} and are available on the accompanying CD-ROM. Refer the book for the details of
+implementing these scripts.
+
+\paragraph*{HTML versus FDF return.} The scripts of Table~\ref{table:QuizScripts2} are of two types:
+HTML return and FDF return. From the student's point of view, his/her
+experience is the same as the \opt{eqText} option with
+\texttt{submitAs=HTML}. In the first case, after the student has submitted
+his/her quiz, the server-side script, as sending out an email response to the
+\anglemeta{recipients}, returns an HTML page to the browser window with an
+assessment of the student's efforts on the quiz. In the second case, the
+script sends back an alert dialog box message saying the data is received and
+results are sent to the instructor (the \anglemeta{recipients}); the quiz is
+self-marking for the student to review. Details are presented in \AEBBook~\cite{book:AEBB}.
+
+
+\subsection{The \texttt{tagged} option}\label{taggedOption}
+
+When the student submits online quiz data to one of the server-side scripts,
+just prior to submission, the hidden field \cs{currQuiz.Responses} is
+populated with the student's answers. For example,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+Newton,2x,-1,-cos(x)
+\end{Verbatim}
+is how the responses field is populated, by default. This data gives no
+indication of which are correct, how many points for each question, and so
+on.
+
+To obtain more information about the quiz taken by the student and his
+responses, you can specify the \opt{tagged} option. When this
+option is taken, the quiz data is written as a ``XML-like'' string. Figure~\ref{fig:tagXML} is
+an example of the data that populates the \cs{currQuiz.Responses} field and
+which is sent to the server when the \opt{tagged} option is specified.
+
+\begin{figure}[htb]
+\begin{minipage}{5.45in}
+\begin{Verbatim}[fontsize=\small]
+<results id="Quiz1" file="quiz1.pdf" n=4>
+ <question n=1 type="text" ptype="na" points="3" credit="0" correct="1">
+ <value>Newton</value>
+ </question>
+ <question n=2 type="math" ptype="na" points="4" credit="0" correct="0">
+ <value>2x</value>
+ </question>
+ <question n=3 type="math" ptype="na" points="3" credit="0" correct="1">
+ <value>-1</value>
+ </question>
+ <question n=4 type="math" ptype="na" points="5" credit="0" correct="1">
+ <value>-cos(x)</value>
+ </question>
+</results>
+\end{Verbatim}
+\end{minipage}%
+\caption{Example of a tagged XML string}\label{fig:tagXML}
+\end{figure}
+
+Referring to Figure~\ref{fig:tagXML}, the XML string packs
+more information in it than the default string. The quiz name is
+\texttt{Quiz1}, the {\PDF} file the student used is \texttt{quiz1.pdf} and
+there are four questions (\texttt{n=4}). The first question was a text
+fill-in type, worth $3$ points, the student responded correctly. The second
+question was a math fill-in worth $4$ points, he missed this one with an
+answer of \texttt{2x}.
+
+The root element \texttt{results} contains child elements or
+nodes called \texttt{question}. Each \texttt{question} node contains
+information about one of the questions in the quiz. The \texttt{question}
+node has several attributes, these attributes are seen in
+Figure~\ref{fig:tagXML} above:
+\begin{itemize}
+ \item \texttt{n} is the question number. This is not the question
+ number the user sees, but the value of an internal counter that
+ increments each time a new question is posed.
+ \item \texttt{type} is the type of question, possible values are
+ \texttt{"text"} (text response), \texttt{"math"} (math response),
+ \texttt{"mc"} (multiple choice), \texttt{"ms"} (multiple
+ selection), \texttt{"grp"} (grouped response), and \texttt{"essay"}
+ (multi-line text response). The latter is not graded by
+ \pkg{exerquiz} but simply transmitted to the server.
+ \item \texttt{ptype} is the problem (question) type, its value is
+ normally \texttt{"na"} for `not applicable'. This attribute is used
+ to describe the question in more detail within the XML. The value
+ of \texttt{ptype} is set within the {\LaTeX} source file with
+ \cs{QT\texttt{\darg{\meta{ptype}}}} command.
+ Placement of this command is just after the \cs{item} command
+ within the \env{questions} environment.
+\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
+\item\PTs{4}\QT{limits} Compute $\lim_{n\to\infty}...$
+\end{Verbatim}
+Now, the \texttt{ptype} attribute will read \texttt{ptype="limits"}. If
+each problem is so tagged, the \texttt{ptype} attribute can be queried as
+part of larger quiz management system to view a student's effort with
+respect to all questions having the specified \texttt{ptype}. Such a system
+was never implemented, but the attribute is available.
+\item \texttt{points} is the number of points assigned to this question.
+\item \texttt{credit} is the amount of partial credit the student earned
+ for this question. Questions types where this attribute can be nonzero
+ are \texttt{"mc"}, \texttt{"ms"}, \texttt{"text"} (in response to a
+ \cs{RespBoxTxtPC} question), and \texttt{"grp"}.
+\item \texttt{correct} is normally \texttt{"0"} (a wrong answer) or
+ \texttt{"1"} (a correct answer); multiple selection (\texttt{"ms"}) and
+ grouped (\texttt{"grp"}) questions use an array of values for the
+ \texttt{correct} attribute, however. When calculating the score field
+ (\cs{ScoreField}), the problem is either right or wrong; however, the calculation
+ of the points field (\cs{PointsField}) takes into account the partial
+ credit so a problem may be partially correct.
+\end{itemize}
+
+\paragraph*{Reconstructing the quiz.} Using the XML data as well as the
+information provided by the \texttt{IdInfo} collection of fields, it is
+possible to reproduce the {\PDF} document exactly as the student submitted
+it. A demonstration file was developed for exactly this purpose and is
+available on the CD-ROM that accompanies the \AEBBook~\cite{book:AEBB}.
+The \app{Acrobat} application is required.
+
+\section{The \texttt{custom} Option}\label{customOption}
+
+This option allows a script developer to utilize the macros of the
+\pkg{eq2db} Package to prepare an {\ifusebw\AcroT\else\cAcroT\fi} document to submit
+to a custom script. Simple create a file named
+\texttt{eq2dbcus.def} and include any custom creation of fields
+you may need for your script. When you then take the \texttt{custom} option,
+\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
+\documentclass{article}
+\usepackage[designi]{web}
+\usepackage{exerquiz}
+\usepackage[custom]{eq2db}
+\end{Verbatim}
+After the command definitions of \pkg{eq2db} are read,
+\texttt{eq2dbcus.def} is input. The rest is up to you.
+
+\redpoint That's all for now! Hope you find the package
+useful. Now I really must get back my retirement. \dps
+
+\addtocontents{toc}{\protect\vspace{2ex}}
+\newpage
+\markright{References}
+
+\begin{thebibliography}{[1]}\label{references}
+\addcontentsline{toc}{section}{\protect\numberline{}References}
+
+\bibitem{book:AEBB}\hypertarget{references}{}%
+ \textsl{\AEBBook}, D. P. Story, in preparation.
+
+\end{thebibliography}
+
+\end{document}