Working with Short-Answer, Multiple-Choice, Fill-in-the-Blank, and True/False Questions¶
The short.tex template (located in pygacity/resources/templates/) provides
a flexible, data-driven mechanism for authoring question pools of four types:
Short answer — a question with space for a written response
Multiple choice — a question with labeled lettered choices
Fill in the blank — a sentence with one or more blanks to complete
True/False — a statement the student marks T or F
Rather than encoding questions directly in LaTeX, you write them in a YAML file
and reference it from the document config. short.tex handles typesetting,
per-serial shuffling, solution display, and answer registration automatically.
Referencing short.tex from a Config¶
Use short.tex as a source entry in the enumerate block of your
document YAML. Add a config key pointing to the YAML file that contains
the question pool:
- enumerate:
- source: short.tex
points: 30
config: derivatives_short_answer.yaml
group: 2
- source: short.tex
points: 10
config: true_false_questions.yaml
group: 4
The same short.tex template can appear multiple times — once per question
pool. Each entry gets its own points value, group assignment, and
independent YAML file.
If you are building in a subdirectory, prepend ../ to the config filename:
- source: short.tex
config: ../my_questions.yaml
The Question-Pool YAML File¶
The YAML file has two top-level keys: config (pool-level settings) and
content (the list of individual questions).
config:
count: 3 # how many questions to draw from the pool
shuffle: true # shuffle the pool before drawing (per serial)
type: short_answer # default question type for items that omit 'T'
instructions: |
\textbf{Derivatives.} Provide the correct derivative for each function.
shuffle_choices: false # (multiple_choice only) shuffle choices globally
clearpage: true # emit \clearpage after the question block (default: true)
content:
- Q: \(f(x) = x^2\)
A: \(f^\prime(x) = 2x\)
text: The power rule states that the derivative of \(x^n\) is \(nx^{n-1}\).
- Q: \(f(x) = \sin(x)\)
A: \(f^\prime(x) = \cos(x)\)
text: The derivative of \(\sin(x)\) is \(\cos(x)\).
If the YAML file contains only a flat list (no config/content split),
all questions in the list are used without shuffling.
config Keys¶
Key |
Default |
Description |
|---|---|---|
|
all |
Number of questions to draw from |
|
|
When |
|
|
Default question type applied to any item that omits the |
|
built-in string |
Instruction text printed above the question list. LaTeX markup is
supported. The |
|
|
|
|
|
When |
Question Item Keys¶
Each entry in content is a dict with the following keys:
Key |
Required |
Description |
|---|---|---|
|
yes |
Question text. LaTeX markup is supported. For |
|
yes |
The correct answer. For |
|
no |
Question type override. One of |
|
no |
Explanation shown in the solution copy (in red). LaTeX markup supported. |
|
MC only |
Ordered dict of |
|
no |
Per-question override of the pool-level |
|
no |
|
Question Types in Detail¶
Short Answer (short_answer)¶
A question followed by blank space for a written response.
- Q: \(f(x) = \ln(x)\)
A: \(f^\prime(x) = \frac{1}{x}\)
text: The derivative of \(\ln(x)\) is \(\frac{1}{x}\).
In the student copy, 1.4 cm of blank space appears below the question. In the solution copy, the answer is shown in blue and the explanation in red.
Fill in the Blank (fill_in_the_blank)¶
A sentence with a blank marked by ___. The answer is rendered via
\fitanswerslot: a dashed line in the student copy and the answer text inline
in the solution copy.
- Q: The capital of France is ___.
A: Paris
text: Paris has been the capital of France since the 10th century.
Multiple blanks in a single question are supported — use ___ once per blank
and provide a single combined answer string.
True/False (true_false)¶
A statement the student marks T or F, rendered via the \tfitem LaTeX macro.
- Q: The chemical symbol for gold is Ag.
A: F
text: The chemical symbol for gold is Au; Ag is the symbol for silver.
Multiple Choice (multiple_choice)¶
A question with lettered choices rendered via the \mcchoiceitem LaTeX macro.
The correct choice label is stored in A; in the solution copy the correct
choice is highlighted.
- Q: Which planet is known as the Red Planet?
choices:
A: Venus
B: Mars
C: Jupiter
D: Saturn
A: B
text: Mars is known as the Red Planet due to iron oxide on its surface.
With shuffle_choices: true in the pool config, choice texts are shuffled
and A is updated automatically to point to whichever label now carries the
correct text.
Per-question shuffle override — when choices cross-reference each other
(e.g. “Both A and B are correct”), set shuffle_choices: false on that item:
- Q: "Which statements about Newton's laws are correct? (Select the best answer.)"
shuffle_choices: false
choices:
A: The first law states that an object at rest stays at rest unless acted on by a net force.
B: The second law states that F = ma.
C: Both A and B are correct.
D: Neither A nor B is correct.
A: C
text: Both A and B are correct; shuffling would invalidate the cross-references.
Pinning the last choice — use fixed_last: true to keep “None of the above”
or similar choices at the bottom while the rest are shuffled freely:
- Q: Which of the following is a fossil fuel?
fixed_last: true
choices:
A: Solar energy
B: Wind energy
C: Natural gas
D: None of the above.
A: C
text: Natural gas is a fossil fuel. The last choice is pinned in place.
Shuffling and Reproducibility¶
When shuffle: true, the question pool is shuffled using rng — the
per-serial NumPy RNG that is seeded by the serial number in setup.py.
Likewise, shuffle_choices: true shuffles MC choices using the same rng.
Because the RNG state is deterministic given the serial, the same serial always
produces the same question draw and the same choice ordering, making every build
fully reproducible.
Answer Registration¶
After selecting and processing questions, short.tex registers each answer
with AnsSet:
for l, t in zip([chr(ord('a') + x) for x in range(len(answers))], answers):
AnsSet.register(idx, group=group, label=l, value=t)
The labels are a, b, c, … in draw order. These answers appear in
the consolidated answer set document, one column per question and one row per
serial.
Complete Examples¶
The compound_exam example uses short.tex four times, exercising all four
question types. The relevant section of CompoundExam.yaml:
- question_number: 4
source: short.tex
points: 20
config: geography_fill_in_the_blank.yaml
- question_number: 5
source: short.tex
points: 10
config: true_false_questions.yaml
- question_number: 6
source: short.tex
points: 10
config: multiple_choice_questions.yaml
- pythontex:
- teardown
build:
seed: 12345
copies: 3
job-name: ExamI
paths:
The corresponding pool files:
Short answer — 8 questions in pool, 3 drawn per serial, shuffled:
config:
count: 3
shuffle: true
instructions: |
\textbf{Derivatives.} Provide the correct derivative for each of the following functions.
type: short_answer
content:
- Q: \(f(x) = x^2\)
A: \(f^\prime(x) = 2x\)
text: The power rule states that the derivative of \(x^n\) is \(nx^{n-1}\).
- Q: \(f(x) = 2x^3 + 3x^2\)
A: \(f^\prime(x) = 6x^2 + 6x\)
text: The power rule states that the derivative of \(x^n\) is \(nx^{n-1}\), and the derivative of a sum is the sum of the derivatives.
- Q: \(f(x) = \sin(x)\)
A: \(f^\prime(x) = \cos(x)\)
text: |
The derivative of \(\sin(x)\) is \(\cos(x)\) according to standard differentiation rules. Or, you can consult the
series expansion of \(\sin(x)\) and differentiate term by term.
- Q: \(f(x) = \ln(x)\)
A: \(f^\prime(x) = \frac{1}{x}\)
text: The derivative of \(\ln(x)\) is \(\frac{1}{x}\) according to standard differentiation rules.
- Q: \(f(x) = e^{2x}\)
A: \(f^\prime(x) = 2e^{2x}\)
text: The derivative of \(e^{kx}\) is \(ke^{kx}\) according to standard differentiation rules.
- Q: \(f(x) = x^4 - 4x^3 + 6x^2 - 4x + 1\)
A: \(f^\prime(x) = 4x^3 - 12x^2 + 12x - 4\)
text: The power rule states that the derivative of \(x^n\) is \(nx^{n-1}\), and the derivative of a sum is the sum of the derivatives.
- Q: \(f(x) = \cos(x)\)
A: \(f^\prime(x) = -\sin(x)\)
text: The derivative of \(\cos(x)\) is \(-\sin(x)\) according to standard differentiation rules.
- Q: \(f(x) = \tan(x)\)
A: \(f^\prime(x) = \sec^2(x)\)
text: The derivative of \(\tan(x)\) is \(\sec^2(x)\) according to standard differentiation rules.
Fill in the blank — 11 questions in pool, 4 drawn per serial, shuffled:
config:
count: 4
shuffle: True
instructions: |
\textbf{State and World Capitals.} Write the correct US State, Canadian Province, or World Country or its capital in the blank provided.
type: fill_in_the_blank
content:
- Q: The capital of Texas is ___.
A: Austin
text: Austin became the capital of Texas in 1839.
- Q: The capital of Ontario is ___.
A: Toronto
text: Toronto is the capital city of the province of Ontario in Canada.
- Q: The capital of France is ___.
A: Paris
text: Paris has been the capital of France since the 10th century.
- Q: The capital of Japan is ___.
A: Tokyo
text: Tokyo has been the capital of Japan since 1868.
- Q: The capital of Germany is ___.
A: Berlin
text: Berlin has been the capital of Germany since 1990 following reunification.
- Q: The capital of ___ is Ottawa.
A: Canada
text: Ottawa is the capital city of Canada.
- Q: The capital of ___ is Canberra.
A: Australia
text: Canberra is the capital city of Australia.
- Q: The capital of ___ is Bras\'ilia.
A: Brazil
text: Bras\'ilia has been the capital of Brazil since 1960.
- Q: The capital of ___ is New Delhi.
A: India
text: New Delhi has been the capital of India since 1911.
- Q: The capital of ___ is Moscow.
A: Russia
text: Moscow has been the capital of Russia since 1918.
- Q: The capital of ___ is Cairo.
A: Egypt
text: Cairo has been the capital of Egypt since 972 AD.
True/False — 8 questions in pool, 4 drawn per serial, shuffled:
config:
count: 4
shuffle: true
instructions: |
\textbf{True/False Questions.} Indicate whether each of the following statements is true (``T'') or false (``F'').
type: true_false
content:
- Q: On a piano, the frequency of middle C is approximately 261.63 Hz.
A: T
text: The frequency of middle C (C4) is indeed approximately 261.63 Hz.
- Q: The chemical symbol for gold is Ag.
A: F
text: The chemical symbol for gold is Au; Ag is the symbol for silver.
- Q: The Great Wall of China is visible from space with the naked eye.
A: F
text: This is a common myth; the Great Wall is not easily visible from space without aid.
- Q: Water boils at 100 degrees Celsius at standard atmospheric pressure.
A: T
text: At standard atmospheric pressure (1 atm), water boils at 100 degrees Celsius.
- Q: The capital of Australia is Sydney.
A: F
text: The capital of Australia is Canberra, not Sydney.
- Q: Humans have four lungs.
A: F
text: Humans have two lungs, not four.
- Q: The speed of light in a vacuum is approximately \(3.00 \times 10^8\) meters per second.
A: T
text: The speed of light in a vacuum is approximately 299,792,458 meters per second, often rounded to \(3.00 \times 10^8\) m/s.
- Q: The largest planet in our solar system is Saturn.
A: F
text: The largest planet in our solar system is Jupiter, not Saturn.
Multiple choice — 13 questions in pool, 4 drawn per serial, shuffled with
global choice shuffling; two questions demonstrate per-question overrides
(shuffle_choices: false and fixed_last: true):
config:
count: 4
shuffle: true
instructions: |
\textbf{Multiple choice questions.} Circle the letter of the correct answer from the choices provided.
type: multiple_choice
shuffle_choices: true
content:
- Q: What is the capital of Italy?
choices:
A: Madrid
B: Rome
C: Berlin
D: Lisbon
A: B
text: Rome is the capital city of Italy.
- Q: Which element has the chemical symbol 'O'?
choices:
a: Gold
b: Oxygen
c: Osmium
d: Silver
A: b
text: Oxygen has the chemical symbol 'O'. Note that the case of the choice keys are preserved in the final document.
- Q: Who wrote "Romeo and Juliet"?
choices:
A: Charles Dickens
B: Mark Twain
C: William Shakespeare
D: Jane Austen
A: C
text: William Shakespeare is the author of "Romeo and Juliet".
- Q: What is the largest mammal in the world?
choices:
A: African Elephant
B: Blue Whale
C: Giraffe
D: Great White Shark
A: B
text: The Blue Whale is the largest mammal in the world.
- Q: What is the boiling point of water at standard atmospheric pressure?
choices:
A: 90 degrees Celsius
B: 100 degrees Celsius
C: 110 degrees Celsius
D: 120 degrees Celsius
A: B
text: Water boils at 100 degrees Celsius at standard atmospheric pressure (1 atm).
- Q: Which planet is known as the Red Planet?
choices:
A: Venus
B: Mars
C: Jupiter
D: Saturn
A: B
text: Mars is known as the Red Planet due to its reddish appearance caused by iron oxide
- Q: Who painted the Mona Lisa?
choices:
A: Vincent van Gogh
B: Pablo Picasso
C: Leonardo da Vinci
D: Claude Monet
A: C
text: The Mona Lisa was painted by Leonardo da Vinci.
- Q: What is the smallest prime number?
choices:
A: 0
B: 1
C: 2
D: 3
A: C
text: The smallest prime number is 2, which is the only even prime number.
- Q: In which year did the Titanic sink?
choices:
A: 1910
B: 1912
C: 1914
D: 1916
A: B
text: The Titanic sank in the North Atlantic Ocean on April 15, 1912, after hitting an iceberg.
- Q: What is the chemical formula for table salt?
choices:
A: H2O
B: CO2
C: NaCl
D: C6H12O6
A: C
text: The chemical formula for table salt is NaCl, which stands for sodium chloride.
- Q: Who is known as the "Father of Modern Physics"?
choices:
A: Isaac Newton
B: Albert Einstein
C: Galileo Galilei
D: Niels Bohr
A: B
text: Albert Einstein is often referred to as the "Father of Modern Physics" for his contributions to the field, including the theory of relativity.
- Q: "Which of the following statements about Newton's laws of motion are correct?
(Select the best answer.)"
shuffle_choices: false
choices:
A: The first law states that an object at rest stays at rest unless acted on by a net force.
B: The second law states that F = ma.
C: Both A and B are correct.
D: Neither A nor B is correct.
A: C
text: Both statements are correct. Choice C cross-references A and B by label,
so shuffling choices would make the cross-references wrong. \texttt{shuffle\_choices} is
set to false for this question to override the global \texttt{shuffle\_choices} setting.
- Q: Which of the following is a fossil fuel?
fixed_last: true
choices:
A: Solar energy
B: Wind energy
C: Natural gas
D: None of the above.
A: C
text: Natural gas is a fossil fuel. The other options are renewable energy sources.
The last choice ``None of the above''' is pinned in place with \texttt{fixed\_last}, while
choices A-C are shuffled freely.