The PreTeXt Guide

Parsons problems are named for Dale Parsons, one of their creators, along with Patricia Haden. They could also be called mixed-up blocks. A reader is presented with a set of blocks containing text, either computer code or natural language, and their goal is to assemble the blocks into a correct order. This could be a computer problem with a stated purpose, or could be a logical argument such as proof, or it could be a procedure such as a recipe. An interactive drag-and-drip interface is a very efficient presentation for a reader.

A <block> that has natural content is authored as usual, with a sequence of paragraphs (<p>) or similar. If the content is a computer language, then it should be authored as a sequence of lines, using the <cline> element, which allows for precise interpretation of indentation and non-standard characters. Include all indentation necessary for each line, no matter how @indentation is set. The content of the blocks, arranged properly, should form a syntactically correct program. If the reader is to provide indentation, PreTeXt will strip away the common amount of indentation.

A block may be a distractor, meaning it is not to be used at all in the solution. Indicate this with a @correct attribute on the <block> set to no (the default being yes). Furthermore, a given block of the solution can be authored with several alternatives, only one of which is correct. Indicate this by structuring a <block> with a sequence of <choice>. Each <choice> should be authored similarly to a <block>, and the one correct choice should have the <correct> attribute set to yes (the default being no).

The blocks should be authored in the correct order and the interactive interface will control the randomization. A block that is a distractor may be placed in any location amidst the other blocks. Each block should have an <@order> attribute that is a whole number, counting from 1. This is the fixed, mixed-up, order that will be presented in any static rendition. In static versions, sequences of blocks are in lists, which are numbered if the attribute has been set, but the left/right distinction is lost—all numbers are to the left. An automatic <answer> is provided if blocks are numbered, and it is just the block numbers in the correct order. An automatic <solution> is always generated with the text of the blocks listed in the correct order. For an exercise with computer code, the PreTeXt <program> element and the exercise’s @language attribute will produce a syntax-highlighted listing.

There is no provision for a <feedback> element. Further explanation may be provided in a <hint>, <answer>, or <solution>. Also, a good interactive interface can provide assistance to a reader by telling them if they have too few or too many blocks, or combining or removing blocks, and so on.

As of 2022-06-14 work is underway to relax the strict ordering assumed of the blocks. So there will be extra markup to specify a poset or directed acyclic graph on the blocks.