Return to s-general.tex CVS log

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

- added the manual

    1: % \capa\ grammar and functions
    2: \hrule 
    3: % \vskip 0.2in
    4: \section{Specification of \capa{} Problem Sets}
    5: % {{\noindent \bf \it \LARGE Section 5: Specification of \capa\ Problem Sets}}
    6: % \vskip 0.2in
    7: \noindent This Section describes the \capa\ grammar and syntax. Examples show
    8: how to code problems and create problem sets.
    9: \vskip 0.2in
   10: \hrule
   11: 
   12: %\begin{enumerate}
   13: %\item 
   14: \subsection{\bf General Description.}
   15: The source code for the problems to be solved by  students are
   16: contained 
   17: in files labeled {\bf set{\em x}.qz} where {\bf {\em x}} is the problem set
   18: number.  These files contain all the information 
   19: needed for each problem as well as the information for the printed hard copy,
   20: the computer-screen presentations, and the web
   21: display of the problem set.  
   22: In the simplest case, one might imagine that the file contains just the text to
   23: specify the problems for the students.  
   24: However, each paper is individualized and must contain variable information such
   25: as the student's name, the due-date of the set, etc. 
   26: 
   27:  \capa\ uses the {\tt /DIS()} command to display functions, variables, or
   28:  anything that has been evaluated and must be  
   29:  inserted in the text when the output is generated.  \capa\ uses other special
   30:  commands at the beginning of a line.  For 
   31:  example: {\tt /LET} defines a variable.  {\tt /IMP} imports a file into the
   32:  {\tt .qz} file.  {\tt /HIN} defines a hint which is 
   33:  available for viewing by the student after the student has entered an incorrect
   34:  answer.  {\tt /ANS()} defines the answer to 
   35:  the problem. Note the UPPER CASE used for the commands. The {\tt //} is used
   36:  for lines that are comments and will not be evaluated 
   37:  or inserted into the text or displayed to the students.  The grammar for
   38:  writing problem sets with some examples is given in the following section.
   39: %
   40: %\item 
   41: \subsection{\bf \LaTeX\ and ASCII in \capa\ problems.}
   42: %
   43:  A complete but plain problem set can be written using only ASCII
   44: characters.  In this case the printed version and 
   45: the version displayed on the {\tt VT100} terminal will be \underline{exactly}
   46: the same.  However, we have found that high 
   47: quality printed problem sets can be readily produced by the \capa\ system with
   48: \LaTeX . Thus, an important and sometimes 
   49: confusing aspect of the set{\em x}.qz files is  the \LaTeX\ commands to control
   50: the presentation of the problem. 
   51: Greek characters, postscript figures, subscripts and superscripts must be
   52: imbedded in the problem set text 
   53: but cannot be displayed on the {\tt VT100} terminal window during interactive
   54: logins.  Using the {\bf tex()} function it is
   55:  possible to specify a \LaTeX\ 
   56: version and an ASCII version of a particular string of characters.  For example,
   57: {\bf $\Delta$H} could appear on paper whereas 
   58: only {\tt delta-H} can be shown on the screen (using ASCII characters).  The
   59: general form of the function to be evaluated  
   60:  is {\small tex("TeX","ASCii")}. For example:
   61: \begingroup\small\begin{verbatim}/DIS(tex("$\Delta$H","delta-H"))\end{verbatim}
   62: \endgroup
   63: would be used in the set{\em x}.qz file to display $\Delta$H on the printed
   64: paper.  The first argument is put into the \TeX\ 
   65: version and the second into the ASCII version.  Note that the {\tt /DIS()}
   66: command, mentioned above is used to evaluate an 
   67: expression amid text.
   68: %
   69: %\item 
   70: \subsection{\bf html in \capa\ problems.}
   71: %
   72: \noindent There are two functions available for specifically entering html code
   73: into your problem sets to improve the Web display of the problem set over that of ASCII text.  If you do not specify
   74: html code, then the ASCII code will be displayed on the web document.  The first
   75: html specific function is the {\tt web()}
   76: function which has similar usage to the {\tt tex()}function.  The {\tt web()}
   77: function has three fields for entry.  They are:\\
   78: {\tt web("ASCII","\TeX\ ","html")}.  The second function, {\tt html()}, can
   79: include anchors, links, or text
   80: to be displayed only on the web document.  An example of the use of
   81: this function is:\\
   82: /DIS({\tt html("<br><img src=/teacher/nsc111f7/pictures/Ball.gif>")})
   83: %
   84: \subsection{{\tt capa.config} File}
   85: A file called \index{capa.config}{\tt capa.config} located in the class directory contains 
   86: general configuration informations of the \capa\ system. 
   87: It is divided into sections 
   88: containing configurable parameters that 
   89: instructors can customize the \capa\ system. 
   90: The first section contains informations related to 
   91: the organization of a class, such as \index{exam\_path}exam\_path, 
   92: \index{quiz\_path}quiz\_path, \index{supp\_path}supp\_path, 
   93: and \index{others\_path}others\_path.
   94: 
   95: \begin{capacode}
   96: exam_path   = /usr/users/teacher/CAPA45/xph183f7
   97: quiz_path   = /usr/users/teacher/CAPA45/qph183f7
   98: supp_path   = /usr/users/teacher/CAPA45/rph183f7
   99: others_path = /usr/users/teacher/CAPA45/fci183f7
  100: \end{capacode}
  101: 
  102: These four class path parameters are the full path information 
  103: that lead to the classes where the exam scores, 
  104: quizz scores, supplementary exercises scores, and others scores are located.
  105: Together with the homework class where this capa.config file is located, 
  106: the score statistics can then be combined from all these
  107: different directories and form a single result. 
  108: 
  109: The second section specifies the full path to commands 
  110: that are used by the \capa\ system,
  111: such as `latex', `dvips', `mail', `allcapaid', and `qzparse'.
  112: 
  113: \begin{capacode}
  114: latex_command   =  "latex"
  115: dvips_command   =  "dvips"
  116: mail_command     =  "/usr/bin/mailx"
  117: allcapaid_command  =  "/usr/users/capadvt/CAPA_SRC/5.0/Teachertools/allcapaid"
  118: qzparse_command =  "/nfs/capa1/capadvt/CAPA_SRC/5.0/pProj/Linux/qzparse"
  119: \end{capacode}
  120: 
  121: The next section has the options and identifies the printers to use when 
  122: the system prints a postscript file. 
  123: Each line of \index{printer\_option} printer\_option specifies a printer name  
  124: selected for \texttt{capautilscapautils} to print problem set(s) for 
  125: a student.
  126: 
  127: The command used to print when a user selects one sided or 
  128: two sided printing is given by the two command options:
  129: \index{lprOneSided\_command}lprOneSided\_command, and 
  130: \index{lprTwoSided\_command}lprTwoSided\_command.
  131: 
  132: \begin{capacode}
  133: printer_option  = "cyccap_capa1"
  134: printer_option  = "cyccap_capa2"
  135: printer_option  = "west_post"
  136: printer_option  = "west_post2"
  137: 
  138: lprOneSided_command  =  "/usr/bin/lpr -P$Printer_selected"
  139: lprTwoSided_command  =  "/usr/bin/lpspr -K2 $PS_file | /usr/bin/lpr -P$Printer_selected"
  140: \end{capacode}
  141: 
  142: The fourth section specifies options for capalogin, 
  143: such as the time the goodbye message stayed on the screen 
  144: after student exits capalogin, which is 
  145: given in seconds in parameter \index{capalogin\_goodbye\_delay}
  146: capalogin\_goodbye\_delay.
  147: The time interval when capalogin consider the student is 
  148: in-active from the \index{capalogin\_inactivity\_delay}capalogin\_inactivity\_delay.
  149: 
  150: \index{capalogin\_show\_summary\_score}capalogin\_show\_summary\_score.
  151: \begin{capacode}
  152: capalogin_goodbye_delay  = 6     
  153: # specify the capalogin inactivity delay time in minutes
  154: # default value is 60 minutes, 0 means never time out
  155: capalogin_inactivity_delay  = 35
  156: # if set to none, don't show the summary score, any other value
  157: # or not defined show the score
  158: capalogin_show_summary_score = none
  159: \end{capacode}
  160: 
  161: Another section is related to an option in X-windows Quizzer. 
  162: By pressing the ``Std. Header'' button the following is written
  163: in the set$x$.qz file. 
  164: 
  165: \begin{capacode}
  166: BeginStandardQuizzerHeader 
  167: //CAPA system software is copyrighted by Michigan State University.
  168: //By using these materials, the User agrees to:
  169: //1) Protect the source code files  from unauthorized copying.
  170: //2) Limit  access  of the source material to teaching staff.
  171: //3) The User is free to mix, cut and paste, modify, adapt, delete,
  172: //   improve, etc. the problems and graphics for his/her own use.
  173: //
  174: /IMP "/demolibrary/Tools/StdMacros"
  175: /IMP "/demolibrary/Tools/StdUnits"
  176: /IMP "/demolibrary/Tools/StdConst"
  177: /IMP "HWTop"
  178: EndStandardQuizzerHeader
  179: \end{capacode}
  180: 
  181: Everything that appears between the keywords
  182: BeginStandardQuizzerHeader
  183: EnStandardQuizzerHeader
  184: is entered into the current .qz file when this button is pressed.
  185: 
  186: \subsection{{\tt capautils.config} File}
  187: 
  188: This first section contains informati0ns used by capautils. The file is self-explanatory bu the comments below can also help.
  189:  
  190: \index{homework\_scores\_limit\_set} homework\_scores\_limit\_set,
  191: \index{exam\_scores\_limit\_set}exam\_scores\_limit\_set,
  192: \index{quiz\_scores\_limit\_set}quiz\_scores\_limit\_set,
  193: \index{supp\_scores\_limit\_set}supp\_scores\_limit\_set, and
  194: \index{others\_scores\_limit\_set}others\_scores\_limit\_set.
  195: These parameters specify the maximal number of problem sets 
  196: that are used to calculated the scores from homework, exam, quizz, supplemental and 
  197: others directories.
  198: 
  199: The  file name to store all scores of students in the classl file 
  200: and is used to send out email is specified in parameter
  201: \index{master\_scores\_file}master\_scores\_file.
  202: The parameter \index{email\_template\_file}email\_template\_file
  203: specifies the template file for email.
  204: 
  205: \begin{capacode}
  206: homework_scores_limit_set = 12
  207: exam_scores_limit_set     = 7
  208: quiz_scores_limit_set     = 16
  209: supp_scores_limit_set     = 14
  210: others_scores_limit_set   = 0
  211: master_scores_file = "/usr/users/teacher/CAPA45/phy183f7/scores/scores.all"
  212: # The template file for e-mail
  213: email_template_file = "/usr/users/teacher/CAPA45/phy183f7/scores/email.template"
  214: \end{capacode}
  215: 
  216: The second section contains definitions used by capautils. 
  217: It first declare a series of variable names to be used 
  218: to store the scores and maximum scores for homework, quizz, and
  219: exam. 
  220: 
  221: 
  222: \begin{capacode}
  223: # pre-defined variable names that can be used in email.template
  224: #
  225: # Declare a variable name with ':=' 
  226: #  when assigning a value to a variable, use '='
  227: # This variable is used to store the total scores 
  228: #    calculated from all setX.db's in the regular class
  229: # It is later refered in the file 'email.template' as $HWtotal_scp
  230: var_homework_total_score   := HWtotal_scp
  231: # This variable is used to represent the total possible scores 
  232: #    that a student could receive from all setX.db's in the regular class
  233: # It is later refered in the file 'email.template' as $HWtotal_max_scp
  234: var_homework_total_max     := HWtotal_max_scp
  235: # This variable is used to represent the total scores 
  236: #    calculated from all setX.db's in the class specified
  237: #    by 'quiz_path' parameter in this file
  238: # It is later refered in the file 'email.template' as $QZtotal_scp
  239: var_quiz_total_score     := QZtotal_scp
  240: # This variable is used to represent the total scores 
  241: #    calculated from all setX.db's in the class specified
  242: #    by 'quiz_path' parameter in this file
  243: # It is later refered in the file 'email.template' as $QZtotal_max_scp
  244: var_quiz_total_max        := QZtotal_max_scp
  245: # This variable is used to represent the total number of 
  246: #    setX.db's in the class specified by 'quiz_path' parameter in this file
  247: # It is later refered in the file 'email.template' as $QZcount_scp
  248: var_quiz_count            := QZcount_scp
  249: # This variable is used to represent the total number of '-'
  250: #    a student got in the term summary report. It represents that
  251: #    the number of times the student is abscent from all the setX.db's 
  252: #    in the class specified by 'quiz_path' parameter in this file
  253: # It is not yet used in the file 'email.template,' but 
  254: #    can be refered as $QZabsent_scp
  255: var_quiz_absent           := QZabsent_scp
  256: # This variable will return a one line string in the form 
  257: #   xxx/xxx xxx/xxx xxx/xxx xxx/xxx xxx/xxx xxx/xxx
  258: #  It gives the statistics for each set in the class specified by
  259: #  'quiz_path' parameter in this file
  260: # It is later refered in the file 'email.template' as $QZsummary
  261: var_quiz_summary_string   := QZsummary
  262: \end{capacode}
  263: 
  264: 
  265: 
  266: 
  267: \begin{capacode}
  268: #
  269: # Declares a class of variables with the same prefix
  270: #  This declaration allows the access of individual set scores 
  271: #  in the class specified by 'exam_path' parameter in this file
  272: #  
  273: prefix_exam_raw_scores     := exam_raw
  274: # Thus, exam_raw1, exam_raw2, exam_raw3, exam_raw4 ... 
  275: #  represent the individual set score
  276: # These variables are used in the later definition of midterm1, midterm2, ...
  277: # 
  278: prefix_exam_raw_max        := exam_raw_max
  279: # similar to the above, now the maximum scores for exam 1 is stored 
  280: #  in variable exam_raw_max1
  281: # These variables are used in the later definition of midterm1, midterm2, ...
  282: 
  283: # This parameter is used in calculation of corrected credits by 
  284: #  successive corrections of their midterm exams
  285: correction_factor = 0.3
  286: # Correction formula for midterm exams
  287: #   here midterm1, midterm2, midterm3, and final_exam 
  288: #   are new variables whose definition depends on
  289: #   the raw scores of each set in the class specified by 'exam_path'
  290: \end{capacode}
  291: 
  292: The eighth section defines how the values of variable
  293: midterm1, midterm2, midterm3 are calculated from
  294: exam\_raw1, exam\_raw2 and exam\_raw3 and correction\_factor. 
  295: These are all in perl code format. The first definition describes how the
  296: value of midterm1 is calculated from exam\_raw1, exam\_raw2, and 
  297: correction\_factor. 
  298: The next definition is for midterm2 and the third definition is for midterm3. 
  299: 
  300: 
  301: \begin{capacode}
  302: ### The reason that we define midterm1, midterm2, midterm3 and final_exam here
  303: ###  is that score report file need these definitions.
  304: midterm1   ::
  305: 
  306: BEGIN_perl
  307: 
  308:   local($tmp);
  309:   if($exam_raw2 >= $exam_raw1) {
  310:     $tmp = $exam_raw1 + $correction_factor*($exam_raw2-$exam_raw1);
  311:   } else {
  312:     $tmp = $exam_raw1;
  313:   }
  314:   return ($tmp);
  315: 
  316: END_perl
  317: 
  318: 
  319: midterm2   ::
  320: 
  321: BEGIN_perl
  322: 
  323:   local($tmp);
  324:   if($exam_raw4 >= $exam_raw3) {
  325:     $tmp = $exam_raw3 + $correction_factor*($exam_raw4-$exam_raw3);
  326:   } else {
  327:     $tmp = $exam_raw3;
  328:   }
  329:   return ($tmp);
  330: 
  331: END_perl
  332: 
  333: 
  334: midterm3   ::
  335: BEGIN_perl
  336: 
  337:   local($tmp);
  338:   if($exam_raw6 >= $exam_raw5) {
  339:     $tmp = $exam_raw5 + $correction_factor*($exam_raw6-$exam_raw5);
  340:   } else {
  341:     $tmp = $exam_raw5;
  342:   }
  343:   return ($tmp);
  344: 
  345: END_perl
  346: 
  347: \end{capacode}
  348: 
  349: 
  350: The last section is related to \index{units}units specifications. 
  351: This section is further divided into three subsections. The first is 
  352: the definition of base units. 
  353: It begins with the special marker ``\verb"<< Base Unit >>".''
  354: Each line contains a definition of a base units, it begins with 
  355: a full name, a symbol represents that base units, and a comment begins with a `\verb"#"'
  356: character. These three fields are separacted by white spaces and 
  357: all three fields are required. 
  358: The number of characters in a full name description 
  359: should not exceed 47 characters and there should not contain any 
  360: space or tab characters in the full name description. 
  361: The number of characters denoting a symbol is limited to 15 characters. 
  362: There could be at most 32 base units defined in this subsection.
  363: 
  364: \begin{capacode}
  365: << Base Unit >>
  366: meter           m      # length
  367: kilogram        kg     # mass
  368: second          s      # time
  369: ampere          A      # electric current
  370: kelvin          K      # thermodynamic temperature
  371: mole            mol    # amount of substance
  372: candela         cd     # luminous intensity
  373: \end{capacode}
  374: The next subsection of units is the definition of prefix symbols. 
  375: It is consists of three fields on each line, separated by 
  376: white spaces or tab characters. 
  377: The length of the full name is not limited to any number of characters, 
  378: however, it cannot contain any while space or tab character. 
  379: The symbol character contains only one character. 
  380: The actual power the character represents is 
  381: shown in the third field.
  382: There could be as many as 52 definitions of the prefix symbol, 
  383: one for each alphabet from a to z and A to Z. 
  384: \begin{capacode}
  385: << Prefix >>
  386: yotta            Y         10^{24}
  387: zetta            Z         10^{21}
  388: exa              E         10^{18}
  389: peta             P         10^{15}
  390: tera             T         10^{12}
  391: giga             G         10^9
  392: mega             M         10^6
  393: kilo             k         10^3
  394: hecto            h         10^2
  395: deci             d         10^-1
  396: centi            c         10^-2
  397: milli            m         10^-3
  398: micro            u         10^-6
  399: nano             n         10^-9
  400: pico             p         10^{-12}
  401: femto            f         10^{-15}
  402: atto             a         10^{-18}
  403: zepto            z         10^{-21}
  404: yocto            y         10^{-24}
  405: \end{capacode}
  406: The third subsection of units is the definition of derived units. 
  407: It is consists of four fields on each line, all four fields are 
  408: required. 
  409: The first field is a one-word name for the units defined 
  410: in that row, the number of characters is at maximal 47. 
  411: The second field is the symbol denoting the units, 15 characters is the maximum.
  412: The first and the second fields are separated by spaces, 
  413: no space is allowed within the name field and the symbol field. 
  414: The third field is the way the units is calculated from base units or other 
  415: previously defined derived units.
  416: Operations that could be used in this field are
  417: ``*'' (multiplication),`` '' (multiplication), ``/'' (division), and
  418: ``\verb"^"'' (integeral power). 
  419: Number can be entered in floating point format (0.001) or 
  420: exponential form (1.77185E-3). 
  421: Operations ``\verb"+"'' (plus) and ``\verb"-"'' (minus) are not allowed. 
  422: The fourth field begins with a `\verb"#"' mark is the comment for this units. 
  423: 
  424: \begin{capacode}
  425: <<Derived Unit>>
  426: gram            g      0.001 kg      # mass
  427: hour            hr     3600. s       # time
  428: pound           lb     0.45359237 kg # mass
  429: ounce           oz     1.77185E-3 kg # mass
  430: inch            in     2.54 cm       # length
  431: foot            ft     12 in         # length
  432: mile            mi     5280 ft       # length
  433: yard            yd     0.9144 m      # length
  434: nautical_mile   n_mi   6080 ft       # length, nautical mile (UK)
  435: rood            rood   1210 yd^2     # area, rood
  436: acre            acre   4840 yd^2     # area, acre
  437: hertz           Hz     1/s           # frequency
  438: litre           L      10^3/cm^3     # volume
  439: newton          N      m*kg/s^2      # force
  440: pound_force     lbf    4.44822 N     # force
  441: dyne            dyn    1E-5 N        # force
  442: pascal          Pa     N/m^2           # pressure, stress
  443: bar             bar    1E5 Pa          # pressure
  444: mmHg            mmHg   1.33322E2 Pa    # pressure, millimeter of mercury
  445: torr            torr   1 mmHg          # pressure
  446: atm             atm    760 torr        # standard atmosphere
  447: joule           J      N*m             # energy, work, heat
  448: electronvolt    eV     1.6021892E-19 J # energy
  449: calorie         cal    4.1868 J        # energy
  450: Btu             Btu    1.05506E3 J     # energy
  451: watt            W      J/s             # power, radiant flux
  452: coulomb         C      A*s             # electric charge
  453: volt            V      J/C           # electric potential, electromotive force
  454: ohm             Ohm    V/A           # electric resistance
  455: siemens         S      1/Ohm         # electric conductance
  456: farad           F      C/V           # electric capacitance
  457: tesla           T      V s/m^2       # magnetic flux density
  458: weber           Wb     V*s           # magnetic flux
  459: henry           H      V*s/A         # inductance
  460: radian          rad    m /m            # plane angle
  461: degree          deg    1.745329E-2 rad # plane angle (Pi rad=180 deg)
  462: steradian       sr     m^2 /m^2        # solid angle
  463: lumen           lm     cd*sr         # luminous flux
  464: lux             lx     cd*sr/m^2     # illuminance
  465: becquerel       Bq     1/s           # activity (radioactive)
  466: gray            Gy     J/kg          # absorbed dose (of radiation)
  467: sievert         Sv     J/kg          # dose equivalent (dose equivalent index)
  468: astroUnit       AU     1.49598E11 m  # mean distance earth to sun
  469: \end{capacode}
  470: 
  471: The rule for matching a units is 
  472: that the process begins with derived and base units first. 
  473: Such as `T' will be matched against ``tesla'' instead of been considered as 
  474: prefix `T'. Another example is that
  475: ``min'' will be matching ``minutes'' instead of treated  
  476: as combination of prefix `m' and 
  477: units `in'. 
  478: 
  479: 
  480: 
  481: 
  482: %\item
  483: \subsection{\bf Grammar Specifications}
  484: \begin{itemize}
  485: \item  The end-of-line character (produced by the {\em Return} key) plays a
  486: critical role in the {\tt set$x$.qz} files.  It is 
  487: used to signify the end of text and mathematical expressions.  Since single
  488: end-of-line characters are ignored by \LaTeX,  
  489: careful usage of the {\em Return} key can be used to format the ASCII output. 
  490: Because the {\tt quizzer}  display automatically 
  491: line-wraps the text input, it is important to check  
  492: the ASCII display before distributing a problem set. The best method is to log
  493: in just as a student would.
  494: %
  495: \item   It is convenient to begin the question file, set{\em x}.qz  with
  496: commands such as {\tt /IMP "HWTop"} 
  497: and  {\tt /IMP "../Tools/StdMacros"}. These  commands `import' a header to
  498: display the student's name, the course name, 
  499: as well as macros for often used   commands and instructions.  The questions
  500: with their coded answers (and appropriate hints, 
  501: comments and explanations if desired) follow.   {\tt /END} command and a
  502: carriage return signify the end of the entire set. It is
  503: recommended that each type of problem for a specific field of study be
  504: classified and kept in individual ASCII files.  This way
  505: an entire problem set can be generated by using commands similar to {\tt /IMP
  506: "../ProblemLibrary/type04/prob3"}.
  507: %
  508: \item  Note that there are also two auxiliary files with commands for formatting
  509: the \LaTeX\ 2.09 document called {\tt TeXheader}
  510:  and {\tt Texfooter}.  These are  automatically included by {\tt quizzer} at the
  511:  top and bottom of the {\tt
  512:  quiztemp.tex} file 
  513:  before the {\tt quiztemp.dvi} file is created.
  514: %
  515: The {\tt TeXheader} file used at MSU creates a high density two-column format
  516: for the problem sets. This file is contained in 
  517: the {\tt nsc111f7} directory and is shown below:\\ 
  518: %
  519: %\begingroup\small 
  520: \begin{capacode}
  521: \documentstyle[twocolumn,epsf]{article}
  522: \textheight 25.9cm  
  523: \oddsidemargin = -0.42in
  524: \evensidemargin = -0.42in
  525: \textwidth= 7.28in  
  526: \begin{document}
  527: \voffset=-4.1cm
  528: \setcounter{page}{1}
  529: \newcommand{\\capa\}{{\sl C\kern-.10em\raise-.00ex\hbox{\rm A}\kern-.22em%
  530: {\sl P}\kern-.14em\kern-.01em{\rm A}}}
  531: \newenvironment{choicelist}{\begin{list}{}{\setlength{\rightmargin}{0in}
  532: \setlength{\leftmargin}{0.13in}\setlength{\topsep}{0.05in}\setlength{\item
  533:  sep}{0.022in}\setlength{\parsep}{0in}\setlength{\belowdisplayskip}{0.04in}
  534: \setlength{\abovedisplayskip}{0.05in}\setlength{\abovedisplayshortskip}
  535: {-0.04in}\setlength{\belowdisplayshortskip}{0.04in}}}{\end{list}}
  536: \end{capacode}
  537: %\endgroup
  538: %
  539: \item  The \index{HWTop}{\tt HWTop} file should be at the top of each problem set. It
  540: includes the student name, section number, class title, 
  541: assignment number, due date, and student's CAPA ID for the assignment. 
  542: %
  543: \item  The actual {\tt HWTop} file information used in {\tt nsc111f7} is shown
  544: below, together with a magnified example  
  545: of the resulting output. Note: In the actual set, the carriage returns are
  546: omitted from the header information.
  547: \newpage
  548: % \vskip 0.1in
  549: % \hrule
  550: % \scriptsize
  551: % \begin{verbatim}
  552: % /DIS(tex("\noindent{\large\bf ",""))/DIS(tex(name(),""))/DIS(tex("\hfill Section
  553: % {\Large ",""))
  554: % /DIS(tex(section(),""))/DIS(tex("}}\\","")) /DIS(tex("\vskip -.1in",""))
  555: % /DIS(tex("\noindent {\large \it Natural Science 111-- \hfill  Set
  556: % ",""))/DIS(tex(set(),""))
  557: % /DIS(tex("}\\ \vskip -.16in",""))   /DIS(tex("\noindent{\bf
  558: % ",""))/DIS(tex(class(),""))
  559: % /DIS(tex("} -- MSU -- 1995.  Due ",""))/DIS(tex(due_date(),"")) /DIS(tex("CAPA
  560: % ID is",""))
  561: % /DIS(tex("{\footnotesize  ",""))/DIS(tex(capa_id(),""))/DIS(tex("}",""))
  562: %  /DIS(tex("\vskip .1in \pagestyle{empty} ",""))
  563: % //
  564: % /LET stdendline=tex("\vskip .05in \hrule width3.55in height0.6pt \hfill \vskip
  565: % -.07in \noindent 
  566: % {\tiny Dept. of Physics and Astronomy, Michigan State University  \dotfill 
  567: % {CAPA\copyright msu}}","")
  568: % \end{verbatim}
  569: \footnotesize{
  570: \begin{capacode}
  571: /LET nameforTeX = name()
  572: /LET due_dateforTeX = due_date()
  573: /LET PINforTeX = capa_id()
  574: /LET sectionforTeX = section()
  575: /LET setforTeX=set()
  576: /LET classforTeX=class()
  577: //
  578: /DIS(tex("\noindent{\large\bf ",""))/DIS(var_in_tex(nameforTeX))
  579: /DIS(tex("\hfill Section {\Large ",""))/DIS(var_in_tex(sectionforTeX))
  580: /DIS(tex("}}\\","")) /DIS(tex("\vskip -.1in","")) 
  581: /DIS(tex("\noindent {\large \it Sample \capa Questions \hfill  Set ",""))
  582: /DIS(var_in_tex(setforTeX))/DIS(tex("}\\ \vskip -.16in",""))   
  583: /DIS(tex("\noindent{\bf ",""))
  584: /DIS(var_in_tex(classforTeX))/DIS(tex("} -- MSU --  Various Dates.  Due ",""))
  585: /DIS(var_in_tex(due_dateforTeX)) /DIS(tex("CAPA ID is",""))
  586: /DIS(tex("{\footnotesize  ",""))/DIS(var_in_tex(PINforTeX))/DIS(tex("}","")) 
  587: /DIS(tex("\vskip .1in \pagestyle{empty} ",""))
  588: //
  589: //
  590: /LET DeptID="College of Natural Science, Michigan State University"
  591: /LET stdendlineA=web("", \
  592:   "\vskip .05in\hrule width3.55in height .6pt\
  593:   \hfill\vskip -.07in\noindent{\tiny ", \
  594:   "<Font color=\"gray\"><font size =-1><i> --- ")
  595: /LET stdendlineB=web("", \
  596:   " \dotfill  {CAPA\copyright msu}}", \
  597:   " --- </font><font size=-2>CAPA &#169</font><font=-1> msu</i></font> \
  598:    <font color=\"black\"")
  599: /LET stdendline=stdendlineA+DeptID+stdendlineB
  600: \end{capacode}
  601: }
  602: % \hrule
  603: \normalsize
  604: % \vskip .2 in
  605: \item  These lines contain \LaTeX\ commands for alignment and font
  606: specification.  They use arguments in the {\tt tex()} function for
  607: \LaTeX\ which are not displayed in the ASCII  or Web versions.  The functions
  608: print the Student Name, section number, problem set
  609: number, due date and CAPA ID.  
  610: \item  The  \LaTeX\ source document created from  {\tt TeXheader} and {\tt
  611: HWTop}, i.e., the first lines in the file 
  612: {\tt quiztemp.tex} file follow: (again, some carriage returns have been added) 
  613: % \vskip 0.1 in
  614: % \hrule \begingroup
  615: % \footnotesize
  616: % \begin{verbatim}
  617: % \documentstyle[twocolumn,epsf]{article}
  618: % \textheight 25.9cm  
  619: % \oddsidemargin = -0.42in
  620: % \evensidemargin = -0.42in
  621: % \textwidth= 7.28in  
  622: % \begin{document}
  623: % \voffset=-4.1cm
  624: % \setcounter{page}{1}
  625: % \newcommand{\\capa\}{{\sl C\kern-.10em\raise-.00ex\hbox{\rm A}\kern-.22em%
  626: %   {\sl P}\kern-.14em\kern-.01em{\rm A}}}
  627: % \newenvironment{choicelist}{\begin{list}{}{\setlength{\rightmargin}{0in}
  628: % \setlength{\leftmargin}{0.13in}\setlength{\topsep}{0.05in}\setlength
  629: % {\itemsep}{0.022in}\setlength{\parsep}{0in}\setlength{\belowdisplayskip}
  630: % {0.04in}\setlength{\abovedisplayskip}{0.05in}\setlength
  631: % {\abovedisplayshortskip}{-0.04in}\setlength{\belowdisplayshortskip}{0.04in}}}
  632: % {\end{list}}\noindent{\large\bf Student, Jamie                \hfill Section
  633: %  {\Large 1}}\\ \vskip -.1in \noindent {\large \it \capa\ Natural Science--
  634: %  \hfill
  635: %   Set 1}\\ \vskip -.16in   \noindent{\bf nsc111f7} -- MSU -- 1995.  Due Sun,
  636: % Sep  1, 1996 at 08:00. CAPA ID is {\footnotesize  8755} \vskip .1in 
  637: % \pagestyle{empty} 
  638: % \end{verbatim}
  639: % \endgroup
  640: \footnotesize{
  641: \begin{capacode}
  642: \documentstyle[twocolumn,epsf]{article}
  643: \textheight 25.9cm  
  644: \oddsidemargin = -0.42in
  645: \evensidemargin = -0.42in
  646: \textwidth= 7.28in  
  647: \begin{document}
  648: \voffset=-4.1cm
  649: \setcounter{page}{1}
  650: \newcommand{\capa}{{\sl C\kern-.10em\raise-.00ex\hbox{\rm A}\kern-.22em%
  651:   {\sl P}\kern-.14em\kern-.01em{\rm A}}}
  652: \newenvironment{choicelist}{\begin{list}{}{\setlength{\rightmargin}{0in}
  653: \setlength{\leftmargin}{0.13in}\setlength{\topsep}{0.05in}
  654: \setlength{\itemsep}{0.022in}
  655: \setlength{\parsep}{0in}\setlength{\belowdisplayskip}{0.04in}
  656: \setlength{\abovedisplayskip}{0.05in}
  657: \setlength{\abovedisplayshortskip}{-0.04in}
  658: \setlength{\belowdisplayshortskip}{0.04in}}}{\end{list}}
  659: 
  660: 
  661: \noindent{\large\bf Student, Jamie .\hfill Section {\Large 1}}\\
  662: \vskip -.1in \noindent 
  663: {\large \it Sample \capa Questions \hfill  Set 1}\\
  664: \vskip -.16in   \noindent{\bf nsc111f7} 
  665: -- MSU --  Various Dates.  Due Fri, May 15, 1998 at 08:00 CAPA ID is 
  666: {\footnotesize  5743}
  667:  \vskip .1in \pagestyle{empty} 
  668: \end{capacode}
  669: }
  670: % \hrule 
  671: % \vskip 0.1 in
  672: \normalsize\noindent 
  673: Note that all of the \capa\ functions have been evaluated
  674: before the file is written.  
  675: \item  The result from Latex and dvips processing is a student copy which looks
  676: like:
  677: \begin{center}
  678: \parbox[t]{3.8in}{
  679: \noindent {\hrule \vskip 0.2 in \noindent{\large\bf Student, Jamie              
  680:  \hfill Section {\Large 1}}\\ \vskip -.1in 
  681: \noindent {\large \it \capa\ Natural Science-- \hfill  Set 1}\\ \vskip -.16in  
  682: \noindent{\bf nsc111f7} -- MSU -- 1995.  
  683: Due Sun, Sep  1, 1996 at 08:00. CAPA ID is {\footnotesize  8755} \vskip .1in
  684: \hrule}}
  685: \end{center}
  686: \normalsize
  687: \item  The remainder of the set{\em x}.qz file contains the questions. Each
  688: question typically consists of a block of 
  689: variable definitions, the text for the question including evaluation  of
  690: imbedded data, the coding of the answer, and 
  691: optionally, a comment, a hint and an explanation. 
  692: \vskip 0.2in
  693: \end{itemize}
  694: %\item 
  695: \subsection{Example}
  696: {\bf Example 1.} A complete example of a very simple \capa\ problem is
  697: given below:
  698: % \vskip 0.1in
  699: % \hrule
  700: % \footnotesize
  701: \begin{capacode}
  702: //************************************** 
  703: /BEG prob_val=2
  704: /IMP "../Tools/Problem#" 
  705: // By S. Wolfe, wolfe@nscl.msu.edu, No commercial use.
  706: /HIN Summing is the same as Addition.
  707: /EXP Add the two numbers and enter the result.
  708: //
  709: /LET firstnumber=random(1,5,1)
  710: /LET secondnumber=random(2,10,2)
  711: //
  712: Find the sum of /DIS(firstnumber) plus /DIS(secondnumber). 
  713: //
  714: /LET sum=firstnumber+secondnumber
  715: /ANS(sum,tol=0.01,wgt=prob_val,tries=10)
  716: /DIS(stdline)
  717: //**************************************
  718: \end{capacode}
  719: 
  720: % \normalsize
  721: % \noindent 
  722: The printed output for a specific student appears as:
  723: % \vskip 0.1in
  724: % \hrule
  725: 
  726: {\bf 1. [2pt]} Find the sum of 3 plus 8.\\ 
  727: \vskip .05in \hrule width2in height0.6pt \hfill \vskip .02in
  728: 
  729: \begin{itemize}
  730: \item  Each of the lines in this example is terminated with a carriage return
  731: end-of-line character, even though it is not 
  732: visible here.  
  733: \item The  {\tt /BEG prob\_val=2} begins the problem and sets the weight of the
  734: problem to 2 points. (The weight must be an integer from 1 to 9.) [Note: \verb"/BEG"
  735: is the same as \verb"/LET"]
  736: \item The {\tt /IMP "../Tools/Problem\#"} function is used to print the problem
  737: number and the weight of the problem with a 
  738: bold font.
  739: \item  All lines that start with double-slashes, {\tt //}, are comment lines and
  740: only appear in the \mbox{set{\em x}.qz} file.  
  741: For example, the comment lines of stars are used to visually separate problems so that they
  742: can be identified easily.  As in any computer 
  743: code, comments play an important role in documentation and  ``self-documenting''
  744: variable names are helpful.  
  745: \item  The line beginning with {\tt /HIN}  contains an optional hint, i.e., it
  746: is up to the instructor whether to include such 
  747: a hint for the students on a particular problem.  If a hint has been coded into
  748: a problem, the student can `request' to view the
  749:  hint after attempting to answer the question.  
  750: \item  The line beginning with {\tt /EXP} is the explanation.  The explanation
  751: becomes available to the students after data 
  752: entry to the problem set is `closed.' (Explanations and Hints are  included at
  753: the discretion of the 
  754: instructor). 
  755: \item  The  lines beginning with {\tt /LET} are definitions of the variables
  756: needed for this problem.  {\tt firstnumber}, is 
  757: declared to be a random integer in the range of 1 to 5 in steps of 1, similarly,
  758: {\tt secondnumber} is an integer in the range 
  759: of 2 to 10 in steps of 2.  \capa\ displays real and integer variables
  760: differently. It is preferable not to mix integer and 
  761: real numbers. Within functions such as {\tt random()} they must not be mixed.
  762: \item  Next, we have the text of the problem that will be contained in the
  763: printed problem set and shown on the computer 
  764: screen.  Note that the {\tt /DIS()} command around a previously declared
  765: variable tells the computer to display its value.  
  766: If the variable is not defined prior to diplaying, an
  767: error message will be displayed.  
  768: \item  The {\tt /LET sum =..} declares that the variable {\tt sum} is the sum of
  769: the two random numbers. This is the answer to 
  770: the problem and we use an appropriate variable name.  (The name of the answer,
  771: here {\tt sum}, is up to the author.)  
  772: \item  Finally, the answer to the problem is declared using the {\tt /ANS()}
  773: command. The line with the answer should come 
  774: literally at the end of all the material for a problem. See Section 6 for
  775: explanations of the arguments of the {\tt /ANS()} function.\\
  776: \end{itemize}
  777: %
  778: %\vskip 0.10 in
  779: %\item
  780: \subsection{\bf Example 2. Using the choose() function}
  781:  The {\tt choose()} function can be used to select among choices or to correlate
  782:  variables with pictures or graphs. ({\small Note: there should be NO
  783: carriage return in the choose line. In general, try
  784: to minimize carriage returns as they use up the limited number of lines
  785: available as screen display on the vt100 terminals}). In this example the
  786: computer selects a random number in the range of 1 to 14 and then constructs a
  787: filename to be displayed and the correlated answer.  
  788: \vskip 0.1in 
  789: \hrule
  790: %
  791: \scriptsize \begin{verbatim}
  792: //************************************** 
  793: /BEG prob_val=1
  794: /IMP "../Tools/Problem#" 
  795: //By E. Kashy, kashy@nscl.msu.edu, No commercial  use
  796: /LET k=random(1,14,1)
  797: /LET file=choose(k,"35","45","56","62","77","86","93","m26","m39","m47","m51","m66","m74","m84")
  798: /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)
  799: The graph shows the function /DIS(tex("\\ \centerline{$Y=a x$} ","Y=ax. "))
  800: Make a careful determination of the value of /DIS(tex("$a$","a")).
  801: /DIS(tex("\epsfxsize=3.6in \epsffile{/usr/users/teacher/CAPA45/nsc111f7/pictures/Y",""))
  802: /DIS(var_in_tex(file))/DIS(tex("x.ps}",""))
  803: /DIS( html("<IMG SRC=/nsc111f7/pictures/Y"))/DIS(html(file))/DIS(html("x.gif >") )
  804: /ANS(ans5:2E,tol=5%,wgt=prob_val,tries=10)
  805: /DIS(stdline)
  806: //**************************************
  807: \end{verbatim}
  808: 
  809: \normalsize
  810: \noindent The output on paper would look like (see next page):
  811: \clearpage
  812: \hrule
  813: {\bf 2.}[1pt] The graph below represents the function $$Y=a x$$ Make a careful
  814: determination of the value of $a$\\ 
  815: \centerline{\epsfxsize=3.8in\epsffile{pictures/Y3p5x.ps}}
  816: \vskip .05in \hrule width2in height0.6pt \hfill \vskip .02in
  817: %
  818: \begin{itemize}
  819: \item  The computer code picks a random number, {\tt k}, and the {\tt choose}
  820: function selects the string variable, ``35", that 
  821: will be included in the name of the {\tt .eps} or \texttt{.gif} file to be displayed.  The choose
  822: function contains the selection index as its 
  823: first argument and the choices as the remaining arguments. 
  824: \item   It is important to check that the number of choices corresponds exactly
  825: to the maximum number of the selection index.  
  826: Otherwise an error will occur whenever the index (randomly) lies outside the
  827: range of choices. An `Out of bounds' error message 
  828: is displayed.
  829: \item   The answer is also specified with a {\tt choose()} function using the
  830: same selection index.  
  831: \item  The author of the problem must be sure that the data in the first {\tt
  832: choose()} function corresponds to the answers 
  833: in the second {\tt choose()} function.  
  834: \end{itemize}
  835: \vskip 0.2in
  836: %\item 
  837: \subsection{\bf Example 3. Scrambling order of N-correct out of M-choices}.
  838:  The traditional multiple choice problem usually has 
  839: only one correct answer described by a letter or  group of letters.  To prevent
  840: guessing and to encourage the students to discuss 
  841: the concepts presented by such problems, we have created problem prototypes
  842: where the order and number of choices vary.  \\
  843: In this example a set of variables is loaded for each student and displayed in
  844: the text of the problem. The students are then 
  845: given three statements which are generated from up to four versions.  \vskip
  846: 0.1in 
  847: \hrule
  848: %\footnotesize
  849: \hskip -1in 
  850: %\begingroup \footnotesize
  851: \begin{capacode}
  852: //************************************** 
  853: /BEG prob_val=1
  854: /IMP "../Tools/Problem#" 
  855: //By E. Kashy, kashy@nscl.msu.edu, No Commercial Use
  856: // ../CAPA4/MCTools/Nof3  Select N correct of 3 Statements
  857: A mass M = 0.16 /DIS(kg_u) is on a smooth horizontal surface (negligible
  858: friction). 
  859: It is attached to a spring with spring constant k = 15.3 /DIS(NPm_u). The mass
  860: is displaced from its equilibrium position (x=0) by a distance of 0.14 m 
  861: (x= + 0.14 m) and then released from rest. 
  862: // The next 3 lines are the answer format instructions for the students.
  863: (Give all of the correct answers, i.e., A or BC or ABC...) 
  864: //----------------------------------------
  865: /LET s1a="The motion of M is simple harmonic motion."
  866: /LET s1b="Statement 1 variation b"
  867: /LET s1c="Statement 1 variation c"
  868: /LET s1d="Statement 1 variation d"
  869: /LET mix1=random(1,1,1)
  870: /LET a1a=1
  871: /LET a1b=26
  872: /LET a1c=26
  873: /LET a1d=26
  874: //
  875: /LET s2a="The amplitude varies with time."
  876: /LET s2b="The amplitude doesn't vary with time"
  877: /LET s2c="Statement 2 variation c"
  878: /LET s2d="Statement 2 variation d"
  879: /LET mix2=random(1,2,1)
  880: /LET a2a=2
  881: /LET a2b=1
  882: /LET a2c=26
  883: /LET a2d=26
  884: //
  885: /LET s3a="The frequency of oscillation is independent of k."
  886: /LET s3b="The Period of oscillation is independent of k."
  887: /LET s3c="The frequency of oscillation depends of k."
  888: /LET s3d="Statement 3 variation d"
  889: /LET mix3=random(1,3,1)
  890: /LET a3a=2
  891: /LET a3b=2
  892: /LET a3c=1
  893: /LET a3d=26
  894: //
  895: /IMP "../MCTools/Nof3aux"
  896: /ANS(Nof3right,wgt=prob_val, str=mc, tries=5)
  897: /DIS(stdline)
  898: //**************************************
  899: \end{capacode}
  900: %\endgroup
  901: %\normalsize
  902: \noindent The output of the above code appears as:
  903: \hrule
  904: {\par \bf 1.} [1pt]
  905: A mass M = 0.16 $kg$ is on a smooth horizontal surface (negligible friction). It
  906: is attached to a spring with spring constant k = 15.3 $N/m$. The mass is
  907: displaced from its equilibrium position (x=0) by a distance of 0.14 m (x=+ 0.14
  908: m ) and then released from rest. (Give all of the correct answers, i.e., A or BC
  909: or ABC...) 
  910: \begin{choicelist}
  911: \item[]  A) The amplitude varies with time.
  912: \item[]  B) The Period of oscillation is independent of k.
  913: \item[]  C) The motion of M is simple harmonic motion.
  914: \end{choicelist}
  915: \vskip .05in \hrule width2in height0.6pt \hfill \vskip .02in
  916: \hrule
  917: The statements displayed to the student are 
  918: controlled by the {\tt mix{\em x}=random(1,4,1)} index.  The upper limit on the
  919: random function is determined by the number of
  920: statements available as options in each set.  In the example there is only one
  921: choice of the first statement, and  {\tt mix1=random(1,1,1)}. For the third
  922: statement, there are three choices and {\tt mix3=random(1,3,1)}, so a student gets
  923: one of the three options. 
  924: 
  925: The example relies on an auxillary file to do the scrambling.  This file is
  926: imported into set{\em x}.qz with the command:\\
  927: {\tt /IMP "../MCTools/Nof3aux"}\\
  928: The imported auxillary file depends upon
  929: consistency in variable names.  Do not change the names of the statement
  930: variables (e.g., {\tt s1a}) or the names of the answer
  931: variables (e.g., {\tt a1a}).  If you wish to make major changes in tool formats,
  932: it is recommended that you include the auxillary file
  933: within the set{\em x}.qz rather than using the import ({\tt /IMP}) command.  The
  934: choices are loaded into specific statement variable names (i.e., {\tt /LET
  935: s1a="The motion of M is simple harmonic motion"}) 
  936: that are correlated to the answer variables for `correct' { \tt /LET a1a=1}; or
  937: `incorrect' { \tt /LET a1a=2}.  In this 
  938: example, the variable {\tt s1b} is not used in the problem, so its answer {\tt
  939: a1b} is not changed from the value 26.  In all the
  940: preformatted MCTools files,  we have used 26 to indicate an unused
  941: answer/statement.  
  942: \begin{itemize}
  943: \item  The file {\tt Nof3} can be simply copied from the {\tt CAPA4/MCTools}
  944: directory and pasted into the problem set file. The {\tt Include Button} in {\tt
  945: quizzer} allows a user to scan the directory structure and perform that
  946: function.
  947: \item  The statements (and their variations) are typed as strings into the s1a,
  948: s2a, etc. and corresponding values for a1a, a2a, etc. indicating if the
  949: variation is correct.
  950: \item  The text of the new problem should be typed in.
  951: \item Certain variables \begin{verbatim} kg_u, NPm_u,  stdline\end{verbatim} 
  952: are not defined within the problem. Because they are used often, they were
  953: defined in files imported once at the start of the set ({\tt /IMP
  954: "../Tools/StdUnits"}) to simplify problem coding.
  955: \item The middle integer in {\tt mix3=random(1,3,1)}  corresponds to the number
  956: of variation of  statement
  957: block 3.\\
  958: \end{itemize}
  959: %
  960: %\item 
  961: \subsection{\bf  Using Logical Functions and other Functions}. A number of logical
  962: functions are provided in \capa\ to allow numerical testing for various
  963: conditions.  The logical expression is tested and returns 0 if False and 1 if
  964: true.  These expressions can be used in a number of ways, for example in the
  965: rank4aux file used in problem 11 on page 56. 
  966: \vskip 0.1in 
  967: \hrule
  968: %\noindent The system selects three random numbers in the ranges specified. 
  969: %These are presented to the student with two decimal places (:2, see below). 
  970: %Because there are three values, any of which could be the smallest, the numbers
  971: %are compared pairwise.  As the logical function returns the number 0 or 1 the
  972: %value of `pair1' will be set to the smaller of r4a and r4b.  
  973: % making voffset less negative moves up
  974: % making hoffset less negative moves right
  975: 
  976: %\end{enumerate}
  977: 
  978: \clearpage
  979: