Merge pull request #2358 from Alex-Jordan/student-orientation

new Student Orientation

assets/pg/Student_Orientation/decimals.pg

@@ -0,0 +1,54 @@
+## DESCRIPTION
+## Decimal Tolerance
+## ENDDESCRIPTION
+
+DOCUMENT();
+
+loadMacros(qw(
+    PGstandard.pl
+    PGML.pl
+    contextFraction.pl
+    PGcourse.pl
+));
+
+BEGIN_PGML
+## Decimal Approximations
+
+Sometimes, your instructor will require you to enter an answer _exactly_. In that case your only option is to enter
+[:1/3:] as a fraction: [`\frac13={}`][_]{Context("LimitedFraction"), Fraction(1/3)}{4}  (Try [|1/3|]*, [|0.33|]*,
+[|0.333|]*, [|0.3333|]*, [|2/6|]*, etc.)
+
+Sometimes, you will be allowed to use decimal _approximations_ to the real answer. So for instance, in the next answer
+blank we can get away with typing [|0.3333|]* even though that is slightly different from [:1/3:].
+[`\frac13={}`][_]{Context("Numeric"), Real(1/3)}{4}  (Try [|0.33|]*, [|0.333|]*, [|0.3333|]*.) Why is [|0.3333|]*
+accepted and [|0.33|]* is not? _If_ a decimal approximation is acceptable at all, then you need to use enough
+significant digits so your answer is "close enough" to the actual correct answer (which was [:1/3:] in this case). In
+general, using _four_ significant digits in your decimals will be enough. You will often be able to get away with fewer,
+but using four is recommended.
+
+Use a calculator to find decimal approximations for these values. At first, round your calculator's output to just two
+significant digits. Then move up to three. If that is still not enough, move up to four.
+
+    [`\sqrt{110} =`] [_]{sqrt(110)} (Try [|10|]*, [|10.4|]*, [|10.5|]*, [|10.48|]*, [|10.49|]*, etc.)
+
+    [`\frac{1}{491} =`] [_]{1/491}{4} (Try [|0.0020|]*, [|0.00203|]*, [|0.00204|]*,
+[|0.002036|]*, etc.)
+
+    [`20380.2 =`] [_]{20380.2}{4} (Try [|20000|]*, [|20300|]*, [|20400|]*, [|20380|]*, etc.)
+
+With [`\frac{1}{491}`], students sometimes feel they should be able to get away with [`0.002`], since that is only off
+by a tiny amount. However, percentage-wise this would be off by [`1.8%`], which is generally considered too much.
+
+With [`20380.2`], students mistakenly believe they must enter the entire number. While that's fine, it's also OK to
+round to four significant digits. So you may simply enter [`20380`] for this answer.
+
+Decimal tolerance settings may vary from problem to problem and the above is only describing default decimal tolerance.
+For example, if a problem has a monetary answer, it might expect you to answer correctly all the way to the hundredths
+place, even if it is a large amount in thousands of dollars. Watch out for any specific instructions in each problem
+that tell you how precise you should be.
+
+
+[@ MODES(HTML => 'When you are ready, click "Next Problem".', TeX => '') @]
+END_PGML
+
+ENDDOCUMENT();

assets/pg/Student_Orientation/emailInstructor.pg

@@ -0,0 +1,40 @@
+## DESCRIPTION
+## Email Instructor
+## ENDDESCRIPTION
+
+DOCUMENT();
+
+loadMacros(qw(
+    PGstandard.pl
+    PGML.pl
+    PGcourse.pl
+));
+
+$a           = random(5, 10);
+$button_name = $envir{feedback_button_name};
+
+BEGIN_PGML
+## [$button_name]
+
+If you feel stuck on a problem, do not understand what the problem asks for, suspect there is a bug with the problem,
+do not understand what syntax to use to enter the answer, or all of the above, there is an "[$button_name]" button
+below the problem that you may use. This button appears on other pages in WeBWorK too.
+
+When you use this button, you should write a message to your instructor (or TA) explaining what you have tried. It will
+help a lot if you write down the steps of the math that you have worked out too. You can even attach a file, for example
+a picture of your hand-written work. Then the instructor gets your message along with a link to the problem from _your
+perspective_, and they can also see all of your previously attempted answers. This way your instructor can write you
+back with good help/hints.
+
+This answer blank is expecting a certain mystery answer: [_]{Real(112358)->cmp(tolType=>'absolute',tolerance=>0.1)}{4}.
+The only way to get the answer is to use the "[$button_name]" button and ask for the answer to this Orientation Problem
+[$envir{probNum}]. The instructor will reply to your email as soon as they are able to. [@ if ($isInstructor)
+{'(Instructors: you can Check/Submit an answer, then view the feedback to reveal the expected correct answer.)'} @]
+
+A reply will come in the form of an email. You must check your official email account to receive the reply. Then return
+to this problem to submit your answer.
+
+[@ MODES(HTML => 'When you are ready, click "Next Problem".', TeX => '') @]
+END_PGML
+
+ENDDOCUMENT();

assets/pg/Student_Orientation/enteringMath.pg

@@ -0,0 +1,104 @@
+## DESCRIPTION
+## Entering Math
+## ENDDESCRIPTION
+
+DOCUMENT();
+
+loadMacros(qw(
+    PGstandard.pl
+    PGML.pl
+    PGcourse.pl
+));
+
+$MathQuill = <<END_BODY;
+When you click into an answer blank, a math tool palette should appear off to the right on your screen. Try clicking in
+the following answer blank and using buttons from the palette to help enter the expression [::pi/sqrt(x+1)::].
+[_]{Context("Numeric"), 'pi/sqrt(x+1)'}{16}
+
+Almost everyting the palette tool can do can be done with typing alone. For the next asnwer blank, enter the same answer
+as before, but ignore the palette tool and type it all out. You can type characters [|pi/sqrtx+1|]* and watch as the
+expression automatically is converted to look like [::pi/sqrt(x+1)::]. [_]{Context("Numeric"), 'pi/sqrt(x+1)'}{16}
+
+Occasionally you will want to answer with raw text that should not be converted into a math expression. For example, if
+the answer is a word. For this kind of answer, you should enter "text mode". There is a "Tt" button on the palette  that
+enters and exits text mode. You can also use the [|"|]* character to enter text mode, and then exit with the [|tab|]*
+key or right arrow. Try answering the following with and without using text mode. The answer is [|pirate|]*:
+[_]{Context("Numeric")->strings->add(pirate => {}), 'pirate'}{16}.
+
+The palette tool might be a distraction, especially to keyboard-only using students. You can disable it by
+right-clicking (or control-clicking) in an answer blank. To "right click" without a mouse:
+* on Windows or Linux, use [|shift F10|]*.
+* on a Mac, you must first enable Mouse Keys in System Settings, and then use [|control m|]*.
+
+Try to disable the palette tool now. Once the tool is diabled, your device and web browser should "remember" this
+setting when you visit a new problem or log in again. To bring the palette tool back, right-click (or control-click)
+again in an answer blank. Unless you are certain you do not want to use the palette tool, you should bring it back now.
+END_BODY
+
+$MathView = <<END_BODY;
+When you want to enter an answer, you might want some assistance understanding how to type it and what your answer looks
+like after it is formatted as a math expression. To the right of each answer blank there is a button[@
+    MODES(
+        HTML => ' <button class="btn btn-sm btn-secondary codeshard-btn" disabled><i class="fa-solid fa-th"/></button>',
+        TeX => ''
+    )
+@]* you can use to reveal a palette with tools for constructing math expressions as well as a preview of what the
+expression will look like. Try using the palette to help enter the expression [::pi/sqrt(x+1)::]. For this particular
+expression:
+1. You should start with the fraction building button for [`\frac{a}{b}`]. It will insert [|()/()|]* into the answer
+blank.
+2. Now place the cursor inside the first set of parentheses. Use the "Operations" list to visit "Others", where you can
+click the [`\pi`] button. This will insert [|pi|]* and your answer blank should have [|(pi)/()|]*.
+3. Now place the cursor inside the second set of parentheses. Use the "Operations" list to visit "Exponents", where you
+can click the [`\sqrt{a}`] button. Now your answer blank looks like [|(pi)/(sqrt())|]*.
+4. Finish by typing the [|x+1|]* in the appropriate place.
+
+    [_]{Context("Numeric"), 'pi/sqrt(x+1)'}{16}
+
+Of course, you might be comfortable directly typing your answer and you do not need to use the palette button.
+END_BODY
+
+$None = <<END_BODY;
+The four basic arithmetic operations are: [`+, -, \times, \div`] and each of these has a corresponding character on the
+keyboard. The first two are found in the upper right area of most keyboards. For [`\times`], we use the asterisk
+character [|*|]*. This is the shift-8 key on most keyboards. For [`\div`], we use the slash character [|/|]*. This is in
+the lower right of most keyboards.
+
+Try entering [`6\cdot5+2`] by typing it exactly as [|6*5 + 2|]*:
+
+    [_]{Compute('6*5+2')->cmp(formatStudentAnswer=>'parsed')}{16}
+
+Of course you could also simplify this to [`32`]. Now try entering [:1/x:]:
+
+    [_]{'1/x'}{16}
+
+Raising to a power is typed using the caret symbol [|^|]*, which is usually shift-6 on a keyboard. Try entering [:x^6:]:
+
+    [_]{'x^6'}{16}
+
+Another common operation is the square root, which is written [`\sqrt{\phantom{x}}`] on paper. There is no square root
+character on most keyboards, so we do something else with this operation. We use [|sqrt()|]* where the parentheses
+should surround the same content covered by the radical in [`\sqrt{\phantom{x}}`]. Try entering [:sqrt(x+1):]:
+
+    [_]{'sqrt(x+1)'}{16}
+
+Complex expressions will require you to understand the order of operations and use grouping symbols. Teaching the order
+of operations might be part of the course you are taking or it might be something you are expected to already know. Here
+is an example of a complex math expression: [::(x^(x+1)+2)/(x+3)::]. Naively, you might type this as [|x^x+1+2/x+3|]*,
+but the order of operations would make that come out as [::x^x+1+2/x+3::]. We need to use grouping symbols to (1) make
+sure all of the [:x+1:] is included in the exponent, and (2) group the entire numerator and denominator together. We
+would need something like [|(x^(x+1)+2)/(x+3)|]*. Try entering [::3^(x+1)/(2(x+2)^2)::].
+
+    [_]{'3^(x+1)/(2(x+2)^2)'}{16}
+
+END_BODY
+
+BEGIN_PGML
+## Entering Math
+
+[@ if ($envir{entryAssist} eq 'MathQuill') {$MathQuill} elsif ($envir{entryAssist} eq 'MathView') {$MathView} else {$None} @]**
+
+[@ MODES(HTML => 'When you are ready, click "Next Problem".', TeX => '') @]
+END_PGML
+
+ENDDOCUMENT();

assets/pg/Student_Orientation/feedback.pg

@@ -0,0 +1,68 @@
+## DESCRIPTION
+## Accessing Feedback
+## ENDDESCRIPTION
+
+DOCUMENT();
+
+loadMacros(qw(
+    PGstandard.pl
+    PGML.pl
+    PGcourse.pl
+));
+
+$random = random(100, 900);
+$answer = Real($random)->cmp(
+    checker => sub {
+        my ($c, $s, $a) = @_;
+        Value::Error("The correct answer is $random.")
+            unless ($s == $random);
+        return 1;
+    }
+);
+
+BEGIN_PGML
+## Feedback
+
+When you Submit an answer, a feedback button appears near the answer blank.
+
+* If you answer correctly, you see a green checkmark[@
+    MODES(
+        HTML => ': <button class="ww-feedback-btn btn btn-sm btn-success" disabled><i class="correct"></i></button>',
+        TeX => ''
+    )@]*.
+* If you answer incorrectly, you see a red alert[@
+    MODES(
+        HTML => ': <button class="ww-feedback-btn btn btn-sm btn-danger" disabled><i class="incorrect"></i></button>',
+        TeX => ''
+    )@]*.
+* If you earn partial credit, you see a yellow warning[@
+    MODES(
+        HTML => ': <button class="ww-feedback-btn btn btn-sm btn-warning" disabled><i class="partially-correct"></i></button>',
+        TeX => ''
+    )@]*.
+
+Each of these buttons is something you can click to see more information about the answer you tried. And if there is an
+actual feedback message, you will see a small circle in the upper right corner of the button[@
+    MODES(
+        HTML => ', like <button class="ww-feedback-btn btn btn-sm btn-danger with-message" disabled><i class="incorrect"></i></button>',
+        TeX => ''
+    )@]*.
+
+For example, try answering the following with any answer. Almost certainly, you will be marked incorrect, but the
+feedback message will tell you the correct answer. What number am I thinking of?  [_]{$answer}{4}
+
+If you type an answer and click to "Preview my Answers", you will see an info button[@
+    MODES(
+        HTML => ': <button class="ww-feedback-btn btn btn-sm btn-info" disabled><i/></button>',
+        TeX => ''
+    )
+@]* instead of the correct/incorrect buttons.
+
+In addition to automated feedback, your instructor can leave messages for you in WeBWorK. To see these messages, you
+must visit the problem for which a message has been left. The message will appear above the exercise. If your course
+uses essay questions, there is no automated feedback, and these messages from the instructor will be your only feedback.
+
+[@ MODES(HTML => 'When you are ready, click "Next Problem".', TeX => '') @]
+END_PGML
+
+ENDDOCUMENT();

assets/pg/Student_Orientation/hardcopy.pg

@@ -0,0 +1,37 @@
+## DESCRIPTION
+## Hardcopies
+## ENDDESCRIPTION
+
+DOCUMENT();
+
+loadMacros(qw(
+    PGstandard.pl
+    PGML.pl
+    PGcourse.pl
+));
+
+$a = random(100, 900);
+
+BEGIN_PGML
+## PDF Hardcopy ##
+
+From the *Assignments* page (which you may or may not have permission to viist), you may push a download button[@
+    MODES(
+        HTML => ' <i class="hardcopy-tooltip icon far fa-arrow-alt-circle-down fa-lg"></i>',
+        TeX => ''
+    )
+@]* to download a PDF version. Alternatively, when you are at the page listing all of one set's exercises, there is a
+"Download Hardcopy for Current Set" button.
+
+This file is something that you can read onscreen while you are offline. You can even print it off and take it to a
+tutoring center or somewhere comfortable to work on.
+
+To check that you understand how this works, download the PDF version of this Orientation assignment. At the end of
+this problem in the PDF, you will find the answer that is expected here: [_]{Compute("$a")}{4}
+
+[@ if ($displayMode eq 'TeX') {"The answer is $a."} @]
+
+[@ MODES(HTML => 'When you are ready, click "Next Problem".', TeX => '') @]
+END_PGML
+
+ENDDOCUMENT();

assets/pg/Student_Orientation/miscellaneous.pg

@@ -0,0 +1,60 @@
+## DESCRIPTION
+## Miscellaneous
+## ENDDESCRIPTION
+
+DOCUMENT();
+
+loadMacros(qw(
+    PGstandard.pl
+    PGML.pl
+    PGcourse.pl
+));
+
+BEGIN_PGML
+## Miscellaneous ##
+
+Here are more WeBWorK features.
+
+* After an assignment is due, you are typically able to see the answers to all questions by visiting an exercise,
+checking an answer, and viewing the feedback. Also when downloading the hardcopy PDF, you have the option to show the
+expected correct answers.
+* Some problems have been coded with walk-through solutions. You will not be able to see these until it's also possible
+for you to see the answers.
+* Some problems have been coded with hints. You will not be able to see these until you've attempted the problem a
+certain number of times.
+* Once the due date has passed, you can still enter answers in the answer blanks and use the "Check" button, and WeBWorK
+will still give you the same feedback; just not for credit.
+* Captial letters are different than lowercase letters when it comes to variables. For exmaple, [`\pi r^2`] might be
+correct while [`\pi R^2`] is not.
+* When you click on a problem set, there is set-specific information in a panel to the right. Always read this before
+you begin the problems set. It may give you important hints.
+*  Repeated guessing is not helpful.  If you have gotten a problem incorrect several times, you should ask for help.
+That's what your instructor, TAs, and tutors are here for.
+* Make sure you read the feedback messages that WeBWorK gives you. The feedback messages might sometimes be "technical"
+(either mathematically or with respect to WeBWorK syntax) but they often give you what you need to make some progress.
+If you don't understand a feedback message, ask your instructor about it.
+* For decimal answers, get in the habit of using four significant digits.
+* If you want to enter [`\pi`], you could type [|pi|]*, use the palette tool, or directly enter the [`\pi`] character if
+you have a way to do that.
+* If you want to enter [`\infty`], you could type [|inf|]*, use the palette tool, or directly enter the [`\infty`]
+character if you have a way to do that.
+* All of your submissions are permanently recorded. That means you can log off at any time and all of your work will be
+saved. So you can do assignments in little bits at a time and work out of order if you like.
+* WeBWorK can be used on tablets and smartphones.
+* Most problems are coded with randomization. This means that while you and your classmate may have the same skeleton of
+a problem, the numbers invloved are different. This encourages you to teach each other the _process_ of answering a
+problem without being able to simply share the answers.
+
+The collection of all of the numbers between [`0`] and [`\pi`] including the endpoints is represented as [`[0,\pi]`] in
+interval notation. Practice entering [`[0,\pi]`] in the answer blank: [_]{Context("Interval"), Compute('[0,pi]')}{4}.
+
+What is the symbol that is used to represent a quantity that is conceptually larger than any number?
+[_]{Context("Numeric"), Compute('inf')}
+
+The answer to the following is something like [`\pi AB`], but that's not accepted because the actual answer has
+lowercase variables. What should it be? [_]{Context("Numeric")->variables->are(a => 'Real', b => 'Real'), 'piab'}
+
+This concludes the WeBWorK student orientation.
+END_PGML
+
+ENDDOCUMENT();