tb-match

The tb-match directive creates a matching question. Authors provide normal prompt content followed by one definition list. Each definition-list term is a source item. Each definition is the matching target.

HTML renders each source item beside a dropdown list of definitions. Students choose one definition for each source item, then use Check Me to evaluate the matches. Authors can add distractor definitions that appear as dropdown choices but do not match any source item.

Synopsis

The general format of the tb-match directive is:

.. tb-match::
   :optional parameter: value

   + --- Prompt area ---
   |
   | question text and optional Sphinx content
   |
   + --- Pair area ---
   |
   | source item
   |    matching target
   |
   | another source item
   |    another matching target
   |
   + -----------------

Options

distractors

String. Optional. Additional definitions that do not match any source item. Separate multiple distractors with semicolons or continuation lines. Dropdown choices are sorted by visible definition text, so distractors do not always appear after the matching definitions.

class

String or List. Optional. A CSS class to add to the directive. See Common options for details.

name

String. Optional. Sphinx reference name for this matching question. See Common options for details.

Accessibility behavior

HTML uses native select controls so keyboard and assistive technology behavior comes from the browser. The result text uses a status region so assistive technology can announce the result after checking.

Fallback behavior

HTML without JavaScript renders source and target content in the page. Text builders render the prompt, a source list, and a target list. PDF-oriented builders render the prompt and a two-column matching table. Sources use upper-case letter labels. Targets include blank answer lines where readers can write the matching source letter.

Examples

Example 1: Terms and meanings

Source

.. tb-match::

   Match each term with its meaning.

   compiler
      Translates source code into executable code.

   interpreter
      Executes source code directly.

   linker
      Combines object files into a program.

Rendered

Match each term with its meaning.

compiler Choose a definition Combines object files into a program. Executes source code directly. Translates source code into executable code.

interpreter Choose a definition Combines object files into a program. Executes source code directly. Translates source code into executable code.

linker Choose a definition Combines object files into a program. Executes source code directly. Translates source code into executable code.

Check Me

Example 2: SQL clauses

Source

.. tb-match::
   :distractors:
      Sorts rows after filtering
      Groups rows by value

   Match each SQL clause with its purpose.

   ``SELECT``
      Chooses output columns.

   ``FROM``
      Names the source table.

   ``WHERE``
      Filters rows before they appear in the result.

Rendered

Match each SQL clause with its purpose.

FROM Choose a definition Chooses output columns. Filters rows before they appear in the result. Groups rows by value Names the source table. Sorts rows after filtering

SELECT Choose a definition Chooses output columns. Filters rows before they appear in the result. Groups rows by value Names the source table. Sorts rows after filtering

WHERE Choose a definition Chooses output columns. Filters rows before they appear in the result. Groups rows by value Names the source table. Sorts rows after filtering

Check Me

Example 3: Simple Code

Source

.. tb-match::

   Match the function declaration to an example of its function call.

   int times_two(double x, string y)
      times_two(4.5,"hello");

   int times_two(string x, double y)
      times_two("hello", 10);

   int times_two(string x, string y)
      times_two("hello", "there");

   int times_two(int x, int y)
      times_two(4,7);

Rendered

Match the function declaration to an example of its function call.

int times_two(double x, string y) Choose a definition times_two(4,7); times_two(4.5,”hello”); times_two(“hello”, 10); times_two(“hello”, “there”);

int times_two(int x, int y) Choose a definition times_two(4,7); times_two(4.5,”hello”); times_two(“hello”, 10); times_two(“hello”, “there”);

int times_two(string x, double y) Choose a definition times_two(4,7); times_two(4.5,”hello”); times_two(“hello”, 10); times_two(“hello”, “there”);

int times_two(string x, string y) Choose a definition times_two(4,7); times_two(4.5,”hello”); times_two(“hello”, 10); times_two(“hello”, “there”);

Check Me