7.4: Common Mistakes and How to Fix Them

Asterisks around variables

Symptom: '*' was not closed before paragraph ends

Cause: PGML interprets * as the start of italic text. When you wrap a variable in single asterisks, PGML tries to treat everything between them as italic content. If the variable expands to something unexpected, the italic block never closes.

BEGIN_PGML
The answer is *[$variable]*.
END_PGML

BEGIN_PGML
The answer is **[$variable]**.
END_PGML

BEGIN_PGML
The answer is [$variable].
END_PGML

$answer_emph = "<em>$variable</em>";

BEGIN_PGML
The answer is [$answer_emph]*.
END_PGML

Bold markers around variables

Symptom: '**' was not closed before paragraph ends

Cause: Bold markers (**) break when the variable content contains characters that PGML interprets as additional formatting.

BEGIN_PGML
At pH [$selected_ph], histidine exists in **[$correct_label]**.
END_PGML

BEGIN_PGML
At pH [$selected_ph], histidine exists in [$correct_label].
END_PGML

$label_bold = "<strong>$correct_label</strong>";

BEGIN_PGML
At pH [$selected_ph], histidine exists in [$label_bold]*.
END_PGML

Using * for bullets when you also have italic content

Symptom: Confusing PGML parse behavior. Lines that begin with * and also contain *italic* markers cause the parser to misread which asterisks are bullets and which are emphasis.

BEGIN_PGML
* *State 1* (pH < 1.82): Description
* *State 2* (pH > 1.82): Description
END_PGML

BEGIN_PGML
- **State 1** (pH < 1.82): Description
- **State 2** (pH > 1.82): Description
END_PGML

The my keyword makes variables invisible to PGML

Symptom: RadioButtons renders as a plain text input box instead of radio buttons. Grading fails with Answer evaluator was not executed due to errors.

Cause: Writing my $radio = RadioButtons(...) creates a lexical variable that PGML cannot see. Think of it this way: PGML looks up variables in a shared directory (the package symbol table). The my keyword puts the variable in a private closet that PGML cannot open. When PGML encounters [_]{$radio}, it checks the shared directory, finds nothing, and falls back to a generic text input.

my $radio = RadioButtons(['Alpha', 'Beta'], 'Alpha');

BEGIN_PGML
[_]{$radio}
END_PGML

$radio = RadioButtons(['Alpha', 'Beta'], 'Alpha');

BEGIN_PGML
[_]{$radio}
END_PGML

# OK -- my for intermediates, bare for PGML-visible results
my $idx = random(0, 3, 1);
$rb = RadioButtons([@choices], $choices[$idx]);

Why local works but my does not

Authors who know that my is "more modern" than local sometimes avoid local entirely. In PG, the two keywords have critically different PGML visibility. local temporarily modifies a package variable, so it stays in the symbol table and PGML can still find it. my creates a lexical variable on the Perl pad stack, which is invisible to PGML's symbol-table lookup. For PG problems, the simplest approach is to use bare package variables (no my, no local) for anything PGML needs to see.

Wrong:

$html_content = '<span style="color:red;">Important</span>';

BEGIN_PGML
This is [$html_content] text.
END_PGML

Right:

$html_content = '<span style="color:red;">Important</span>';

BEGIN_PGML
This is [$html_content]* text.
END_PGML

The rule: If a variable contains any HTML tags (<span>, <div>, <strong>, <sub>, etc.), always add * after the closing bracket. The asterisk tells PGML to pass the content through without escaping.

Symptom table: missing macro errors

How to fix

Check your loadMacros() block near the top of the file and add the missing macro. A correct block that covers common widgets:

loadMacros(
  'PGstandard.pl',
  'PGML.pl',
  'parserRadioButtons.pl',
  'parserPopUp.pl',
  'niceTables.pl',
  'PGcourse.pl',
);

use statements are trapped

Symptom: 'require' trapped by operation mask

Cause: Perl's use statement calls require internally, and the PG sandbox blocks it for security. PG problems run on shared servers and cannot load arbitrary Perl modules.

use POSIX qw(floor);
use List::Util qw(shuffle);

# For truncation (instead of POSIX floor)
$val = int(3.7);              # returns 3

# For rounding (instead of POSIX round)
$val = sprintf("%.0f", 3.7);  # returns 4

Wrong:

BEGIN_PGML
<table>
  <tr><td>Cell 1</td><td>Cell 2</td></tr>
</table>
END_PGML

Right: Use niceTables.pl with DataTable or LayoutTable.

loadMacros('niceTables.pl');

$table = DataTable(
  [['Header 1', 'Header 2'],
   ['Cell 1',   'Cell 2']],
);

BEGIN_PGML
[$table]*
END_PGML

Note the * after [$table] because the variable contains HTML. niceTables.pl is the only supported way to create tables in PG problems.

Wrong:

BEGIN_PGML
[@ MODES(HTML => '<div>content</div>') @]*
END_PGML

Right:

$content = '<div>content</div>';

BEGIN_PGML
[$content]*
END_PGML

TeX color macros do not work. Commands like \color{} and \textcolor{} do not render in this environment. Use HTML <span> elements with inline CSS for colored text instead.

Using variables before they are defined

Symptom: Empty output, missing content, or blank areas in the rendered problem.

@all_cards = ($card1, $card2, $card3);
# ... 50 lines later ...
$card1 = '<div>content 1</div>';
$card2 = '<div>content 2</div>';
$card3 = '<div>content 3</div>';

$card1 = '<div>content 1</div>';
$card2 = '<div>content 2</div>';
$card3 = '<div>content 3</div>';
# ... then use them ...
@all_cards = ($card1, $card2, $card3);

Shuffle timing

The correct pattern: (1) define all items, (2) create the array, (3) shuffle. Never shuffle before the items exist.

# 1. Define all items first
$item1 = "content 1";
$item2 = "content 2";
$item3 = "content 3";

# 2. Create array
@all_items = ($item1, $item2, $item3);

# 3. Shuffle
@shuffled = ();
@temp = @all_items;
while (@temp) {
  my $i = random(0, $#temp, 1);
  push @shuffled, splice(@temp, $i, 1);
}

Hash key order is not deterministic

Symptom: Random order changes between runs even with the same seed.

Cause: Perl hash key iteration order is not guaranteed. Each run can return keys in a different order, making randomization unreproducible.

%items = (a => 'Apple', b => 'Banana', c => 'Cherry');
@choices = values %items;  # Random order!

%items = (a => 'Apple', b => 'Banana', c => 'Cherry');
@sorted_keys = sort keys %items;
$selected = list_random(@sorted_keys);

Backslash references are broken (\@ and \%)

Symptom: Not an ARRAY reference or Not a HASH reference

Cause: The PG sandbox blocks the backslash (\) operator for creating references. Writing \@array does not produce a usable array reference.

@choices = ('Alpha', 'Beta', 'Gamma');
$rb = RadioButtons(\@choices, 'Alpha');

@choices = ('Alpha', 'Beta', 'Gamma');
$rb = RadioButtons([@choices], 'Alpha');

@choices = ('Alpha', 'Beta', 'Gamma');
$rb = RadioButtons(~~@choices, 'Alpha');

# Wrong:  $href = \%data;
# Right:  $href = {%data};
# Right:  $href = ~~%data;

Loops do not work inside BEGIN_TEXT

Symptom: No output, empty section where the loop content should appear.

Cause: BEGIN_TEXT...END_TEXT is a string construction block, not Perl code execution. A foreach loop inside it becomes part of the string rather than running as code.

BEGIN_TEXT
foreach my $item (@items) {
  \{ $item \}
}
END_TEXT

$all_items_html = '';
foreach my $item (@items) {
  $all_items_html .= $item;
}

BEGIN_TEXT
\{ $all_items_html \}
END_TEXT

Wrong:

ANS(str_cmp($answer));  # Looks for AnSwEr0001
# But JS or HTML creates an input with a different name -- no connection!

Right:

BEGIN_TEXT
\{ MODES(HTML => '<div style="display:none;">' . ans_rule(20) . '</div>', TeX => '') \}
END_TEXT
ANS(str_cmp($answer));

The rule: ans_rule() creates the input field that ANS() checks. Always create the ans_rule() first, then call ANS(). When you need a custom UI with JavaScript, hide the ans_rule() input and use JavaScript to populate its value.

Incorrect formal charges in ring systems

Symptom: Molecule renders with wrong structure, or RDKit rejects the SMILES string entirely.

Cause: Using incorrect formal charge notation for nitrogen atoms in ring systems like imidazole. Writing NH2+ implies two hydrogens on one nitrogen, which is chemically incorrect for the imidazole ring.

# NH2+ implies TWO hydrogens on one nitrogen -- wrong for imidazole
$imidazole_protonated = '...N=C[NH2+]1)...';

# Imidazole has two nitrogens: one NH, one NH+
$imidazole_protonated = 'C1=C([NH]C=[NH+]1)...';

Check line numbers

When variables seem empty or undefined, check where the variable is used versus where it is defined. Find the usage with a search for the variable name, then find the definition (the line with $var_name = ...). The definition line number must be lower (earlier in the file) than the usage line number.

Isolate PGML errors with binary search

When you get '*' was not closed or similar PGML parsing errors:

1. Comment out the bottom half of your PGML block.
2. Render the problem. If the error is gone, the problem is in the bottom half.
3. Restore the bottom half and comment out the top half to confirm.
4. Keep splitting the offending half until you find the exact line.
5. Check for *, **, or _ near variables on that line.

Test with a minimal example

Create the smallest possible problem file that reproduces the error:

DOCUMENT();
loadMacros("PGstandard.pl", "PGML.pl");

$var = "test";

BEGIN_PGML
Test: [$var]
END_PGML

ENDDOCUMENT();

Add complexity one piece at a time until the problem reappears. The last piece you added is the cause.

Check renderer output

If your local setup supports the -r flag on the renderer script, use it to inspect the actual HTML output. Look for HTML that was escaped when it should not have been (< instead of <), missing elements, or structural problems in the generated markup.