File format

Files used by Drill 2 are compatible with PDS. PDS's behavior is exploited to enable support for keeping additional settings and data along with questions. This way question bank's creator can configure recommended preferences for a file or enable new features like Markdown formatting.

PDS format

Basic PDS-compatible question banks consist of newline-separated text blocks representing questions.

Each text block starts with a number of text lines representing actual question. Question body is followed by any number of answers, each one in a separate line. Answer lines begin with subsequent alphabet letters, a closing round bracket and a space, followed by answer text. Correct answers are preceded with any number of greater than signs.

Example file in PDS format:

1 correct answers below:
A) A
B) B
>>>C) Correct

2 correct answers below:
A) A
>>>B) Borrect
>>>C) Correct

3 correct answers below:
>>>A) Aorrect
>>>B) Borrect
>>>C) Correct

PDS compatibility

Drill 2 detects PDS files' format as legacy. There are some known differences between file parsing methods used in PDS and Drill 2.

• Question splitting

  PDS splits questions on empty lines after answer lines, while Drill 2 splits them on each empty line. This difference can affect parsing of some files, for example this one:

    Some question body followed by an empty line.
  
    Choose correct answers:
    A) Answer 1
    >>>B) Answer 2
    C) Answer 3
  

  Drill 2 will reject the first line (because it looks like a question without answers), while PDS will recognize it as a multiline question. The old behavior is now obsolete, because Drill 2 will split question body into paragraphs and applies margins to them, so adding extra space between paragraphs is unnecessary.

• Questions without answers

  Both PDS and Drill 2 ignore questions without answers, but PDS's implementation of this feature is buggy and affected by its method of question splitting. The issue can be demonstrated with following text file:

    Question?
    A) Answer 1
    B) Answer 2
    
    >>>C) Answer 3
  

  PDS will output an error message to console, but will accept the question and three answers anyway. Drill 2 will treat this example as two invalid questions: first one doesn't have any correct answers and second one has only one answer.

  PDS will silently ignore a question without answers if it's the last questions in a file. This behavior is exploited to include additional data without breaking backwards compatibility.

• Question identifiers

  If question starts with a number preceded by hash symbol (#) and wrapped in square brackets, then Drill 2 will strip the number and use it as a question identifier. Such identifiers can be used later to add explanations to questions. PDS won't recognize identifiers and will just display them as a part of question. If you're afraid that easily recognizable identifiers will impact learning efficiency, you can use large, hard to remember numbers.

  Example of identifiers can be seen on Example question bank page.

Recommendations

Correct answers can be marked with any number of greater than signs, but for readability, number of signs used should be kept consistent across files. It's recommended to use one or three greater than signs.

Letters designating answers don't have to be unique. Following file is valid both in PDS and Drill 2:

    Question?
    A) Answer 1
    A) Answer 2
    >>>A) Answer 3
    
    Question?
    Z) Answer 1
    Y) Answer 2
    >>>X) Answer 3

<options> block

<options> blocks are Drill 2's extension to PDS file format. PDS will silently ignore such blocks due to a bug described in previous sections of this page.

Features introduced in Drill 2 can be enabled using <options> block. Some features inherited from PDS are preconfigurable too. Using <options> blocks is described on the <options> block page.