--- doc/tutorial/Attic/tutorial.lyx 2002/06/03 05:15:59 1.3 +++ doc/tutorial/Attic/tutorial.lyx 2002/06/03 21:29:28 1.4 @@ -140,6 +140,11 @@ Throughout this manual, keywords and phr bold type \series default . + Function names and scripts will be shown in a +\family typewriter +typewriter font +\family default +. \layout Standard Chapters @@ -2650,10 +2655,14 @@ After the system notices the map does no Note there are two windows. One is the workspace, and one is the window which will contain information as you add resources. -\layout Subsection +\layout Comment + +The following is a commented-out section of the manual, likely to not be + useful. +\layout Comment About The Editor -\layout Standard +\layout Comment \begin_float fig \layout Caption @@ -2666,12 +2675,12 @@ Example of the Map Editor \end_float Maps are very powerful and can do a lot. - They can make decisions as the user progresses, and go down different paths + They can make decisions as the user progresses, going down different paths under different circumstances. For instance, a map can go down one path if the user gets a problem right, - and another path if they don't. + and another path if they don't which will provide more help for the student. -\layout Standard +\layout Comment To facilitate editing these powerful entities, LON-CAPA has a map editor that helps you take advantage of this power, as seen in figure @@ -2697,7 +2706,7 @@ Finish In the example figure, there are two paths the student can go down, depending on whether or not they get the problem at the branch point correct. By the end of this section, we'll create the map represented in this figure. -\layout Standard +\layout Comment The branching ability can obviously be used to help the student understand the concept in the problem by having them go through some extra material @@ -2706,18 +2715,22 @@ The branching ability can obviously be u \layout Subsection Creating a Simple Map: Page +\begin_inset LatexCommand \index{Page} + +\end_inset + + \layout Standard -To add a resource to the map: +To create a simple page that joins several resources into one page: \layout Enumerate -Click on an unused light gray area. \begin_float fig \layout Standard \align center -\begin_inset Figure size 476 242 -file mapEditFirstClick.eps +\begin_inset Figure size 476 221 +file mapClickedStart.eps width 3 80 flags 9 @@ -2726,55 +2739,73 @@ flags 9 \layout Caption -Map Editor after clicking on the box labelled +Clicked Start in the Map Constructor +\begin_inset LatexCommand \label{Clicked Start Figure} + +\end_inset + + +\end_float +Click the Start box. + You'll see what you see in figure +\begin_inset LatexCommand \ref{Clicked Start Figure} + +\end_inset + +. + Click \begin_inset Quotes eld \end_inset -here +Link Resource \begin_inset Quotes erd \end_inset -. - -\begin_inset LatexCommand \label{Map Editor First Click Figure} + in the secondary window, then click on the Finish box. +\begin_float fig +\layout Standard +\align center + +\begin_inset Figure size 120 360 +file mapStraightened.eps +flags 9 \end_inset -\end_float - In figure -\begin_inset LatexCommand \ref{Map Editor First Click Figure} +\layout Caption + +Straightened Map +\begin_inset LatexCommand \label{Striaghtened map} \end_inset -, the map editor after clicking on the area labelled + +\end_float + After that, click \begin_inset Quotes eld \end_inset -here +straighten \begin_inset Quotes erd \end_inset - is shown. - In that figure, lines have been added to show where the box boundaries - are for the purposes of demonstration. - This is to allow you to stay in sync with this tutorial; normally this - doesn't matter. - -\begin_deeper -\layout Standard +. + You should see something like figure +\begin_inset LatexCommand \ref{Striaghtened map} -Note that the contents of the seperate window have changed. -\end_deeper +\end_inset + +. + This creates a simple map that flows from beginning to end. \layout Enumerate \begin_float fig \layout Standard \align center -\begin_inset Figure size 476 218 -file mapNewResource.eps -width 3 80 +\begin_inset Figure size 264 245 +file mapInsertResource.eps flags 9 \end_inset @@ -2782,31 +2813,31 @@ flags 9 \layout Caption -Map Resource Editor -\begin_inset LatexCommand \label{Map Resource Editor Figure} +Inserting a Resource +\begin_inset LatexCommand \label{Inserting a Resource Figure} \end_inset \end_float -Click on -\series bold -Insert Resource -\series default - in the secondary window. - A -\series bold -Resource -\series default - will appear in the map editor. - Click on the new Resource, and you'll get something like Figure -\begin_inset LatexCommand \ref{Map Resource Editor Figure} +To insert a resource into the flow, click the black line with two arrows. + In the secondary window, you'll see something like figure +\begin_inset LatexCommand \ref{Inserting a Resource Figure} \end_inset - will show appear. +. Click \series bold +Insert Resource Into Link +\series default +. + A new resource will appear in the link. + Click the resource. +\layout Enumerate + +Click +\series bold Browse \series default , and the @@ -2846,9 +2877,8 @@ Network Directory Browser \layout Standard \align center -\begin_inset Figure size 476 213 +\begin_inset Figure size 61 360 file mapEditorResourceChosen.eps -width 3 80 flags 9 \end_inset @@ -2861,7 +2891,7 @@ Resource Chosen \end_inset - (HTML page) + \end_float Once you've done that, if you look back at the window that popped up when you clicked on @@ -2882,7 +2912,8 @@ URL \series bold Title \series default - if you prefer, following the format you see above. + into the secondary window, if you prefer, following the format you see + above. After you click \series bold Save Changes @@ -2908,116 +2939,69 @@ Clicking on the left icon for a resource \end_deeper \layout Enumerate -Let's give practice giving ourselves a bit more space. - Click on the grey space just left of your resource, and select -\series bold -Insert Column Right -\series default -. - This will add a column to the right of that space. - Now, click on the bottom row in the grey area, and select -\series bold -Insert Row Above -\series default -. - This gives us enough space to work with. +Repeat steps two and three for as many resources as you'd like to bind together + into one page. + You can insert the new resources anywhere you'd like. \layout Enumerate -Now, in the map editor window, click just to the left of the +When you are done adding resources, click the \series bold -Res +Save Map \series default - box. -\begin_float fig -\layout Standard -\align center + link to save the map. +\layout Subsection -\begin_inset Figure size 357 190 -file mapSecondWindowSecondResource.eps -flags 9 +Creating Sequences +\begin_inset LatexCommand \index{Sequence} \end_inset -\layout Caption - -Choosing your second resource -\begin_inset LatexCommand \label{Map Second Resource Figure} - -\end_inset - +\layout Standard -\end_float - The secondary window will appear as it does in figure -\begin_inset LatexCommand \ref{Map Second Resource Figure} +Sequences are a series of resources that can be navigated using the +\series bold +NAV +\series default + remote control button, or by using the arrow keys on the remote control. + Sequence maps are created identically to page maps, the only difference + is how they are displayed. +\layout Subsection -\end_inset +Creating a Course: Top-level Sequence +\layout Standard -, but for now just choose +In order to view sequences, they need to be part of a \series bold -Insert Resource +course \series default - again, not the new options. - Insert a resource in the same manner as before. +. \begin_float fig \layout Standard \align center -\begin_inset Figure size 476 243 -file mapTwoResources.eps -width 3 80 -flags 11 +\begin_inset Figure size 422 410 +file creatingANewCourse.eps +flags 9 \end_inset \layout Caption -Two Resource in the Map Editor -\begin_inset LatexCommand \label{Two Resources in the Map Editor Figure} +Creating a New Course +\begin_inset LatexCommand \label{Creating a New Course Figure} \end_inset \end_float - You should have something that looks like figure -\begin_inset LatexCommand \ref{Two Resources in the Map Editor Figure} - -\end_inset - -, though the exact placement may differ. - Now we need to link them together. -\layout Enumerate - -Click the Start box. - In the secondary window, select -\series bold -Link Resource -\series default -. - The secondary window will prompt you to click on the resource you want - to link it to. - Click the first resource you added to the map. - A new link is created. -\layout Enumerate - -Repeat the last step, linking the first resource to the second resource, - and the second resource to -\series bold -Finish -\series default -. -\layout Enumerate - -Now, in the editor window, click -\series bold -Save Map -\series default -. - A dialog box will pop up, telling you the map has been saved. -\layout Standard - -Now that you + Courses have a Top-level Map which defines the whole course. + This top-level map will often itself contain maps corresponding to homework + assignments or weekly sequences. + To view your maps, you will need to make them part of a course. + Only Domain Administrators can make courses and set their Top-level maps, + so coordinate with your Domain Adminstrator if you need to create courses. \layout Section Numerical Response @@ -3030,7 +3014,7 @@ Numerical Response \end_inset - Problems + And Formula Response Questions \layout Standard Numerical Response problems are very powerful. @@ -3564,7 +3548,7 @@ very \emph default good idea to adopt some sort of commenting standard, especially if you are working in a group or others may use your problems in the future. -\layout Standard +\layout Itemize One of the simplest statements in LON-CAPA is a \series bold @@ -3911,7 +3895,79 @@ View Calling Functions \layout Standard -Now you've seen how to use variables and stuff, see how to call functions. +With variables, you can store strings or numbers. + +\series bold +Functions +\series default + allow you to manipulate these strings or numbers. + By stringing together a series of functions, you can do a lot. +\layout Standard + + +\series bold +Functions +\series default + work like mathematical functions: They take some number of arguments in, + and return one argument, usually a number or a string for our purposes. + There are a lot of functions available in LON-CAPA. + You can see a complete list at http://mileva.lite.msu.edu/loncapadocs/homework/hom +ework5.html. + For now, let's just look at some simple examples. +\layout Standard + +\begin_float fig +\layout LyX-Code + +$a = 3; +\layout LyX-Code + +$b = &sin($a); +\layout LyX-Code + +$c = &pow(3, &floor($a)); +\layout Caption + +Some Function Calls +\begin_inset LatexCommand \label{Some Function Calls Figure} + +\end_inset + + +\end_float +In the +\series bold +Script +\series default + block, function names start with +\series bold +& +\series default +. + Some example function calls are shown in figure +\begin_inset LatexCommand \ref{Some Function Calls Figure} + +\end_inset + +. + You can see that functions can take either variables, numbers, or the results + of other function calls as parameters. + The +\family typewriter +sin +\family default + function returns the sine of an angle expressed in radians. + +\family typewriter +pow +\family default + raises the first parameter to the power of the second parameter. + +\family typewriter +floor +\family default + returns the nearest integer below the parameter, which since 3 is already + an integer is 3. \layout Subsubsection Randomization @@ -3922,13 +3978,295 @@ Randomization \layout Standard -One of the most importent functions for LON-CAPA is the RANDOM function. +For LON-CAPA, one of the most importent functions is the +\family typewriter +random +\family default + function. + Random takes three parameters, a +\emph on +lower limit +\emph default +, an +\emph on +upper limit +\emph default +, and an +\emph on +interval +\emph default +. + The +\family typewriter +random +\family default + function returns a random value between the upper and lower limit, some + integer number of +\emph on +interval +\emph default +'s away from the lower limit. + Thus, for example, +\family typewriter +&rand(1,2,.2) +\family default + might return 1, 1.2, 1.4, 1.6, 1.8, or 2. + +\layout Standard + +\begin_float fig +\layout LyX-Code + +$a = &random(1,10,1); +\layout LyX-Code + +$b = &random(-10, -3, 1); +\layout LyX-Code + +$answer = $a+$b; +\layout Caption + +Sample +\family typewriter +random +\family default + Calls +\begin_inset LatexCommand \label{Sample Random Calls figure} + +\end_inset + + +\end_float +If you put the script in figure +\begin_inset LatexCommand \ref{Sample Random Calls figure} + +\end_inset + + into the +\series bold +Script +\series default + block (replacing whatever contents might be in the block already), you'll + get two random variables $a and $b. + Now, in the +\series bold +Text Block +\series default +, put +\begin_inset Quotes eld +\end_inset + +What is $a plus $b? +\begin_inset Quotes erd +\end_inset + +, and in the +\series bold +Answer +\series default + put +\begin_inset Quotes eld +\end_inset + +$answer +\begin_inset Quotes erd +\end_inset + +, without the quotes for either of them. + (It is a good idea to create a variable to hold the answer and call it + $answer. + Do not try to compute the answer in the +\series bold +Answer +\series default + field itself; it will not work as you expect.) Now save the problem and + +\series bold +View +\series default + it. + You'll see a randomized problem. +\layout Standard + +For each student, the same random number will be used each time they visit + the problem, but each student will get different random numbers. + For any but the simplest random problems, you'll want to see several random + problems to make sure everything is working out correctly. + This is what the +\series bold +Random Seed +\begin_inset LatexCommand \index{Random Seed} + +\end_inset + + +\series default + field is for. + To see another randomized version of the problem you've just created, put + another number into the +\series bold +Random Seed +\series default + field and hit +\series bold +Change +\series default +. + It doesn't really matter what number you put into the field. + But for any given +\series bold +Random Seed +\series default + with the same problem, you'll see the same randomized problem generated + for you. + (If you change the +\series bold +Script +\series default +, you are no longer guarenteed to get the same problem.) +\layout Standard + +If you're doing this as a tutorial, try a few random seeds to see what happens. \layout Subsection Dynamic, Randomized Problems: Putting It All Together \layout Standard -placeholder +Now you have all the tools to create those wonderful dynamic, randomized + problems that you've seen in LON-CAPA. +\begin_float fig +\layout Standard +\align center + +\begin_inset Figure size 476 197 +file numericalResponseSlopeProblem.eps +width 3 80 +flags 9 + +\end_inset + + +\layout Caption + +Slope Problem Parameters +\begin_inset LatexCommand \label{Slope Problem Parameters Figure} + +\end_inset + + +\end_float + For example, try filling out your problem with the parameters shown in + figure +\begin_inset LatexCommand \ref{Slope Problem Parameters Figure} + +\end_inset + +. + +\layout Standard + +When creating randomized problems, you want to make sure that the problems + always have an answer! Consider what might happen if I had chosen the two + slopes +\emph on +both +\emph default + with the expression +\family typewriter +&rand(-1,1,.2) +\family default +. + One out of ten students would get a problem where both slopes were equal, + which has either no solution (for unequal y-intercepts) or an infinite + number of solutions (for equal slopes and y-intercepts). + Both of these cause a division-by-zero error on the division that computes + the answer. + There are many ways to avoid this, one of the easiest of which is picking + one slope negative and one positive. + This same problem can show up in many other places, too, so be careful. +\layout Standard + +LON-CAPA has functions for several common random distributions; consult + the function list at http://mileva.lite.msu.edu/loncapadocs/homework/homework5.html + for a complete list and parameter specification. +\layout Subsection + +Units, Format +\layout Standard + +Numerical Response problems can require units. + In the problem editting form, place the desired unit in the +\series bold +Unit +\series default + field. + For information about what units the system accepts, see http://capa4.lite.msu.edu +/demolibrary/Links/UnitsSymbolsT2.html. + The computer will accept the answer in any of its accepted unit formats. + For example, if the answer to a problem is +\begin_inset Quotes eld +\end_inset + +1ft +\begin_inset Quotes erd +\end_inset + +, the computer will accept +\begin_inset Quotes eld +\end_inset + +12in +\begin_inset Quotes erd +\end_inset + + as correct. +\layout Standard + +Additionally, you can format the number displayed by the computer as the + answer. + For instance, if the answer is one-third, the computer will display that + it computed +\begin_inset Quotes eld +\end_inset + +.333333333 +\begin_inset Quotes erd +\end_inset + + as the answer. + If you'd like to shorten that, you can use the +\series bold +Format +\series default + field. + Format strings like +\begin_inset Quotes eld +\end_inset + +2e +\begin_inset Quotes erd +\end_inset + + (without the quotes) will display three significant digits in scientific + notation. + Format strings like +\begin_inset Quotes eld +\end_inset + +2f +\begin_inset Quotes erd +\end_inset + + will display three significant digit in traditional notation. + You can use any number that you want instead of +\begin_inset Quotes eld +\end_inset + +2 +\begin_inset Quotes erd +\end_inset + +. \layout Subsection For More Information @@ -3944,68 +4282,269 @@ Very often, the easiest way to create a \series default The more complicated a problem is, the more time you'll save by doing this. - Also, you may find new ideas you can use and elaborate in your problems. + You may also find new ideas you can use and elaborate on in your problems. \layout Comment Is there UI for this? Check. \layout Standard The full power of the Perl is well outside the scope of this document. - Without going into the same level of detail as the previous examples, here's - some ideas to stimulate your imagination: -\layout Itemize + Looking in the function list at http://mileva.lite.msu.edu/loncapadocs/homework/ho +mework5.html can give you some ideas. + O'Reilly has some good Perl books. + The Perl 5 pocket reference will contain more then what you need to know + to use LON-CAPA, available at http://www.oreilly.com/catalog/perlpr3/ . +\layout Standard + +If you have any problems, consult http://help.loncapa.org/fom/cache/5.html + . + If you don't find the answer to your problem, please help us expand the + FAQ by emailing us your question so we can answer it. +\layout Standard + +Our advanced users often come to prefer the XML interface for the problems, + available through the +\series bold +EditXML +\series default + buttons. + Covering the XML format is beyond the scope of this manual, but you can + learn a lot by using the editor to make changes and seeing what happens + to the XML. +\layout Subsection + +Formula Response +\begin_inset LatexCommand \index{Formula Response} + +\end_inset + + +\begin_inset LatexCommand \label{Formula Response} + +\end_inset -Variable text. + Problems +\layout Standard + +\begin_float fig +\layout Standard +\align center + +\begin_inset Figure size 476 262 +file formulaResponse.eps +width 3 80 +flags 9 + +\end_inset + + +\layout Caption + +Formula Response Problem +\end_float +Formula response problems asks the student to type in a formula as an answer. + If the answer is +\begin_inset Formula \( 2x^{2}+4 \) +\end_inset + +, the student is allowed to type +\begin_inset Quotes eld +\end_inset + +2*x*x+4 +\begin_inset Quotes erd +\end_inset + +, +\begin_inset Quotes eld +\end_inset + +x*x + x*x + 4 +\begin_inset Quotes erd +\end_inset + +, +\begin_inset Quotes eld +\end_inset + +2*x^2 + 14 - 10 +\begin_inset Quotes erd +\end_inset + +, or any other equivalent expression. + Formula Response problems have many of the same characteristics of Numerical + Response problems, including the ability to run scripts, dynamically generate + answers, etc. +\layout Standard + +As you may know, it is extremely difficult to determine whether a given + expression is exactly equal to another expression in general. + For example, is +\begin_inset Formula \( \sin 2x=2\sin x\cos x \) +\end_inset + +? Symbolically proving it one way or another is impossible in general. + Therefore, LON-CAPA uses a sampling system. + If your answer and the student's answer agree at the sampling points within + your given tolerance factor, the student's answer will be accepted, otherwise + it will be rejected. +\layout Comment + +What's up with the x,y@1,2:4,3#2 stuff? +\layout Standard + +Formula Response problems are otherwise virtually identical to Numeric Response + problems. +\layout Subsubsection + +Sample Point Specifications +\begin_inset LatexCommand \index{Sample Points} + +\end_inset + + +\layout Standard + +To specific the sample points, use the following format: +\layout Itemize + +a comma seperated list of the variables you wish to have sampled, +\layout Itemize + +followed by an @ +\layout Itemize + +followed by a comma seperated list of values as long as your list of variables, + representing the sample points \layout Itemize -Perl has several other data structures which might be of use. - You may wish to do one of the many simple Perl tutorials on the Web. - I recommend searching Google for +optionally followed by a semi-colon, and more comma seperated lists as in + the previous item. +\layout Standard + +For +\begin_inset Formula \( 2x^{2}+4 \) +\end_inset + +, with one variable \begin_inset Quotes eld \end_inset -perl tutorial +x +\begin_inset Quotes erd +\end_inset + +, one could specify +\begin_inset Quotes eld +\end_inset + +x@2 +\begin_inset Quotes erd +\end_inset + + or +\begin_inset Quotes eld +\end_inset + +x@2;3;4;5 \begin_inset Quotes erd \end_inset . -\layout Section + (It is generally a good idea to give a few sample points.) For +\begin_inset Formula \( 2y^{3}+2x \) +\end_inset -Formula Response -\begin_inset LatexCommand \index{Formula Response} +, with two variables, one could specify +\begin_inset Quotes eld +\end_inset +x,y@1,2;1,3;2,3;2,2 +\begin_inset Quotes erd \end_inset +. + +\layout Subsubsection + +Example Formula Response +\layout Standard -\begin_inset LatexCommand \label{Formula Response} +A very simple formula response problem: +\layout Standard + +In the +\series bold +Script +\series default +, place the following: +\layout LyX-Code + +$slope = random(1,5,.5); +\layout LyX-Code +$yint = random(1,5,.5); +\layout Standard + +In the +\series bold +Text Block +\series default +, place the following: +\begin_inset Quotes eld \end_inset - Problems -\layout Section +For a line with slope $slope and y-intercept $yint, what is y equal to? +\begin_inset Quotes erd +\end_inset + + +\layout Standard + +In the +\series bold +Answer +\series default +, place the following: +\begin_inset Quotes eld +\end_inset + +$slope*x + $yint +\begin_inset Quotes erd +\end_inset + + +\layout Standard -Additional Problem Components +Set the Tolerence to 1%. \layout Standard -Using the +Set the +\series bold +Answer +\series default + to \begin_inset Quotes eld \end_inset -Insert +$slope * x + $yint \begin_inset Quotes erd \end_inset - menu that appears in many of the problem editors, a wide variety of different - things can be added to the problems. +. +\layout Standard + +Set the +\series bold +Sample Points +\series default + to x@0,1,2,3 . \layout Section Things That Need To Be Added \layout Subsection -LON-CAPA and Units -\layout Subsection - Creating a default metadata file \layout Subsection @@ -4013,16 +4552,6 @@ My questions\SpecialChar \ldots{} \layout Itemize -How do I do the things above? -\layout Itemize - -Is there any pre-existing documentation for number or formula problems? -\layout Itemize - -Is there any pre-existing documentation for maps et al? I seem to have exhausted - the documentation. -\layout Itemize - What is the LON-CAPA default resource? If it's free, can just anyone \begin_inset Quotes eld \end_inset @@ -4041,6 +4570,9 @@ use it if they already know where it is ? (In other words, how powerful is the search feature?) What's the difference between free and public? +\layout Itemize + +How do I look at a map? (Must be part of course?) \layout Section Appendix A: Student Interface