Return to s-general.tex CVS log

Up to [LON-CAPA] / capa / capa51 / Manual

- added the manual

% \capa\ grammar and functions
\hrule 
% \vskip 0.2in
\section{Specification of \capa{} Problem Sets}
% {{\noindent \bf \it \LARGE Section 5: Specification of \capa\ Problem Sets}}
% \vskip 0.2in
\noindent This Section describes the \capa\ grammar and syntax. Examples show
how to code problems and create problem sets.
\vskip 0.2in
\hrule

%\begin{enumerate}
%\item 
\subsection{\bf General Description.}
The source code for the problems to be solved by  students are
contained 
in files labeled {\bf set{\em x}.qz} where {\bf {\em x}} is the problem set
number.  These files contain all the information 
needed for each problem as well as the information for the printed hard copy,
the computer-screen presentations, and the web
display of the problem set.  
In the simplest case, one might imagine that the file contains just the text to
specify the problems for the students.  
However, each paper is individualized and must contain variable information such
as the student's name, the due-date of the set, etc. 

 \capa\ uses the {\tt /DIS()} command to display functions, variables, or
 anything that has been evaluated and must be  
 inserted in the text when the output is generated.  \capa\ uses other special
 commands at the beginning of a line.  For 
 example: {\tt /LET} defines a variable.  {\tt /IMP} imports a file into the
 {\tt .qz} file.  {\tt /HIN} defines a hint which is 
 available for viewing by the student after the student has entered an incorrect
 answer.  {\tt /ANS()} defines the answer to 
 the problem. Note the UPPER CASE used for the commands. The {\tt //} is used
 for lines that are comments and will not be evaluated 
 or inserted into the text or displayed to the students.  The grammar for
 writing problem sets with some examples is given in the following section.
%
%\item 
\subsection{\bf \LaTeX\ and ASCII in \capa\ problems.}
%
 A complete but plain problem set can be written using only ASCII
characters.  In this case the printed version and 
the version displayed on the {\tt VT100} terminal will be \underline{exactly}
the same.  However, we have found that high 
quality printed problem sets can be readily produced by the \capa\ system with
\LaTeX . Thus, an important and sometimes 
confusing aspect of the set{\em x}.qz files is  the \LaTeX\ commands to control
the presentation of the problem. 
Greek characters, postscript figures, subscripts and superscripts must be
imbedded in the problem set text 
but cannot be displayed on the {\tt VT100} terminal window during interactive
logins.  Using the {\bf tex()} function it is
 possible to specify a \LaTeX\ 
version and an ASCII version of a particular string of characters.  For example,
{\bf $\Delta$H} could appear on paper whereas 
only {\tt delta-H} can be shown on the screen (using ASCII characters).  The
general form of the function to be evaluated  
 is {\small tex("TeX","ASCii")}. For example:
\begingroup\small\begin{verbatim}/DIS(tex("$\Delta$H","delta-H"))\end{verbatim}
\endgroup
would be used in the set{\em x}.qz file to display $\Delta$H on the printed
paper.  The first argument is put into the \TeX\ 
version and the second into the ASCII version.  Note that the {\tt /DIS()}
command, mentioned above is used to evaluate an 
expression amid text.
%
%\item 
\subsection{\bf html in \capa\ problems.}
%
\noindent There are two functions available for specifically entering html code
into your problem sets to improve the Web display of the problem set over that of ASCII text.  If you do not specify
html code, then the ASCII code will be displayed on the web document.  The first
html specific function is the {\tt web()}
function which has similar usage to the {\tt tex()}function.  The {\tt web()}
function has three fields for entry.  They are:\\
{\tt web("ASCII","\TeX\ ","html")}.  The second function, {\tt html()}, can
include anchors, links, or text
to be displayed only on the web document.  An example of the use of
this function is:\\
/DIS({\tt html("<br><img src=/teacher/nsc111f7/pictures/Ball.gif>")})
%
\subsection{{\tt capa.config} File}
A file called \index{capa.config}{\tt capa.config} located in the class directory contains 
general configuration informations of the \capa\ system. 
It is divided into sections 
containing configurable parameters that 
instructors can customize the \capa\ system. 
The first section contains informations related to 
the organization of a class, such as \index{exam\_path}exam\_path, 
\index{quiz\_path}quiz\_path, \index{supp\_path}supp\_path, 
and \index{others\_path}others\_path.

\begin{capacode}
exam_path   = /usr/users/teacher/CAPA45/xph183f7
quiz_path   = /usr/users/teacher/CAPA45/qph183f7
supp_path   = /usr/users/teacher/CAPA45/rph183f7
others_path = /usr/users/teacher/CAPA45/fci183f7
\end{capacode}

These four class path parameters are the full path information 
that lead to the classes where the exam scores, 
quizz scores, supplementary exercises scores, and others scores are located.
Together with the homework class where this capa.config file is located, 
the score statistics can then be combined from all these
different directories and form a single result. 

The second section specifies the full path to commands 
that are used by the \capa\ system,
such as `latex', `dvips', `mail', `allcapaid', and `qzparse'.

\begin{capacode}
latex_command   =  "latex"
dvips_command   =  "dvips"
mail_command     =  "/usr/bin/mailx"
allcapaid_command  =  "/usr/users/capadvt/CAPA_SRC/5.0/Teachertools/allcapaid"
qzparse_command =  "/nfs/capa1/capadvt/CAPA_SRC/5.0/pProj/Linux/qzparse"
\end{capacode}

The next section has the options and identifies the printers to use when 
the system prints a postscript file. 
Each line of \index{printer\_option} printer\_option specifies a printer name  
selected for \texttt{capautilscapautils} to print problem set(s) for 
a student.

The command used to print when a user selects one sided or 
two sided printing is given by the two command options:
\index{lprOneSided\_command}lprOneSided\_command, and 
\index{lprTwoSided\_command}lprTwoSided\_command.

\begin{capacode}
printer_option  = "cyccap_capa1"
printer_option  = "cyccap_capa2"
printer_option  = "west_post"
printer_option  = "west_post2"

lprOneSided_command  =  "/usr/bin/lpr -P$Printer_selected"
lprTwoSided_command  =  "/usr/bin/lpspr -K2 $PS_file | /usr/bin/lpr -P$Printer_selected"
\end{capacode}

The fourth section specifies options for capalogin, 
such as the time the goodbye message stayed on the screen 
after student exits capalogin, which is 
given in seconds in parameter \index{capalogin\_goodbye\_delay}
capalogin\_goodbye\_delay.
The time interval when capalogin consider the student is 
in-active from the \index{capalogin\_inactivity\_delay}capalogin\_inactivity\_delay.

\index{capalogin\_show\_summary\_score}capalogin\_show\_summary\_score.
\begin{capacode}
capalogin_goodbye_delay  = 6     
# specify the capalogin inactivity delay time in minutes
# default value is 60 minutes, 0 means never time out
capalogin_inactivity_delay  = 35
# if set to none, don't show the summary score, any other value
# or not defined show the score
capalogin_show_summary_score = none
\end{capacode}

Another section is related to an option in X-windows Quizzer. 
By pressing the ``Std. Header'' button the following is written
in the set$x$.qz file. 

\begin{capacode}
BeginStandardQuizzerHeader 
//CAPA system software is copyrighted by Michigan State University.
//By using these materials, the User agrees to:
//1) Protect the source code files  from unauthorized copying.
//2) Limit  access  of the source material to teaching staff.
//3) The User is free to mix, cut and paste, modify, adapt, delete,
//   improve, etc. the problems and graphics for his/her own use.
//
/IMP "/demolibrary/Tools/StdMacros"
/IMP "/demolibrary/Tools/StdUnits"
/IMP "/demolibrary/Tools/StdConst"
/IMP "HWTop"
EndStandardQuizzerHeader
\end{capacode}

Everything that appears between the keywords
BeginStandardQuizzerHeader
EnStandardQuizzerHeader
is entered into the current .qz file when this button is pressed.

\subsection{{\tt capautils.config} File}

This first section contains informati0ns used by capautils. The file is self-explanatory bu the comments below can also help.
 
\index{homework\_scores\_limit\_set} homework\_scores\_limit\_set,
\index{exam\_scores\_limit\_set}exam\_scores\_limit\_set,
\index{quiz\_scores\_limit\_set}quiz\_scores\_limit\_set,
\index{supp\_scores\_limit\_set}supp\_scores\_limit\_set, and
\index{others\_scores\_limit\_set}others\_scores\_limit\_set.
These parameters specify the maximal number of problem sets 
that are used to calculated the scores from homework, exam, quizz, supplemental and 
others directories.

The  file name to store all scores of students in the classl file 
and is used to send out email is specified in parameter
\index{master\_scores\_file}master\_scores\_file.
The parameter \index{email\_template\_file}email\_template\_file
specifies the template file for email.

\begin{capacode}
homework_scores_limit_set = 12
exam_scores_limit_set     = 7
quiz_scores_limit_set     = 16
supp_scores_limit_set     = 14
others_scores_limit_set   = 0
master_scores_file = "/usr/users/teacher/CAPA45/phy183f7/scores/scores.all"
# The template file for e-mail
email_template_file = "/usr/users/teacher/CAPA45/phy183f7/scores/email.template"
\end{capacode}

The second section contains definitions used by capautils. 
It first declare a series of variable names to be used 
to store the scores and maximum scores for homework, quizz, and
exam. 


\begin{capacode}
# pre-defined variable names that can be used in email.template
#
# Declare a variable name with ':=' 
#  when assigning a value to a variable, use '='
# This variable is used to store the total scores 
#    calculated from all setX.db's in the regular class
# It is later refered in the file 'email.template' as $HWtotal_scp
var_homework_total_score   := HWtotal_scp
# This variable is used to represent the total possible scores 
#    that a student could receive from all setX.db's in the regular class
# It is later refered in the file 'email.template' as $HWtotal_max_scp
var_homework_total_max     := HWtotal_max_scp
# This variable is used to represent the total scores 
#    calculated from all setX.db's in the class specified
#    by 'quiz_path' parameter in this file
# It is later refered in the file 'email.template' as $QZtotal_scp
var_quiz_total_score     := QZtotal_scp
# This variable is used to represent the total scores 
#    calculated from all setX.db's in the class specified
#    by 'quiz_path' parameter in this file
# It is later refered in the file 'email.template' as $QZtotal_max_scp
var_quiz_total_max        := QZtotal_max_scp
# This variable is used to represent the total number of 
#    setX.db's in the class specified by 'quiz_path' parameter in this file
# It is later refered in the file 'email.template' as $QZcount_scp
var_quiz_count            := QZcount_scp
# This variable is used to represent the total number of '-'
#    a student got in the term summary report. It represents that
#    the number of times the student is abscent from all the setX.db's 
#    in the class specified by 'quiz_path' parameter in this file
# It is not yet used in the file 'email.template,' but 
#    can be refered as $QZabsent_scp
var_quiz_absent           := QZabsent_scp
# This variable will return a one line string in the form 
#   xxx/xxx xxx/xxx xxx/xxx xxx/xxx xxx/xxx xxx/xxx
#  It gives the statistics for each set in the class specified by
#  'quiz_path' parameter in this file
# It is later refered in the file 'email.template' as $QZsummary
var_quiz_summary_string   := QZsummary
\end{capacode}




\begin{capacode}
#
# Declares a class of variables with the same prefix
#  This declaration allows the access of individual set scores 
#  in the class specified by 'exam_path' parameter in this file
#  
prefix_exam_raw_scores     := exam_raw
# Thus, exam_raw1, exam_raw2, exam_raw3, exam_raw4 ... 
#  represent the individual set score
# These variables are used in the later definition of midterm1, midterm2, ...
# 
prefix_exam_raw_max        := exam_raw_max
# similar to the above, now the maximum scores for exam 1 is stored 
#  in variable exam_raw_max1
# These variables are used in the later definition of midterm1, midterm2, ...

# This parameter is used in calculation of corrected credits by 
#  successive corrections of their midterm exams
correction_factor = 0.3
# Correction formula for midterm exams
#   here midterm1, midterm2, midterm3, and final_exam 
#   are new variables whose definition depends on
#   the raw scores of each set in the class specified by 'exam_path'
\end{capacode}

The eighth section defines how the values of variable
midterm1, midterm2, midterm3 are calculated from
exam\_raw1, exam\_raw2 and exam\_raw3 and correction\_factor. 
These are all in perl code format. The first definition describes how the
value of midterm1 is calculated from exam\_raw1, exam\_raw2, and 
correction\_factor. 
The next definition is for midterm2 and the third definition is for midterm3. 


\begin{capacode}
### The reason that we define midterm1, midterm2, midterm3 and final_exam here
###  is that score report file need these definitions.
midterm1   ::

BEGIN_perl

  local($tmp);
  if($exam_raw2 >= $exam_raw1) {
    $tmp = $exam_raw1 + $correction_factor*($exam_raw2-$exam_raw1);
  } else {
    $tmp = $exam_raw1;
  }
  return ($tmp);

END_perl


midterm2   ::

BEGIN_perl

  local($tmp);
  if($exam_raw4 >= $exam_raw3) {
    $tmp = $exam_raw3 + $correction_factor*($exam_raw4-$exam_raw3);
  } else {
    $tmp = $exam_raw3;
  }
  return ($tmp);

END_perl


midterm3   ::
BEGIN_perl

  local($tmp);
  if($exam_raw6 >= $exam_raw5) {
    $tmp = $exam_raw5 + $correction_factor*($exam_raw6-$exam_raw5);
  } else {
    $tmp = $exam_raw5;
  }
  return ($tmp);

END_perl

\end{capacode}


The last section is related to \index{units}units specifications. 
This section is further divided into three subsections. The first is 
the definition of base units. 
It begins with the special marker ``\verb"<< Base Unit >>".''
Each line contains a definition of a base units, it begins with 
a full name, a symbol represents that base units, and a comment begins with a `\verb"#"'
character. These three fields are separacted by white spaces and 
all three fields are required. 
The number of characters in a full name description 
should not exceed 47 characters and there should not contain any 
space or tab characters in the full name description. 
The number of characters denoting a symbol is limited to 15 characters. 
There could be at most 32 base units defined in this subsection.

\begin{capacode}
<< Base Unit >>
meter           m      # length
kilogram        kg     # mass
second          s      # time
ampere          A      # electric current
kelvin          K      # thermodynamic temperature
mole            mol    # amount of substance
candela         cd     # luminous intensity
\end{capacode}
The next subsection of units is the definition of prefix symbols. 
It is consists of three fields on each line, separated by 
white spaces or tab characters. 
The length of the full name is not limited to any number of characters, 
however, it cannot contain any while space or tab character. 
The symbol character contains only one character. 
The actual power the character represents is 
shown in the third field.
There could be as many as 52 definitions of the prefix symbol, 
one for each alphabet from a to z and A to Z. 
\begin{capacode}
<< Prefix >>
yotta            Y         10^{24}
zetta            Z         10^{21}
exa              E         10^{18}
peta             P         10^{15}
tera             T         10^{12}
giga             G         10^9
mega             M         10^6
kilo             k         10^3
hecto            h         10^2
deci             d         10^-1
centi            c         10^-2
milli            m         10^-3
micro            u         10^-6
nano             n         10^-9
pico             p         10^{-12}
femto            f         10^{-15}
atto             a         10^{-18}
zepto            z         10^{-21}
yocto            y         10^{-24}
\end{capacode}
The third subsection of units is the definition of derived units. 
It is consists of four fields on each line, all four fields are 
required. 
The first field is a one-word name for the units defined 
in that row, the number of characters is at maximal 47. 
The second field is the symbol denoting the units, 15 characters is the maximum.
The first and the second fields are separated by spaces, 
no space is allowed within the name field and the symbol field. 
The third field is the way the units is calculated from base units or other 
previously defined derived units.
Operations that could be used in this field are
``*'' (multiplication),`` '' (multiplication), ``/'' (division), and
``\verb"^"'' (integeral power). 
Number can be entered in floating point format (0.001) or 
exponential form (1.77185E-3). 
Operations ``\verb"+"'' (plus) and ``\verb"-"'' (minus) are not allowed. 
The fourth field begins with a `\verb"#"' mark is the comment for this units. 

\begin{capacode}
<<Derived Unit>>
gram            g      0.001 kg      # mass
hour            hr     3600. s       # time
pound           lb     0.45359237 kg # mass
ounce           oz     1.77185E-3 kg # mass
inch            in     2.54 cm       # length
foot            ft     12 in         # length
mile            mi     5280 ft       # length
yard            yd     0.9144 m      # length
nautical_mile   n_mi   6080 ft       # length, nautical mile (UK)
rood            rood   1210 yd^2     # area, rood
acre            acre   4840 yd^2     # area, acre
hertz           Hz     1/s           # frequency
litre           L      10^3/cm^3     # volume
newton          N      m*kg/s^2      # force
pound_force     lbf    4.44822 N     # force
dyne            dyn    1E-5 N        # force
pascal          Pa     N/m^2           # pressure, stress
bar             bar    1E5 Pa          # pressure
mmHg            mmHg   1.33322E2 Pa    # pressure, millimeter of mercury
torr            torr   1 mmHg          # pressure
atm             atm    760 torr        # standard atmosphere
joule           J      N*m             # energy, work, heat
electronvolt    eV     1.6021892E-19 J # energy
calorie         cal    4.1868 J        # energy
Btu             Btu    1.05506E3 J     # energy
watt            W      J/s             # power, radiant flux
coulomb         C      A*s             # electric charge
volt            V      J/C           # electric potential, electromotive force
ohm             Ohm    V/A           # electric resistance
siemens         S      1/Ohm         # electric conductance
farad           F      C/V           # electric capacitance
tesla           T      V s/m^2       # magnetic flux density
weber           Wb     V*s           # magnetic flux
henry           H      V*s/A         # inductance
radian          rad    m /m            # plane angle
degree          deg    1.745329E-2 rad # plane angle (Pi rad=180 deg)
steradian       sr     m^2 /m^2        # solid angle
lumen           lm     cd*sr         # luminous flux
lux             lx     cd*sr/m^2     # illuminance
becquerel       Bq     1/s           # activity (radioactive)
gray            Gy     J/kg          # absorbed dose (of radiation)
sievert         Sv     J/kg          # dose equivalent (dose equivalent index)
astroUnit       AU     1.49598E11 m  # mean distance earth to sun
\end{capacode}

The rule for matching a units is 
that the process begins with derived and base units first. 
Such as `T' will be matched against ``tesla'' instead of been considered as 
prefix `T'. Another example is that
``min'' will be matching ``minutes'' instead of treated  
as combination of prefix `m' and 
units `in'. 




%\item
\subsection{\bf Grammar Specifications}
\begin{itemize}
\item  The end-of-line character (produced by the {\em Return} key) plays a
critical role in the {\tt set$x$.qz} files.  It is 
used to signify the end of text and mathematical expressions.  Since single
end-of-line characters are ignored by \LaTeX,  
careful usage of the {\em Return} key can be used to format the ASCII output. 
Because the {\tt quizzer}  display automatically 
line-wraps the text input, it is important to check  
the ASCII display before distributing a problem set. The best method is to log
in just as a student would.
%
\item   It is convenient to begin the question file, set{\em x}.qz  with
commands such as {\tt /IMP "HWTop"} 
and  {\tt /IMP "../Tools/StdMacros"}. These  commands `import' a header to
display the student's name, the course name, 
as well as macros for often used   commands and instructions.  The questions
with their coded answers (and appropriate hints, 
comments and explanations if desired) follow.   {\tt /END} command and a
carriage return signify the end of the entire set. It is
recommended that each type of problem for a specific field of study be
classified and kept in individual ASCII files.  This way
an entire problem set can be generated by using commands similar to {\tt /IMP
"../ProblemLibrary/type04/prob3"}.
%
\item  Note that there are also two auxiliary files with commands for formatting
the \LaTeX\ 2.09 document called {\tt TeXheader}
 and {\tt Texfooter}.  These are  automatically included by {\tt quizzer} at the
 top and bottom of the {\tt
 quiztemp.tex} file 
 before the {\tt quiztemp.dvi} file is created.
%
The {\tt TeXheader} file used at MSU creates a high density two-column format
for the problem sets. This file is contained in 
the {\tt nsc111f7} directory and is shown below:\\ 
%
%\begingroup\small 
\begin{capacode}
\documentstyle[twocolumn,epsf]{article}
\textheight 25.9cm  
\oddsidemargin = -0.42in
\evensidemargin = -0.42in
\textwidth= 7.28in  
\begin{document}
\voffset=-4.1cm
\setcounter{page}{1}
\newcommand{\\capa\}{{\sl C\kern-.10em\raise-.00ex\hbox{\rm A}\kern-.22em%
{\sl P}\kern-.14em\kern-.01em{\rm A}}}
\newenvironment{choicelist}{\begin{list}{}{\setlength{\rightmargin}{0in}
\setlength{\leftmargin}{0.13in}\setlength{\topsep}{0.05in}\setlength{\item
 sep}{0.022in}\setlength{\parsep}{0in}\setlength{\belowdisplayskip}{0.04in}
\setlength{\abovedisplayskip}{0.05in}\setlength{\abovedisplayshortskip}
{-0.04in}\setlength{\belowdisplayshortskip}{0.04in}}}{\end{list}}
\end{capacode}
%\endgroup
%
\item  The \index{HWTop}{\tt HWTop} file should be at the top of each problem set. It
includes the student name, section number, class title, 
assignment number, due date, and student's CAPA ID for the assignment. 
%
\item  The actual {\tt HWTop} file information used in {\tt nsc111f7} is shown
below, together with a magnified example  
of the resulting output. Note: In the actual set, the carriage returns are
omitted from the header information.
\newpage
% \vskip 0.1in
% \hrule
% \scriptsize
% \begin{verbatim}
% /DIS(tex("\noindent{\large\bf ",""))/DIS(tex(name(),""))/DIS(tex("\hfill Section
% {\Large ",""))
% /DIS(tex(section(),""))/DIS(tex("}}\\","")) /DIS(tex("\vskip -.1in",""))
% /DIS(tex("\noindent {\large \it Natural Science 111-- \hfill  Set
% ",""))/DIS(tex(set(),""))
% /DIS(tex("}\\ \vskip -.16in",""))   /DIS(tex("\noindent{\bf
% ",""))/DIS(tex(class(),""))
% /DIS(tex("} -- MSU -- 1995.  Due ",""))/DIS(tex(due_date(),"")) /DIS(tex("CAPA
% ID is",""))
% /DIS(tex("{\footnotesize  ",""))/DIS(tex(capa_id(),""))/DIS(tex("}",""))
%  /DIS(tex("\vskip .1in \pagestyle{empty} ",""))
% //
% /LET stdendline=tex("\vskip .05in \hrule width3.55in height0.6pt \hfill \vskip
% -.07in \noindent 
% {\tiny Dept. of Physics and Astronomy, Michigan State University  \dotfill 
% {CAPA\copyright msu}}","")
% \end{verbatim}
\footnotesize{
\begin{capacode}
/LET nameforTeX = name()
/LET due_dateforTeX = due_date()
/LET PINforTeX = capa_id()
/LET sectionforTeX = section()
/LET setforTeX=set()
/LET classforTeX=class()
//
/DIS(tex("\noindent{\large\bf ",""))/DIS(var_in_tex(nameforTeX))
/DIS(tex("\hfill Section {\Large ",""))/DIS(var_in_tex(sectionforTeX))
/DIS(tex("}}\\","")) /DIS(tex("\vskip -.1in","")) 
/DIS(tex("\noindent {\large \it Sample \capa Questions \hfill  Set ",""))
/DIS(var_in_tex(setforTeX))/DIS(tex("}\\ \vskip -.16in",""))   
/DIS(tex("\noindent{\bf ",""))
/DIS(var_in_tex(classforTeX))/DIS(tex("} -- MSU --  Various Dates.  Due ",""))
/DIS(var_in_tex(due_dateforTeX)) /DIS(tex("CAPA ID is",""))
/DIS(tex("{\footnotesize  ",""))/DIS(var_in_tex(PINforTeX))/DIS(tex("}","")) 
/DIS(tex("\vskip .1in \pagestyle{empty} ",""))
//
//
/LET DeptID="College of Natural Science, Michigan State University"
/LET stdendlineA=web("", \
  "\vskip .05in\hrule width3.55in height .6pt\
  \hfill\vskip -.07in\noindent{\tiny ", \
  "<Font color=\"gray\"><font size =-1><i> --- ")
/LET stdendlineB=web("", \
  " \dotfill  {CAPA\copyright msu}}", \
  " --- </font><font size=-2>CAPA &#169</font><font=-1> msu</i></font> \
   <font color=\"black\"")
/LET stdendline=stdendlineA+DeptID+stdendlineB
\end{capacode}
}
% \hrule
\normalsize
% \vskip .2 in
\item  These lines contain \LaTeX\ commands for alignment and font
specification.  They use arguments in the {\tt tex()} function for
\LaTeX\ which are not displayed in the ASCII  or Web versions.  The functions
print the Student Name, section number, problem set
number, due date and CAPA ID.  
\item  The  \LaTeX\ source document created from  {\tt TeXheader} and {\tt
HWTop}, i.e., the first lines in the file 
{\tt quiztemp.tex} file follow: (again, some carriage returns have been added) 
% \vskip 0.1 in
% \hrule \begingroup
% \footnotesize
% \begin{verbatim}
% \documentstyle[twocolumn,epsf]{article}
% \textheight 25.9cm  
% \oddsidemargin = -0.42in
% \evensidemargin = -0.42in
% \textwidth= 7.28in  
% \begin{document}
% \voffset=-4.1cm
% \setcounter{page}{1}
% \newcommand{\\capa\}{{\sl C\kern-.10em\raise-.00ex\hbox{\rm A}\kern-.22em%
%   {\sl P}\kern-.14em\kern-.01em{\rm A}}}
% \newenvironment{choicelist}{\begin{list}{}{\setlength{\rightmargin}{0in}
% \setlength{\leftmargin}{0.13in}\setlength{\topsep}{0.05in}\setlength
% {\itemsep}{0.022in}\setlength{\parsep}{0in}\setlength{\belowdisplayskip}
% {0.04in}\setlength{\abovedisplayskip}{0.05in}\setlength
% {\abovedisplayshortskip}{-0.04in}\setlength{\belowdisplayshortskip}{0.04in}}}
% {\end{list}}\noindent{\large\bf Student, Jamie                \hfill Section
%  {\Large 1}}\\ \vskip -.1in \noindent {\large \it \capa\ Natural Science--
%  \hfill
%   Set 1}\\ \vskip -.16in   \noindent{\bf nsc111f7} -- MSU -- 1995.  Due Sun,
% Sep  1, 1996 at 08:00. CAPA ID is {\footnotesize  8755} \vskip .1in 
% \pagestyle{empty} 
% \end{verbatim}
% \endgroup
\footnotesize{
\begin{capacode}
\documentstyle[twocolumn,epsf]{article}
\textheight 25.9cm  
\oddsidemargin = -0.42in
\evensidemargin = -0.42in
\textwidth= 7.28in  
\begin{document}
\voffset=-4.1cm
\setcounter{page}{1}
\newcommand{\capa}{{\sl C\kern-.10em\raise-.00ex\hbox{\rm A}\kern-.22em%
  {\sl P}\kern-.14em\kern-.01em{\rm A}}}
\newenvironment{choicelist}{\begin{list}{}{\setlength{\rightmargin}{0in}
\setlength{\leftmargin}{0.13in}\setlength{\topsep}{0.05in}
\setlength{\itemsep}{0.022in}
\setlength{\parsep}{0in}\setlength{\belowdisplayskip}{0.04in}
\setlength{\abovedisplayskip}{0.05in}
\setlength{\abovedisplayshortskip}{-0.04in}
\setlength{\belowdisplayshortskip}{0.04in}}}{\end{list}}


\noindent{\large\bf Student, Jamie .\hfill Section {\Large 1}}\\
\vskip -.1in \noindent 
{\large \it Sample \capa Questions \hfill  Set 1}\\
\vskip -.16in   \noindent{\bf nsc111f7} 
-- MSU --  Various Dates.  Due Fri, May 15, 1998 at 08:00 CAPA ID is 
{\footnotesize  5743}
 \vskip .1in \pagestyle{empty} 
\end{capacode}
}
% \hrule 
% \vskip 0.1 in
\normalsize\noindent 
Note that all of the \capa\ functions have been evaluated
before the file is written.  
\item  The result from Latex and dvips processing is a student copy which looks
like:
\begin{center}
\parbox[t]{3.8in}{
\noindent {\hrule \vskip 0.2 in \noindent{\large\bf Student, Jamie              
 \hfill Section {\Large 1}}\\ \vskip -.1in 
\noindent {\large \it \capa\ Natural Science-- \hfill  Set 1}\\ \vskip -.16in  
\noindent{\bf nsc111f7} -- MSU -- 1995.  
Due Sun, Sep  1, 1996 at 08:00. CAPA ID is {\footnotesize  8755} \vskip .1in
\hrule}}
\end{center}
\normalsize
\item  The remainder of the set{\em x}.qz file contains the questions. Each
question typically consists of a block of 
variable definitions, the text for the question including evaluation  of
imbedded data, the coding of the answer, and 
optionally, a comment, a hint and an explanation. 
\vskip 0.2in
\end{itemize}
%\item 
\subsection{Example}
{\bf Example 1.} A complete example of a very simple \capa\ problem is
given below:
% \vskip 0.1in
% \hrule
% \footnotesize
\begin{capacode}
//************************************** 
/BEG prob_val=2
/IMP "../Tools/Problem#" 
// By S. Wolfe, wolfe@nscl.msu.edu, No commercial use.
/HIN Summing is the same as Addition.
/EXP Add the two numbers and enter the result.
//
/LET firstnumber=random(1,5,1)
/LET secondnumber=random(2,10,2)
//
Find the sum of /DIS(firstnumber) plus /DIS(secondnumber). 
//
/LET sum=firstnumber+secondnumber
/ANS(sum,tol=0.01,wgt=prob_val,tries=10)
/DIS(stdline)
//**************************************
\end{capacode}

% \normalsize
% \noindent 
The printed output for a specific student appears as:
% \vskip 0.1in
% \hrule

{\bf 1. [2pt]} Find the sum of 3 plus 8.\\ 
\vskip .05in \hrule width2in height0.6pt \hfill \vskip .02in

\begin{itemize}
\item  Each of the lines in this example is terminated with a carriage return
end-of-line character, even though it is not 
visible here.  
\item The  {\tt /BEG prob\_val=2} begins the problem and sets the weight of the
problem to 2 points. (The weight must be an integer from 1 to 9.) [Note: \verb"/BEG"
is the same as \verb"/LET"]
\item The {\tt /IMP "../Tools/Problem\#"} function is used to print the problem
number and the weight of the problem with a 
bold font.
\item  All lines that start with double-slashes, {\tt //}, are comment lines and
only appear in the \mbox{set{\em x}.qz} file.  
For example, the comment lines of stars are used to visually separate problems so that they
can be identified easily.  As in any computer 
code, comments play an important role in documentation and  ``self-documenting''
variable names are helpful.  
\item  The line beginning with {\tt /HIN}  contains an optional hint, i.e., it
is up to the instructor whether to include such 
a hint for the students on a particular problem.  If a hint has been coded into
a problem, the student can `request' to view the
 hint after attempting to answer the question.  
\item  The line beginning with {\tt /EXP} is the explanation.  The explanation
becomes available to the students after data 
entry to the problem set is `closed.' (Explanations and Hints are  included at
the discretion of the 
instructor). 
\item  The  lines beginning with {\tt /LET} are definitions of the variables
needed for this problem.  {\tt firstnumber}, is 
declared to be a random integer in the range of 1 to 5 in steps of 1, similarly,
{\tt secondnumber} is an integer in the range 
of 2 to 10 in steps of 2.  \capa\ displays real and integer variables
differently. It is preferable not to mix integer and 
real numbers. Within functions such as {\tt random()} they must not be mixed.
\item  Next, we have the text of the problem that will be contained in the
printed problem set and shown on the computer 
screen.  Note that the {\tt /DIS()} command around a previously declared
variable tells the computer to display its value.  
If the variable is not defined prior to diplaying, an
error message will be displayed.  
\item  The {\tt /LET sum =..} declares that the variable {\tt sum} is the sum of
the two random numbers. This is the answer to 
the problem and we use an appropriate variable name.  (The name of the answer,
here {\tt sum}, is up to the author.)  
\item  Finally, the answer to the problem is declared using the {\tt /ANS()}
command. The line with the answer should come 
literally at the end of all the material for a problem. See Section 6 for
explanations of the arguments of the {\tt /ANS()} function.\\
\end{itemize}
%
%\vskip 0.10 in
%\item
\subsection{\bf Example 2. Using the choose() function}
 The {\tt choose()} function can be used to select among choices or to correlate
 variables with pictures or graphs. ({\small Note: there should be NO
carriage return in the choose line. In general, try
to minimize carriage returns as they use up the limited number of lines
available as screen display on the vt100 terminals}). In this example the
computer selects a random number in the range of 1 to 14 and then constructs a
filename to be displayed and the correlated answer.  
\vskip 0.1in 
\hrule
%
\scriptsize \begin{verbatim}
//************************************** 
/BEG prob_val=1
/IMP "../Tools/Problem#" 
//By E. Kashy, kashy@nscl.msu.edu, No commercial  use
/LET k=random(1,14,1)
/LET file=choose(k,"35","45","56","62","77","86","93","m26","m39","m47","m51","m66","m74","m84")
/LET ans5=choose(k, 3.5,4.5,5.6,6.2,7.7,8.6,9.3,-2.6,-3.9,-4.7,-5.1,-6.6,-7.4,-8.4)
The graph shows the function /DIS(tex("\\ \centerline{$Y=a x$} ","Y=ax. "))
Make a careful determination of the value of /DIS(tex("$a$","a")).
/DIS(tex("\epsfxsize=3.6in \epsffile{/usr/users/teacher/CAPA45/nsc111f7/pictures/Y",""))
/DIS(var_in_tex(file))/DIS(tex("x.ps}",""))
/DIS( html("<IMG SRC=/nsc111f7/pictures/Y"))/DIS(html(file))/DIS(html("x.gif >") )
/ANS(ans5:2E,tol=5%,wgt=prob_val,tries=10)
/DIS(stdline)
//**************************************
\end{verbatim}

\normalsize
\noindent The output on paper would look like (see next page):
\clearpage
\hrule
{\bf 2.}[1pt] The graph below represents the function $$Y=a x$$ Make a careful
determination of the value of $a$\\ 
\centerline{\epsfxsize=3.8in\epsffile{pictures/Y3p5x.ps}}
\vskip .05in \hrule width2in height0.6pt \hfill \vskip .02in
%
\begin{itemize}
\item  The computer code picks a random number, {\tt k}, and the {\tt choose}
function selects the string variable, ``35", that 
will be included in the name of the {\tt .eps} or \texttt{.gif} file to be displayed.  The choose
function contains the selection index as its 
first argument and the choices as the remaining arguments. 
\item   It is important to check that the number of choices corresponds exactly
to the maximum number of the selection index.  
Otherwise an error will occur whenever the index (randomly) lies outside the
range of choices. An `Out of bounds' error message 
is displayed.
\item   The answer is also specified with a {\tt choose()} function using the
same selection index.  
\item  The author of the problem must be sure that the data in the first {\tt
choose()} function corresponds to the answers 
in the second {\tt choose()} function.  
\end{itemize}
\vskip 0.2in
%\item 
\subsection{\bf Example 3. Scrambling order of N-correct out of M-choices}.
 The traditional multiple choice problem usually has 
only one correct answer described by a letter or  group of letters.  To prevent
guessing and to encourage the students to discuss 
the concepts presented by such problems, we have created problem prototypes
where the order and number of choices vary.  \\
In this example a set of variables is loaded for each student and displayed in
the text of the problem. The students are then 
given three statements which are generated from up to four versions.  \vskip
0.1in 
\hrule
%\footnotesize
\hskip -1in 
%\begingroup \footnotesize
\begin{capacode}
//************************************** 
/BEG prob_val=1
/IMP "../Tools/Problem#" 
//By E. Kashy, kashy@nscl.msu.edu, No Commercial Use
// ../CAPA4/MCTools/Nof3  Select N correct of 3 Statements
A mass M = 0.16 /DIS(kg_u) is on a smooth horizontal surface (negligible
friction). 
It is attached to a spring with spring constant k = 15.3 /DIS(NPm_u). The mass
is displaced from its equilibrium position (x=0) by a distance of 0.14 m 
(x= + 0.14 m) and then released from rest. 
// The next 3 lines are the answer format instructions for the students.
(Give all of the correct answers, i.e., A or BC or ABC...) 
//----------------------------------------
/LET s1a="The motion of M is simple harmonic motion."
/LET s1b="Statement 1 variation b"
/LET s1c="Statement 1 variation c"
/LET s1d="Statement 1 variation d"
/LET mix1=random(1,1,1)
/LET a1a=1
/LET a1b=26
/LET a1c=26
/LET a1d=26
//
/LET s2a="The amplitude varies with time."
/LET s2b="The amplitude doesn't vary with time"
/LET s2c="Statement 2 variation c"
/LET s2d="Statement 2 variation d"
/LET mix2=random(1,2,1)
/LET a2a=2
/LET a2b=1
/LET a2c=26
/LET a2d=26
//
/LET s3a="The frequency of oscillation is independent of k."
/LET s3b="The Period of oscillation is independent of k."
/LET s3c="The frequency of oscillation depends of k."
/LET s3d="Statement 3 variation d"
/LET mix3=random(1,3,1)
/LET a3a=2
/LET a3b=2
/LET a3c=1
/LET a3d=26
//
/IMP "../MCTools/Nof3aux"
/ANS(Nof3right,wgt=prob_val, str=mc, tries=5)
/DIS(stdline)
//**************************************
\end{capacode}
%\endgroup
%\normalsize
\noindent The output of the above code appears as:
\hrule
{\par \bf 1.} [1pt]
A mass M = 0.16 $kg$ is on a smooth horizontal surface (negligible friction). It
is attached to a spring with spring constant k = 15.3 $N/m$. The mass is
displaced from its equilibrium position (x=0) by a distance of 0.14 m (x=+ 0.14
m ) and then released from rest. (Give all of the correct answers, i.e., A or BC
or ABC...) 
\begin{choicelist}
\item[]  A) The amplitude varies with time.
\item[]  B) The Period of oscillation is independent of k.
\item[]  C) The motion of M is simple harmonic motion.
\end{choicelist}
\vskip .05in \hrule width2in height0.6pt \hfill \vskip .02in
\hrule
The statements displayed to the student are 
controlled by the {\tt mix{\em x}=random(1,4,1)} index.  The upper limit on the
random function is determined by the number of
statements available as options in each set.  In the example there is only one
choice of the first statement, and  {\tt mix1=random(1,1,1)}. For the third
statement, there are three choices and {\tt mix3=random(1,3,1)}, so a student gets
one of the three options. 

The example relies on an auxillary file to do the scrambling.  This file is
imported into set{\em x}.qz with the command:\\
{\tt /IMP "../MCTools/Nof3aux"}\\
The imported auxillary file depends upon
consistency in variable names.  Do not change the names of the statement
variables (e.g., {\tt s1a}) or the names of the answer
variables (e.g., {\tt a1a}).  If you wish to make major changes in tool formats,
it is recommended that you include the auxillary file
within the set{\em x}.qz rather than using the import ({\tt /IMP}) command.  The
choices are loaded into specific statement variable names (i.e., {\tt /LET
s1a="The motion of M is simple harmonic motion"}) 
that are correlated to the answer variables for `correct' { \tt /LET a1a=1}; or
`incorrect' { \tt /LET a1a=2}.  In this 
example, the variable {\tt s1b} is not used in the problem, so its answer {\tt
a1b} is not changed from the value 26.  In all the
preformatted MCTools files,  we have used 26 to indicate an unused
answer/statement.  
\begin{itemize}
\item  The file {\tt Nof3} can be simply copied from the {\tt CAPA4/MCTools}
directory and pasted into the problem set file. The {\tt Include Button} in {\tt
quizzer} allows a user to scan the directory structure and perform that
function.
\item  The statements (and their variations) are typed as strings into the s1a,
s2a, etc. and corresponding values for a1a, a2a, etc. indicating if the
variation is correct.
\item  The text of the new problem should be typed in.
\item Certain variables \begin{verbatim} kg_u, NPm_u,  stdline\end{verbatim} 
are not defined within the problem. Because they are used often, they were
defined in files imported once at the start of the set ({\tt /IMP
"../Tools/StdUnits"}) to simplify problem coding.
\item The middle integer in {\tt mix3=random(1,3,1)}  corresponds to the number
of variation of  statement
block 3.\\
\end{itemize}
%
%\item 
\subsection{\bf  Using Logical Functions and other Functions}. A number of logical
functions are provided in \capa\ to allow numerical testing for various
conditions.  The logical expression is tested and returns 0 if False and 1 if
true.  These expressions can be used in a number of ways, for example in the
rank4aux file used in problem 11 on page 56. 
\vskip 0.1in 
\hrule
%\noindent The system selects three random numbers in the ranges specified. 
%These are presented to the student with two decimal places (:2, see below). 
%Because there are three values, any of which could be the smallest, the numbers
%are compared pairwise.  As the logical function returns the number 0 or 1 the
%value of `pair1' will be set to the smaller of r4a and r4b.  
% making voffset less negative moves up
% making hoffset less negative moves right

%\end{enumerate}

\clearpage