% \iffalse
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% dljsLib.sty package,             2002-2-9            %%
%% Copyright (C) 2001-2002  D. P. Story                 %%
%%   dpstory@uakron.edu                                 %%
%%                                                      %%
%% This program can redistributed and/or modified under %%
%% the terms of the LaTeX Projet Public License         %%
%% Distributed from CTAN archives in directory          %%
%% macros/latex/base/lppl.txt; either version 1 of the  %%
%% License, or (at your option) any later version.      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%</copyright>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{dljslib}
%<package> [2002/02/09 v1.0 Manage a Library of Document Level JavaScripts (dps)]
%<*driver>
\documentclass{ltxdoc}
\usepackage[colorlinks,hyperindex]{hyperref}
\pdfstringdefDisableCommands{\let\\\textbackslash}%
\EnableCrossrefs \CodelineIndex
\begin{document}
  \GetFileInfo{dljslib.sty}
  \title{The \texttt{dljsLib} Package}
  \author{D. P. Story\\
    Email: \texttt{dpstory@uakron.edu}}
  \date{processed \today}
  \maketitle
  \tableofcontents
  \let\Email\texttt
  \DocInput{dljslib.dtx}
  \PrintIndex
\end{document}
%</driver>
% \fi
%\section{Introduction}
% This is a companion package to the \texttt{insdljs} package. \texttt{Insdljs} gives the 
% document author the ability to write document level JavaScripts to the PDF docuement, when
% it is finally built.  I personally will be writing a number of general routines to 
% handle situations that arise, and I would hope that other enthusiasts of \texttt{insdljs} will
% do the same. Therefore, it is desirable to gather together some general purpose routines into
% a single library, and have a way of selecting the desired function or functions to be used.
%
%\section{The Library Procedures}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% Define some convenience commands, \cs{dljsRegister} and \cs{DeclareAndRegister}, see comments that follow.
%    \begin{macrocode}
\newcommand\dljsRegister[2][n]
    {\expandafter\let\csname checkout@#2\endcsname=#1}
\newcommand\DeclareAndRegister[1]
    {\DeclareOption{#1}{\dljsRegister[y]{#1}}\dljsRegister{#1}}
%    \end{macrocode}
% Here we ``register'' the functions contained in the library. \cs{dljsRegister} defines a 
% control sequence that records the name of the function (actually, the option name). This
% control is set to `n'. When a package user chooses a particular function for inclusion, the
% control is set to `y'. 
%    \begin{macrocode}
\dljsRegister[y]{dljslib}
%    \end{macrocode}
% \subsection{Library Card Catalog}
% The arguments of the \cs{DeclareAndRegister} command are the options of this package, and
% their names represent JavaScript functions in the library.
%    \begin{macrocode}
\DeclareAndRegister{vectors}
\DeclareAndRegister{indefIntegral}
%    \end{macrocode}
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
% \subsection{Requirements for a Library Card}
%
% In order to check a function out of this library, you must have 
% the \texttt{insdljs} Package. The \texttt{insdljs} package itself 
% has software requirements: (1) the \texttt{verbatim} and 
% \texttt{hyperref} packages; (2) One of the fillowing, 
% \textsf{Distiller~5.0} or greater, \textsf{pdftex}, or 
% \textsf{dvipdfm}.
%
%    \begin{macrocode}
\RequirePackage{insdljs}
%    \end{macrocode}
%
% \subsection{Checkout Procedure}
%
% Functions can be checkout of the library by using the \texttt{dljslib} package
% in the usual way. For example:
%\begin{verbatim}
%\documentclass{article}
%\usepackage{amsmath}
%\usepackage[pdftex,designi]{web}
%\usepackage{exerquiz}
%\usepackage[indefIntegral]{dljslib}  % <- check out `indefIntegral'
%\end{verbatim}
% Here, we first use \texttt{exerquiz}, which has \texttt{insdljs} as a required package.
% The use of this package is not limited to users of \texttt{exerquiz}, for example, we can
% say
%\begin{verbatim}
%\documentclass{article}
%\def\mydriver{dvipdfm}
%\usepackage[\mydriver]{color}
%\usepackage[\mydriver,colorlinks,pdfpagemode=None]{hyperref}
%\usepackage[\mydriver]{insdljs}
%\usepackage[indefIntegral]{dljslib}  % <- check out `indefIntegral'
%\end{verbatim}
% However, at the time of the release of v1.0 of this package, the only functions in this
% library are ones used by \texttt{exerquiz}.
%
% \subsection{Exiting the Library with your Checkouts}
%
% This package has an output stream, \cs{dljslib@verbatim@out}, 
% that is used to write all the functions that are to be included.  
% We use a control sequence \cs{js@verbatim@out} defined in 
% \texttt{insdljs}. We also use a verbatim write from 
% \texttt{insdljs} as well, the \cs{js@verbatimwrite} environment. 
% \cs{js@verbatimwrite} writes to the output stream pointed to  
% \cs{js@verbatim@out}.
%    \begin{macrocode}
\newwrite\dljslib@verbatim@out
%    \end{macrocode}
% This package generates only one auxiliary file, 
% \texttt{dljslib.ljs}, which can be deleted after the document is 
% latexed. The file \texttt{dljslib.ljs} (\texttt{ljs} means 
% ``library javascripts'') and contains the functions that are
% specified in the package options.  At the end of this package, 
% the file \texttt{dljslib.ljs} is input back into the calling 
% document where the package \texttt{insdljs} takes over.
%    \begin{macrocode}
\immediate\openout\dljslib@verbatim@out=dljslib.ljs
%    \end{macrocode}
% \subsection{The Catalog and Checkout Mechanism}
%    \begin{macro}{library@holding}
% This is a simple environment, it reads its parameter, and if that option was specified by the
% user, it writes the function verbatim to the \texttt{dljslib.ljs}, otherwise, it comments out
% that function using the \texttt{comment} environment from the \texttt{verbatim} package.  
% This environment uses, \texttt{js@verbatimwrite}, an environment
% defined in the \texttt{insdljs} package.
%    \begin{macrocode}
\newenvironment{library@holding}[1]
{%
    \expandafter\ifx\csname checkout@#1\endcsname y%
    \let\js@verbatim@out=\dljslib@verbatim@out
    \let\dljs@verbatim=\js@verbatimwrite
    \let\enddljs@verbatim=\endjs@verbatimwrite\else
    \let\dljs@verbatim=\comment
    \let\enddljs@verbatim=\endcomment\fi\dljs@verbatim
}{\enddljs@verbatim}
%    \end{macrocode}
%    \end{macro}
%\section{The DLJS Library}
% We finaly reach the ``stacks'', the location of the actual library holdings.
%
%   \medskip\noindent This item must always accompany the collection of functions that are to be
% checked out. This is the beginning of the \texttt{insDLJS} environment. To continue this library analogy,
% this of this as the ``front wrapper'' or ``front cover'' of your library selections. It contains the 
% ``name'' of the library from which you checked out your selections.
%    \begin{macrocode}
\begin{library@holding}{dljslib}
\begin{insDLJS}[dljslib]{dljslib}{The dljs Library}
var dljslib = true;
\end{library@holding}
%    \end{macrocode}
%\subsection{The Stacks}
% Now we reach of the beginning of the stacks. There are several sections of the library, currently,
% \nameref{s:respfunctions} and \nameref{s:compfunctions}.
%
% \subsection{Response Functions}\label{s:respfunctions}
%
% \textbf{Used by Exerquiz.} In this section we catalog response functions. A response function is the one that
% \cs{RespBoxMath} calls to process the user's response to a math fill-in question. See the sample file
% \texttt{jqzspec.tex} for a detailed explanation of this type of function.
%
% \subsubsection{\texttt{vectors}}\label{vectors}
%    \begin{macro}{vectors}
% This function attempts to process questions that have vectors
% as answers. Note the name of the function is \texttt{ProcVec}, this is the name used to call it.
%\begin{verbatim}
%$\vec a + \vec b = \RespBoxMath{<4, 4, 4>}{1}{.0001}24*{ProcVec}$
%\end{verbatim}
%See also the file \texttt{jqzspec.tex} for more details.
%    \begin{macrocode}
\begin{library@holding}{vectors}
function ProcVec (flag,CorrAns,n,epsilon,a,b,indepVar,comp) {
    ok2Continue = true;
    var i, success, truthCnt=0;
    var aScalar, scalar = 1;
    var fieldname = event.target.name;
    var re =/(.*)(\*)(\s*<)/;
    var UserAns = event.value;
    CorrAns = stripWhiteSpace (CorrAns);
    UserAns = stripWhiteSpace (UserAns); // sets ok2Continue
    if ( !ProcessIt || !ok2Continue ) return null;
    if (!/<|>/.test(UserAns)) {
        app.alert("I'm looking for a vector. "
            + "You need to use proper vector notation.", 3);
        return null;
    }
    if (!CkBalP(UserAns,"<",">")) {
        app.alert("Angle brackets are not balanced.", 3);
        return null;
    }
    // see if there is a scalar multiple to the left of '<'
    if (re.test(UserAns)) {
        aScalar = re.exec(UserAns);
        scalar = aScalar[1];
        UserAns = UserAns.replace(re,"$3");
    }
    CorrAns = CorrAns.replace(/<|>/g, ""); // strip of < and >
    UserAns = UserAns.replace(/<|>/g, "");
    aUserAns = UserAns.split(",");
    aCorrAns = CorrAns.split(",");
    if (scalar != 1)
        for (i=0; i<aUserAns.length; i++)
            aUserAns[i]=""+scalar+"*"+aUserAns[i];
    if (aCorrAns.length != aUserAns.length) {
        app.alert("Incorrect number of components. The answer requires "
            + aCorrAns.length+" components.",3);
        return null
    }
    for (i=0; i<aCorrAns.length; i++) {
        aCorrAns[i] = ParseInput(aCorrAns[i]);
        if (!ok2Continue) {
            app.alert("Author Syntax error!", 3);
            return null
        }
        aUserAns[i] = ParseInput(aUserAns[i]);
        if (!ok2Continue) return null;
        aCorrAns[i] = changeToX(aCorrAns[i], indepVar);
        aUserAns[i] = changeToX(aUserAns[i], indepVar);
        success=randomPointCompare (n,a,b,epsilon,aCorrAns[i],aUserAns[i],comp)
        if ( success == null ) { 
            app.alert(\eqSyntaxErrorUndefVar,3); 
            return null; 
        }
        if (success) truthCnt +=1;
    }
    return notifyField((truthCnt == 3), flag, fieldname);
}
% This is a custom compare function for processing an indefinite integral.
\end{library@holding}
%    \end{macrocode}
%    \end{macro}
% \subsection{Compare Functions}\label{s:compfunctions}
%
% \textbf{Used by Exerquiz.}   A compare function is a JavaScript that compares the author's answer
% with the user's answer. There may be a need for compare functions other than the default one provided
% by \texttt{exerquiz}.
%
% \subsubsection{\texttt{indefIntegral}}\label{indefIntegral}
%    \begin{macro}{indefIntegral}
% The answer to an indefinite integral is nonunique; however all answers differ by a constant.
% This compare function is used with indefinite integrals. See \texttt{jqzspec.tex} for an
% example of the use of this function. Note the name of the function is \texttt{indefCompare}, this
% is the name you use to call the function. An example of usage of this function can be found in
% the sample file \texttt{jslib\_ex.tex} that comes with the Acro\TeX{} Bundle; from that file we
% have:
%\begin{verbatim}
%$\displaystyle\int\sin(x)\,dx = 
%    \RespBoxMath{-cos(x)}[intSin]{4}{.0001}01[indefCompare]$
%\end{verbatim}
% See also the file \texttt{jqzspec.tex} for more details.
%    \begin{macrocode}
\begin{library@holding}{indefIntegral}
function indefCompare(_a,_b,_c,_F,_G) {
    var eqC, eqx;
    with(Math) {
        eqx = _a;
% var C = 0 is used to designate an arbitrary constant        
        var C = 0;         
%</package>        
%<assumeAcroV>try {
%<*package>
        if (isNaN(eqC = eval(_F)-eval(_G))) return -1;
%</package>
%<assumeAcroV>} catch(e) { return null; }
%<*package>
        eqx = _c;
        _F = eval(_F);
%</package>
%<assumeAcroV>try {
%<*package>
        if(isNaN(_G = eval(_G))) return -1;
%</package>
%<assumeAcroV>} catch(e) { return null; }
%<*package>
        return abs( _F - _G - eqC );
    }
}
\end{library@holding}
%    \end{macrocode}
%    \end{macro}
% Finally, we have the ``back wrapper'' or ``back cover'' of the selected materials. We close the
% \texttt{insDLJS} environment
%    \begin{macrocode}
\begin{library@holding}{dljslib}
\end{insDLJS}
\end{library@holding}
%    \end{macrocode}
% \section{Out the Door and Close it behind you}
%    \begin{macrocode}
\immediate\closeout\dljslib@verbatim@out
%    \end{macrocode}
% \section{Back Home with your Selections}
%    \begin{macrocode}
\input{dljslib.ljs}
%</package>
%    \end{macrocode}
\endinput