Drilldown format

Markdown-like format for drill content

With “Drilldown” Drillster introduces an additional method to create and transfer drill content. Drilldown is a regular language inspired by the Markdown language and specifically designed to provide an easy-to-read and easy-to-write text based format for drills and drill entries.

Example

In its simplest form, a valid Drilldown document could look like this:

car = voiture
bicycle = vélo
airplane = avion

The above file represents a drill with two columns containing three entries:

Sensible defaults are used for column names, drill details, practice settings, etc.

Anatomy of a drill entry

In the Drilldown format, each line represents a single drill entry. The general format of a drilldown line is:

{known term} = {unknown term} … *) {context} +) {pos feedback} -) {neg feedback} #tag …

The minimal valid drilldown line consists of {known term} = {unknown term}.

Additional = {unknown term} blocks may be added after the first unknown term block, each marked by an equals sign.

The context and positive/negative feedback blocks are optional and may appear in any order after the unknown term blocks. Curly braces in the above examples are not there literally.

Zero or more entry tags may be added at the very end of a line, each prepended with a “#” character.

A {term} consists of one or more alternatives, separated by a forward slash. An alternative may be marked as decoy (intentionally incorrect answer) by prepending it with an exclamation point.

Examples:

one = un/une/!unne
end = fin/!finn

Context, positive and negative feedback are expressed as single items, so the forward slash and starting exclamation point do not serve a purpose there.

Example with feedback:

one = un -) Sorry, that was incorrect +) Well done

Example with context:

address = adresse *) The noun, not the verb

Multiple unknown columns

The first column is always considered to be the “known” column. It represents the reference from which the learner is going to memorize the “unknown” column items. This may for example represent the learner’s native language or just “the question”.

The second and subsequent columns represent the “unknown” sides. These are the items the learner is going to memorize. There must always be at least one known column item and one unknown column item. It is possible to add additional unknown columns by appending another equals sign after the first unknown column item.

Examples:

@NAME Irregular verbs
@SUBJ English
@COLS Present = Past simple = Past participle
begin = began = begun
bite = bit = bitten
build = built = built
dream = dreamed/dreamt = dreamed/dreamt

There must be at least one populated unknown column item:

one = 1 = I
two = = II
three = 3 =

# the below entries are not valid
four =
five = =

Markup

The Drilldown format supports all of Drillster’s markup capabilities. The implementation is inspired by Markdown, but not 100% compatible.

The supported markup types are:

Markup type	Drilldown syntax	Example	Renders as
Bold	**bold**	Please do **not** do this.	Please do not do this.
Italic	*italic*	This is *cool*!	This is cool`!
Underline	_underline_	Go _here_.	Go here.
Superscript	^superscript^	A googol is 10^100^.	A googol is 10100.
Subscript	~subscript~	A glass of H~2~O.	A glass of H2O.
Line break	|	One|two|three	One two three
Bullet point	>	>One> >two> >three>	One two three
Placeholder	___	I am ___ years old.	I am ______ years old.

The placeholder is denoted with any repetition of underscores of length three or higher.

Escape character

The backslash character is used as an escape character where required. For example: equals = \=.

A backslash itself is represented by \\.

Spaces

Repeated spaces are regarded as a single space. Leading and trailing spaces are ignored. Extra spaces may be added for readability of the file, but have no impact in Drillster.

Media support

Supported media attachments may be included as follows:

[type url] caption

Where “type” is the MIME type and “url” is the absolute URL to the object. In the case of images, where there are usually multiple size variants, the URL should represent the original, large-size variant.

Examples:

[image/png https://example.com/img1] = one
[image/png https://example.com/img2] the caption = two

In addition to images, video and audio files are also supported. It is also possible to use a reference to a PDF document.

Drill details

It is possible to include drill details such as the name, subject, column names, etc. by including specific @-directives.

Directive	Purpose	Example
@NAME	Set drill name	@NAME Counting in Russian
@SUBJ	Set drill subject	@SUBJ Russian
@DESC	Set drill description	@DESC Learn to count in Russian
@ICON	Reserved for future use
@TAGS	Set drill tags	@TAGS #counting #russian
@COLS	Set column names	@COLS English = Russian

The @-directives are case sensitive. Only the first occurrence of any of these directives is taken into account — subsequent directives of the same type will be ignored. Default values and settings are used for properties that are not specifically defined.

Markup is not supported in any of these directives. Tags must be prefixed with a “#” character, cannot be longer than 30 characters and must not contain spaces.

Comments

Any lines starting with a “#” are considered to be comments and are ignored by the system. Blank lines are also ignored. Keep in mind that the “#”-character is also used to indicate tags where appropriate.

Example:

#
# This is a comment
#
@COLS English = French

car = voiture

Character encoding

All Drilldown files and strings are considered to be in UTF-8 encoding.

Unsupported features

Not all drill content features are supported by the drilldown format. Unsupported features are:

• Hot spot questions
• Column settings, such as question/answer style and open ended answer arbiters
• MathML support
• Individual term settings related to question and answer style
• Question time limits
• Term introduction behavior
• Question variants (see below)

Where possible, sensible defaults are used. Once uploaded, all settings can still be applied or changed by opening the drill in the familiar drill editor.

Future enhancements

In future updates, the format will be improved to support the following:

• Support for grouping of entries to indicate question varieties. To this end a single open curly brace ({) or closing curly brace (}) on its own line will be used.