Drilldown format

Markdown-like format for drill and story content

With “Drilldown” Drillster introduces an additional method to create and transfer drill/story 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 either drills and drill entries or stories.

Drill example

In its simplest form, a valid Drilldown document to upload a drill 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.

Story example

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

@TYPE Story
Once upon a time...
---
And they lived happely ever after

The above file represents a story with two pages each containing a text paragraph:

Similarly to the drill case above, sensible defaults are used for the story details when not explicitly provided.

---

Now, we will break down the different components that make up a drilldown document for a drill.

Anatomy of a drill entry

By default, 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.

Drill drilldown 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 = =

Question variants

It is possible to group drill entries together that effectively test the same knowledge but are formulated differently. Such drill entries are called 'question variants' of each other. Such a grouping is called a 'question variety'.

Grouping such question variants together is supported in drilldown.

To define a question variety, you start with a opening curly brace { on a separate line. Then on the next lines, you can define the entries that should be question variants of each other. To complete a question variety section, put a closing curly brace } on the next line.

A drill drilldown example containing question varieties:

Are the entries within the curly braces part of a variety?=yes!
{
1=one *) This entry is part of a question variety
één=one *) This entry is part of a question variety
une=one *) This entry is part of a question variety
}
Is this entry after the closing curly brace part of a variety?=No!
{
2=two *) This entry is part of a second question variety
What is 1 + 1 in english?=two/!deux/!unne *) This entry is part of a second question variety
}
vélo=bicycle=fiets *) This entry is not part of a question variety
soccer=Fußball

Anatomy of a Story

Alternatively, as we saw above, a story can also be expressed in the drilldown format.

To represent a story in drilldown format, we need to explicitly specify the drilldown is of type Story.

This is done by starting the drilldown file with @TYPE Story.

A story comprises so-called story items. The below table denotes the different story item types:

Story item type	Syntax
Text paragraph	Text, including optional markup
Text header paragraph	Text, including optional markup preceeded by # for h1, ## h2 up to h4
Media paragraph	[image/png https://example.com/img1], See also Media support
Page separator	--- A dashed line with minimum length of 3

An example containing all the above components

@TYPE Story
@NAME Let me tell you a story
@SUBJ Drilldown story
@DESC My wonderful story
@ICON [image/png https://res.cloudinary.com/drillster/image/upload/c_fill,fl_lossy,h_512,w_512/v1/image/ceec80af35b33a952b8e2d6aa2e91b966b311b16]
@COVER [image/png https://res.cloudinary.com/drillster/image/upload/c_fill,fl_lossy,h_512,w_512/v1/image/ceec80af35b33a952b8e2d6aa2e91b966b311b16]
@TAGS #drilldown #story
# Paragraph header
## Paragraph sub header
Some multi line text
Here is some more text|Next line
Some diacritic chars: ẞ é ī æ
-----
Here is some text and some media items
[video/mp4 https://res.cloudinary.com/drillster/video/upload/vc_auto/v1/video/719211de55ec7152b294cb10cc798b6d6fd1cad4.mp4]
[audio/mpeg https://res.cloudinary.com/drillster/video/upload/v1/audio/7bd4d150fed7b6f6163d8b62afa87cd7ae810620]
---
# Header1
Please do **not** do this.
This is *cool*!
Go _here_.
A googol is 10^100^
A glass of H~2~O.
One|two|three
I am ___ years old.
equals = \=
---
>This is a bullet point>
>This is a second bullet point>
>This is a bullet followed by>>another bullet point>

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.

For stories, the caption is omitted and you just use[type url]

Drill entry 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/Story details

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

Directive	Purpose	Example	Conditions
@NAME	Set drill/story name	@NAME Counting in Russian
@SUBJ	Set drill/story subject	@SUBJ Russian
@DESC	Set drill/story description	@DESC Learn to count in Russian
@ICON	Set drill/story icon	@ICON [image/png https://example.com/icon]
@COVER	Set drill/story cover	@COVER [image/png https://example.com/cover]
@TAGS	Set drill/story tags	@TAGS #counting #russian
@COLS	Set drill column names	@COLS English = Russian	Only applies to Drill drilldown documents
@TYPE	Set drill/story type	@TYPE Drill, @TYPE Story	Optional for Drill drilldown documents, mandatory for Story drilldown documents

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.

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

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.