New Sample problems for WeBWorK

[pstaabp]

So I decided to go ahead and try the idea we talked about yesterday with regards to sample problems. I have a proof of concept that takes a sample pg file, embeds

• markers within comments that determine what code snippet of a problem we want to show
• the related explanation code.

The latter I put in a __DATA__ at the bottom of the pg file and have it as yaml with embedded html markup.

Here's a sample PG file with everything embedded:

#:preamble:begin
DOCUMENT();

loadMacros('PGstandard.pl','MathObjects.pl','contextLimitedPolynomial.pl',
  'AnswerFormatHelp.pl','PGML.pl','PGcourse.pl');

TEXT(beginproblem());
#:preamble:end

$showPartialCorrectAnswers = 1;

###########################
#  Setup

#:setup:begin
# Vertex form
Context('Numeric');
$h = 3;
$k = 5;
$vertexform = Compute("(x-$h)^2-$k");


# Expanded form
Context('LimitedPolynomial-Strict');
$b = -2 * $h;
$c = $h**2 - $k;
$expandedform = Formula("x^2 + $b x + $c")->reduce();
#:setup:end

###########################
#  Main text

#:statement:begin
BEGIN_PGML
The quadratic expression [` [$vertexform] `]
is written in vertex form.  Write the
expression in expanded form [` ax^2 + bx + c `].

[_____________________]{$expandedform}

[@ helpLink('formulas') @]*
END_PGML
#:statement:end

############################
#  Solution

#:solution:begin
BEGIN_PGML_SOLUTION
Solution explanation goes here.
END_PGML_SOLUTION

ENDDOCUMENT();
#:solution:end

__DATA__
---
preamble: |
    <b>Preamble:</b>
    <p>We need to load <code>contextLimitedPolynomial.pl</code></p>
setup: |
    <p>
    <b>Setup:</b>
    The macro <code>contextLimitedPolynomial.pl</code> provides two contexts:
    </p>
    <pre>Context("LimitedPolynomial");
    Context("LimitedPolynomial-Strict");
    </pre>
    <p>The strict version does not allow any mathematical operations within coefficients, so <code>(5+3)x</code> must be simplified to <code>8x</code>.
    For more details, see <a rel="nofollow" class="external text" href="http://webwork.maa.org/pod/pg/macros/contextLimitedPolynomial.html">contextLimitedPolynomial.pl</a>
    </p>
    <p>
    The strict version does not allow any mathematical operations within coefficients, so
    <code>(5+3)x</code>
    must be simplified to
    <code>8x</code>
    </p>
    <p>
    We use the <code>LimitedPolynomial-Strict</code> context, construct the coefficients <code>$b</code> and <code>$c</code> as Perl reals, and then construct <code>$expandedform</code> using these pre-computed coefficients.  This is because the LimitedPolynomial-Strict context balks at answers that are not already simplified completely.  Notice that we called the <code>-&gt;reduce()</code> method on the expanded form of the polynomial, which will ensure that the polynomial will be displayed as <code>x^2 - 6x + 4</code> instead of <code>x^2 + -6x + 4</code>.
    </p>
statement: |
    <b>Problem Statement:</b>
    <p>To help students understand how to format their answers, we give an example <code>ax^2+bx+c</code> of what the answer should look like.</p>
solution: |
    <b>Solution:</b>

I wrote a small script to parse the file, pull out the code blocks, parse the explanation and output to an html file. Here's an example:

with some of the similar styling to the wiki, but we should work to a new style with coloring for the code (code mirror?)

I think we also use GitHub actions to automate this and probably simplest to use GitHub pages to serve the sample problems.

I'm not wed to any particular thing I did here, but wanted to test out to see how easy it would be to do this.

Anyway, had an itch and scratched it. Thoughts?

[pstaabp]

Worked a bit more on this and will probably submit as a draft PR. More thoughts:

• Move sample problems into webwork2/doc/sample_problems
• Add some formatting to each sample problem to make it parseable.

Then I have a script that parses the file similar to what I have above, use a Mojolicious template to convert to HTML. This script now parses all .pg problems in a directory (should work recursively) and creates a HTML version like above.

I'm also thinking the results could be put in a separate repository on GitHub (say webwork2-docs) as use GitHub pages to serve them. I think we can make a GitHub action to automate a lot of this.

[somiaj]

I have a few thoughts. First the simple one, shouldn't these problems live in pg/ and not webwork2/, since they are for PG. webwork should have a way to import them as templates to add to problems, but I think PG is the better place to store them (since they may be used by more than just webwork2). I also think the problems should be a part of pg/webwork (not a separate repo) so we can create a way to add them as templates directly to assignments for people to use. A github action could copy them to a separate repo if they are needing to be served somewhere.

Second, I think your format is a bit too complicated for this. I have some ideas, not a full description, but I think we should use markdown (instead of html), since this will help keep things more uniformly formatted and be easier to write/maintain, and I think the actual .pg file should look something like this:

## Initial comments (including headers for the OPL or just other info).
# This will be silently ignored.


#: option1:value1 option2:value2 option3:value3
#:
#: markdown for the description of the first block goes here
#:
DOCUMENT();

loadMacros('PGstandard.pl','MathObjects.pl','contextLimitedPolynomial.pl',
  'AnswerFormatHelp.pl','PGML.pl','PGcourse.pl');

$showPartialCorrectAnswers = 1;

#: options:values
#:
#: markdown for the description for the second block goes here
# Vertex form
Context('Numeric');
$h = random(2,5,1);
$k = random(4,8,1);
$vertexform = Compute("(x-$h)^2-$k");


# Expanded form
Context('LimitedPolynomial-Strict');
$b = -2 * $h;
$c = $h**2 - $k;
$expandedform = Formula("x^2 + $b x + $c")->reduce();

#: options:values
#:
#: markdown for the description of the PGML block goes here
#:
BEGIN_PGML
The quadratic expression [` [$vertexform] `]
is written in vertex form.  Write the
expression in expanded form [` ax^2 + bx + c `].

[_____________________]{$expandedform}

[@ helpLink('formulas') @]*
END_PGML

#: options:values
#:
#: markdown for the description of the solution block goes here
#:
BEGIN_PGML_SOLUTION
Solution explanation goes here.
END_PGML_SOLUTION

ENDDOCUMENT();

Basic idea is to have some symbol that is a comment like #: (alternatives like #% could also work) that identifies the sections and markdown blocks to be processed. The parser will then search for all of the #: blocks, use the info inside the block to format the description, and then use everything after the block up to the next block (or end of file) for the code.

The first row (or maybe multiple rows if needed) of each markdown block can contain some configuration information in the form option:value, such as section:preamble which will use the color blue and create a preamble section from the markdown, or other things like color:green and so on (I don't think to much is needed here but a few things could be useful). The rest of the block will be run through a markdown to html converter that will generate the wiki.

Some other thoughts are that the problems should have very minimal comments (the description block should be describing what things are). Otherwise if there are too many comments these will just get copy/pasted into each problem built from the template.

The wiki should include a link to the full .pg file (not split into different blocks) in which all of the markdown blocks, #: have been removed. This way there is an easy to copy template that someone can download (or add directly to a problem from inside of webwork).

Anyways, when I was thinking about this, I would have approached it as described here, not a complete description, but a basic idea I had.

[pstaabp]

@somiaj i was thinking that we should use markdown and I like your formatting ideas. I think it shouldn’t be too difficult to parse.

I also was thinking along the same lines with you about providing the full file available with all of the markdown stripped out. I’ll try to play with this. My thought was to have this as either a link in the file or available in a collapsible text area.

Lastly.I think it probably does belong in PG and I think this seems like something we can get done before the full release this summer.

[pstaabp]

Here's some new ideas. For a given block that we want comments on, we need the comments as well as markers where to include code. I think it will be too difficult to "guess" where these are, so here's an example, where there are begin, code and end markers for a given block. In this case: statement for the problem statement.

#:statement:begin
#:To help students understand how to format their answers, we give an example
#:`ax^2+bx+c` of what the answer should look like.
#:statement:code
BEGIN_PGML
The quadratic expression [` [$vertexform] `]
is written in vertex form.  Write the
expression in expanded form [` ax^2 + bx + c `].

[___]{$expandedform}

[@ helpLink('formulas') @]*
END_PGML
#:statement:end

Also, easily parsed all #: comments out for a copyable version of the file. I think I'll move this to PG and open a draft PR for additional comments.

[somiaj]

Here's some new ideas. For a given block that we want comments on, we need the comments as well as markers where to include code. I think it will be too difficult to "guess" where these are, so here's an example, where there are begin, code and end markers for a given block. In this case: statement for the problem statement.

I still don't see the reason we need start, code, end, tags, as we can easily identify these regions (without guessing) using the #: block tags. The #:foo:start always appears right before a block of lines that start with #:, so we can identify the start by looking for where #: blocks start, the #:statement:code is right at the end of a #: block, so we can just look for blocks of #: and we get the full description without start/stop tags. Same for the code that follows, the code ends where a new #: block starts.

Last if we want to be able to ignore a block of code, we could set up a an option to ignore the code so a block that does #:display:none (or some other tag) will say that the #: description block and all the code that follows won't appear in the wiki.

Looks good, I just don't think the start/code/end tags are needed (it makes the format a little bit more restrictive, which is fine to me).

[pstaabp]

I see what you mean about cluttering the code a bit. I was thinking that there may be blocks of code that we don't want in the documentation and that this would allow for such flexibility. But perhaps thinking again about it, maybe we always want the entire code in the documentation and that your method would push us in this direction.

Let me try this and see if it seems flexible enough.

[somiaj]

I have something I'm working on and almost done with to show you how this works. I'll throw up a patch to your branch soon.

[pstaabp]

I just put in a draft PR for this in openwebwork/pg#811