# Introduction to PGML

(Add basic formatting section) |
(Added PG interaction section) |
||

Line 5: | Line 5: | ||

PGML provides easy means of creating paragraphs, lists, headers, indentation, centering, and other formatting features. It also allows you to link the answer directly to its answer blank for easy problem maintenance. The underlying idea behind PGML is to make what you type as the text of the problem look as close to the result on screen as possible. | PGML provides easy means of creating paragraphs, lists, headers, indentation, centering, and other formatting features. It also allows you to link the answer directly to its answer blank for easy problem maintenance. The underlying idea behind PGML is to make what you type as the text of the problem look as close to the result on screen as possible. | ||

− | PGML is for creating the ''text'' of the problem and for associating answers to their answer blanks. The setup and computational portion of the problem is still done in the traditional way. PGML integrates with MathObjects to make it easy to work with answers and answer checkers, and to present mathematics within the text of your problem. | + | PGML is for creating the ''text'' of the problem and for associating answers to their answer blanks. The setup and computational portion of the problem is still done in the traditional way. PGML integrates with [[:Category:MathObjects|MathObjects]] to make it easy to work with answers and answer checkers, and to present mathematics within the text of your problem. |

PGML can also be used to create the solutions to your problem, with many of the same advantages that you have for the text of the problem itself. | PGML can also be used to create the solutions to your problem, with many of the same advantages that you have for the text of the problem itself. | ||

Line 193: | Line 193: | ||

== Interaction with PG == | == Interaction with PG == | ||

− | answer | + | There are two important ways that PGML must interact with the rest of the PG problem: inserting the values of perl variables into the problem (e.g., the randomized parameters for the problem), and making the answer blanks where students will enter their answers and tying those blanks to the correct answers. Both of these are easy to do, and are described below. |

− | variable | + | |

+ | === Variable Substitution === | ||

+ | |||

+ | To insert the value of a variable into your PGML text, enclose the variable name with <code>[...]</code>. For example, if you have a variable <code>$a</code> in your problem, then you can use | ||

+ | |||

+ | BEGIN_PGML | ||

+ | Suppose that a train leaves Chicago traveling [$a] miles per hour due south. | ||

+ | END_PGML | ||

+ | |||

+ | You can access array or hash entries similarly, e.g., <code>[$b[0]]</code> or <code>[$c{neg}]</code> or <code>[$d->{period}]</code>. | ||

+ | |||

+ | Note that a variable that holds a [[:Category:MathObjects|MathObject]] can produce either a TeX string or a calculator-notation string; which one it produces depends on the context in which it is used. If it is inserted inside of TeX math delimiters (e.g., inside <code>[`...`]</code>), it will produce its TeX form, while if it is inserted inside calculator delimiters (e.g., <code>[: ... :]</code>), or not inside any delimiters, then it produces calculator-style notation. So if <code>$f = Formula("(x+1)/(x-1)")</code>, then | ||

+ | |||

+ | Suppose [`f(x) = [$f]`]. | ||

+ | |||

+ | and | ||

+ | |||

+ | Suppose [:f(x) = [$f]:]. | ||

+ | |||

+ | will both produce properly formatted mathematical output with no special handling needed on your part. (Note that this is in sharp contrast to the traditional <code>BEGIN_TEXT/END_TEXT</code> approach, which requires you to handle the TeX versions specially.) | ||

+ | |||

+ | === Answer Blanks === | ||

+ | |||

+ | One of the key ingredients in any WeBWorK problem is answer blanks where students can enter their answers. In PGML, these are created using <code>[_____]</code>, where the number of underscores indicates how wide the answer blank should be. For example | ||

+ | |||

+ | If [: x = [$a] :], then the value of [: x^2 :] is [___________] | ||

+ | |||

+ | sets up an answer blank for the student to enter his or her value for <math>x^2</math>. The answer checker for this blank can be provided via <code>ANS()</code> in the traditional way. PGML provides an easier way to tie answers to answer blanks, however. Simply insert the answer inside braces following the answer blank: | ||

+ | |||

+ | If [: x = [$a] :], then the value of [: x^2 :] is [___________]{$a**2} | ||

+ | |||

+ | Note that, as in this example, you can use a mathematical expression, or you could use a constant, or a variable. Here, you don't need to enclose the variable in brackets, as this is a perl expression, not PGML text. | ||

+ | |||

+ | If your answer is a formula, enclose it in quotation marks | ||

+ | |||

+ | The parabola that opens upward and passes through [`x = 1`] and [`x = -1`] | ||

+ | is [` y = `] [_______________________]{"x^2-1"} | ||

+ | |||

+ | or use a Formula MathObject: | ||

+ | |||

+ | $f = Compute("x^2-1"); | ||

+ | |||

+ | BEGIN_PGML | ||

+ | The parabola that opens upward and passes through [`x = 1`] and [`x = -1`] | ||

+ | is [` y = `] [_______________________]{$f} | ||

+ | END_PGML | ||

+ | |||

+ | If your expression has random parameter, you insert them as you would in a call to the MathObject <code>Compute()</code> command: | ||

+ | |||

+ | $a = random(2,5,1); | ||

+ | |||

+ | BEGIN_PGML | ||

+ | The parabola that opens upward and passes through [`x = [$a]`] and [`x = 0`] | ||

+ | is [` y = `] [_______________________]{"x(x-$a)"} | ||

+ | END_PGML | ||

+ | |||

+ | (Again, no brackets are needed in the answer string). | ||

+ | |||

+ | If you want to pass parameters to a MathObject answer checker, you can: | ||

+ | |||

+ | $f = Compute("sqrt(x^2-10)"); | ||

+ | |||

+ | BEGIN_PGML | ||

+ | The answer is [_________________]{$f->cmp(limits=>[4,6])} | ||

+ | END_PGML | ||

+ | |||

+ | There are many other possibilities for what you can pass as the answer; see the documents linked below for more details. | ||

== Further Reading == | == Further Reading == |

## Revision as of 11:22, 7 May 2015

## Contents |

## What is PGML?

**PGML** stands for "PG Markup Language", and it provides a method of creating the text of a PG problem that is easier and more flexible than the traditional `BEGIN_TEXT/END_TEXT`

approach. PGML is based on the Markdown language that now underlies many blog and wiki software, so you may be familiar with some of its syntax already. Note, however, that there are many flavors of Markdown, and PGML may not implement everything exactly the same as the markdown dialect that you use elsewhere. There are also important additions to PGML specifically for working with PG, such as the ability to create answer blanks, or insert values of variables created earlier in the problem.

PGML provides easy means of creating paragraphs, lists, headers, indentation, centering, and other formatting features. It also allows you to link the answer directly to its answer blank for easy problem maintenance. The underlying idea behind PGML is to make what you type as the text of the problem look as close to the result on screen as possible.

PGML is for creating the *text* of the problem and for associating answers to their answer blanks. The setup and computational portion of the problem is still done in the traditional way. PGML integrates with MathObjects to make it easy to work with answers and answer checkers, and to present mathematics within the text of your problem.

PGML can also be used to create the solutions to your problem, with many of the same advantages that you have for the text of the problem itself.

## PGML Basics

To use PGML, you need to include `PGML.pl`

in your problem file via

loadMacros("PGML.pl");

Within your problem file, you can format a section of text using PGML by surrounding it with `BEGIN_PGML`

and `END_PGML`

BEGIN_PGML ... your PGML text goes here ... END_PGML

Similarly, if you want to use PGML to generate your solution text, use

BEGIN_PGML_SOLUTION ... your PGML solution text goes here ... END_PGML_SOLUTION

These `BEGIN`

and `END`

commands must be on a line by themselves, though they can be indented.

The formatting for the text that goes between them is described in more detail below, but PGML tries to make the formatting reflect the layout you have used within the `BEGIN/END`

, and it uses the kinds of things you might type in an email message to indicate more advanced formatting. For example, a blank line indicates a paragraph break, indenting by 4 spaces indicates an indentation, asterisks and underlines indicate bold and italics, numbers at the beginning of a line indicates a numbered list, and so on.

## Basic Formatting

One of the underlying motivations of PGML is to try to make how you format the text within your problem file be reflected in the formatting when the problem is displayed on screen. So if you want to have some text be indented on screen, you simply indent it in when you are typing the problem. PGML formats your output based on standard conventions used in email or other text-based documents. Some of the more important of these conventions are described below. Full details can be found in the Further Reading below.

### Paragraph and Line breaks

Paragraphs are separated by a blank line (just as you would in an email message, for example).

Paragraph one has a few lines of text, but ends here. This is paragraph two.

Line breaks normally are ignored, so several lines of text will become one paragraph, and that will reflow to fill the horizontal space allocated to the problem. In the example above, the line break between "few lines" and "of text" may not be where the line breaks on screen. To force a line break within a paragraph, end the line with two consecutive spaces. So using `"a few lines "`

in the example above would guarantee that the line break on screen comes after "lines".

### Indenting, Centering, and Justifying

To indent a paragraph, insert 4 spaces before the first word of the paragraph.

This paragraph is flush left. But this one is indented. Back to flush left.

You only need to indent the first line of the paragraph, but is is OK to indent them all if that is easier to read.

This is indented, but only the first line needs to have the four spaces. The others can be flush left. But you can indent all the lines of a paragraph if you want. That might be easier to read.

You can have multiple indent levels:

This is flush left. This is indented. This is also indented. And this is indented further.

To center text, put `>>`

and `<<`

around it.

>> Centered text << >> Centered paragraph spanning more than one line. << >> You can mark each << >> line separately if you want << >> and all lines will be combined << >> into one centered paragraph. <<

Put two spaces after the `<<`

to force a line break within the centered paragraph.

To right-justify some text, use just `>>`

at the left

>> Right-justified text >> Right-jutified paragraph spanning multiple lines. >> Right-justified paragraphs >> can have markers on >> each line.

### Lists

You can create numbered, alphabetic, or bullet lists in PGML. Items in a numbered lists begin with a number followed by a period and at least one space.

1. This is the first item 2. This is the second item which spans several lines.

A blank line ends the list, unless it is indented with four spaces, in which case it becomes a new paragraph in the previous numbered item.

Here is a list: 1. This is the first list item continued on the next line. 2. Additional items are easy to add. 3. Continuation need not be indented, such as this line. A paragraph break ends the list... 1. Unless you indent the paragraph... ...in which case it is part of the list item. 2. See?

Note that the actual numbers used don't matter. PGML will always number from 1 and increment by one each time. So

1. Item A 2. Item B 3. Item C

and

8. Item A 1. Item B 3. Item C

both produce the same numbered list in the output (numbered as in the first example).

Alphabetic lists start with a letter followed by a period or a close parenthesis:

A list with alphabetic markers: a) You can use dots b) or parens to indicate the items

Roman numerals can be obtained using lists starting with roman numbers an a period:

A list with roman numeral markers: i. Item 1 ii. Item 2

Uppercase letters or roman numerals produce lists with upper-case markers.

Bullet lists begin with an asterisk or a dash. Plus signs produce square bullets, and `o`

produces open circles.

Bullets: * Item A * item B Squares: + Item A' + Item B'

### Emphasis

Asterisks are used to indicate '*bold*, and underscores produce *italics*. (Note: some Markdown processors use `*`

for italics and `**`

for bold; we may adopt that convention in the future.)

This is *bold text*, and _italic text_. They can be combined as *_bold italic text_*.

### Mathematical Notation

PGML allows you to specify mathematics in two different formats: TeX and calculator notation. The TeX notation allows you to use the standard TeX and LaTeX commands to format your mathematics. The calculator notation uses MathObjects to parse and format the mathematics (so this is the notation that you use to create formulas in your PG problems, and that students use to enter their answers). Both formats come in two forms: in-line and display style. The in-line form uses spacing rules that try to minimize the impact on line spacing, while display style allows for easier readability at the cost of using more vertical space.

To use TeX-formatted mathematics, enclose it in `[`...`]`

for in-line math and `[``...``]`

for display-style math.

To use calculator notation, enclose it in `[: ... :]`

for in-line math and `[:: ... ::]`

for display-style math.

For example,

What [`x`] makes [`\frac{x+2}{3} = 1`]? What [:x:] makes [:(x+2)/3 = 1:]?

both produce the same results (with in-line math).

Note that, unlike with TeX, display-mode math is not automatically centered on a separate line. If you want that, you must provide the formatting for that yourself:

[``\sum_{n=0}^{10} 2^n``] is flush left [``\sum_{n=0}^{10} 2^n``] is indented >> [``\sum_{n=0}^{10} 2^n ``] is centered <<

## Interaction with PG

There are two important ways that PGML must interact with the rest of the PG problem: inserting the values of perl variables into the problem (e.g., the randomized parameters for the problem), and making the answer blanks where students will enter their answers and tying those blanks to the correct answers. Both of these are easy to do, and are described below.

### Variable Substitution

To insert the value of a variable into your PGML text, enclose the variable name with `[...]`

. For example, if you have a variable `$a`

in your problem, then you can use

BEGIN_PGML Suppose that a train leaves Chicago traveling [$a] miles per hour due south. END_PGML

You can access array or hash entries similarly, e.g., `[$b[0]]`

or `[$c{neg}]`

or `[$d->{period}]`

.

Note that a variable that holds a MathObject can produce either a TeX string or a calculator-notation string; which one it produces depends on the context in which it is used. If it is inserted inside of TeX math delimiters (e.g., inside `[`...`]`

), it will produce its TeX form, while if it is inserted inside calculator delimiters (e.g., `[: ... :]`

), or not inside any delimiters, then it produces calculator-style notation. So if `$f = Formula("(x+1)/(x-1)")`

, then

Suppose [`f(x) = [$f]`].

and

Suppose [:f(x) = [$f]:].

will both produce properly formatted mathematical output with no special handling needed on your part. (Note that this is in sharp contrast to the traditional `BEGIN_TEXT/END_TEXT`

approach, which requires you to handle the TeX versions specially.)

### Answer Blanks

One of the key ingredients in any WeBWorK problem is answer blanks where students can enter their answers. In PGML, these are created using `[_____]`

, where the number of underscores indicates how wide the answer blank should be. For example

If [: x = [$a] :], then the value of [: x^2 :] is [___________]

sets up an answer blank for the student to enter his or her value for \(x^2\). The answer checker for this blank can be provided via `ANS()`

in the traditional way. PGML provides an easier way to tie answers to answer blanks, however. Simply insert the answer inside braces following the answer blank:

If [: x = [$a] :], then the value of [: x^2 :] is [___________]{$a**2}

Note that, as in this example, you can use a mathematical expression, or you could use a constant, or a variable. Here, you don't need to enclose the variable in brackets, as this is a perl expression, not PGML text.

If your answer is a formula, enclose it in quotation marks

The parabola that opens upward and passes through [`x = 1`] and [`x = -1`] is [` y = `] [_______________________]{"x^2-1"}

or use a Formula MathObject:

$f = Compute("x^2-1"); BEGIN_PGML The parabola that opens upward and passes through [`x = 1`] and [`x = -1`] is [` y = `] [_______________________]{$f} END_PGML

If your expression has random parameter, you insert them as you would in a call to the MathObject `Compute()`

command:

$a = random(2,5,1); BEGIN_PGML The parabola that opens upward and passes through [`x = [$a]`] and [`x = 0`] is [` y = `] [_______________________]{"x(x-$a)"} END_PGML

(Again, no brackets are needed in the answer string).

If you want to pass parameters to a MathObject answer checker, you can:

$f = Compute("sqrt(x^2-10)"); BEGIN_PGML The answer is [_________________]{$f->cmp(limits=>[4,6])} END_PGML

There are many other possibilities for what you can pass as the answer; see the documents linked below for more details.

## Further Reading

links to other pages