Tutor

Create bold text.

*bold* gives bold.

Create a numeric callout for the digits 1—​9.

Callouts are used to attach numeric labels to a source code [Listing] for later discussion in the text.

[source]
----
This code contains the callout <1>
----
will produce

By including <1> in an enumeration or text, for instance,

<1> refers to the callout.

will give:

Callout are most usefull to place markers in code fragments for later reference in explanatory text.

Create inline code fragments.

Creates inline fragments of text that represent code. Inside the MarkedText, other markup can be used.

` if ` --- that is ` followed by if followed by ` --- gives if.

Refer to an external URL.

Creates a link to an external url URL. When MarkedText is present, a clickable hyperlink is included with the text Name. Otherwise URL itself is included as clickable hyperlink.

gives http://www.rascal-mpl.org and

gives Rascal. Try it!

Include an image.

Describes an image to be included:

For further styling of images, see http://asciidoctor.org/docs/user-manual/#images.

Create italic text.

_italic_ gives: italic.

Refer to a concept in this course or another course.

Recall that a concept is known under two names, its concept name (the file name of the concept) and its display name (the name as displayed in the text).

The first two forms create a link to a concept in the current course.

The remaining two forms create a link to a concept in another course.

The first creates a link to a complete course, the second to a specific concept in an external course.

The concept name of this concept is ReferenceToConcept while its display name is Reference to Concept (note the spaces).

We can create a reference to the InlineMarkup concept in the current course in the following ways:

Here is a reference to another course:

Note the / before the course name in refernces to another course.

Markup for a variable.

Variables in text and code are represented by Italic markup. They may be followed by one or more subscripts (enclosed by ~ and ~) or superscripts (enclosed by ^ and ^)

Multiple-choice question.

Asks a multiple-choice questions described by MarkedText. OptName is an optional name of the question (enclosed between [ and ]). If OptName is missing, the question gets a unique number as name.

Each possible Choice is preceded by a good (g) or bad (b) marker. When generating a question 3 choices (including one good answer) are presented in random order.

Providing more good and bad answers will therefore create more variation in the generated questions.

will produce the question Faster in the questions section below.

And, by the way, the High-speed train wins with over 570 km/hour compared to Ferrari (315 km/hour), Apache (293 km/hour) and Hovercraft (137 km/hour).

A text question with a free-format answer.

Presents a text questions consisting of Text. OptName is an optional name of the question (enclosed between [ and ]). If OptName is missing, the question gets a unique number as name.

The user can give a free format answer, and that is accepted if it contains one of the given answers answer₁, Answer₂ as substring.

The markup

Will generate question Tall in the questions section below. The answer is obvious: the Empire State Building is 443.2 meters tall while the Eifel Tower is 324 meters tall. Any answer that contains Empire will be accepted.

A question about a Rascal type.

A type question presents a Rascal expressions and poses a question about its type.

OptName is an optional name of the question (enclosed between [ and ]). If OptName is missing, the question gets a unique number as name.

The desired type is given by a TypeDescriptor.

The first form presents the value generated for the TypeDescriptor and asks about its type.

The second form allows more preparatory steps and also allows adding a listing to the question.

See the effect of the following type questions in the Questions section below.

Description of a Rascal type used in type and value questions.

A TypeDescriptor is one of

A TypeDescriptor is used to describe Rascal types and values in questions and are used to automatically generate values of the described type. TypeDescriptors largely follow the types as available in Rascal, with the following extensions that are helpfull when generating values:

Question about the value of a Rascal expression or program.

A value question presents a Rascal expression and poses a question about its value.

OptName is an optional name of the question (enclosed between [ and ]). If OptName is missing, the question gets a unique number as name.

The desired type of the expression is given by a TypeDescriptor.

The first form presents the value generated for the TypeDescriptor and asks about its value.

The second form allows more preparatory steps and also allows adding a listing to the question. The following steps are defined:

The following restrictions apply:

See the effect of the following value questions in the Questions section below.

Include the concepts in a Rascal source module in a course.

Each Rascal source file defines a module M that may declare concepts M/c1, M/c2, …​. as indicated by embedded @doc annotations. How are these concepts included in a Tutor course?

The answer is a remote concept file.

Where an ordinary concept C is defined by a subdirectory C and a concept file C/C.concept a remote concept is defined by C/C.remote that contains the location of the source file, say CLoc.

Cloc will be parsed, all its concepts will be extracted and all these concepts become subconcepts of C.

Moving the documentation for a library file is as simple as moving C to another position in the concept hierarchy.

The DateTime library module is defined in the Libraries course by the subdirectory Libraries/Prelude/DateTime and the file DateTime/DateTime.remote. The latter contains a single line with the location of the DateTime module:

This establishes, for instance, that the function now that is declared in the DateTime.rsc library file will become the concept Libraries/Prelude/DateTime/now.

A doc annotation attaches an inline concept description to a Rascal declaration.

All Rascal declarations can be preceeded by an annotation of the form @doc{ …​ } where …​ may be arbitrary text, provided that { and } characters are balanced and that unbalanced braces are escaped like \{ or \}. This text is expanded to a full concept definition when the concept is processed.

The Tutor supports and expands inline concept descriptions for the following declarations types.

Mark up for admonitions.

An admonition is remark that should draw the reader’s attention.

The input

NOTE: This is a note.

gives

The input:

WARNING: Use warnings sparingly.

will give:

An admonition should start at the begin of a line and the : should be followed by a single space.

A (possible nested) list of bullet points.

Bullet lists create, possibly nested, lists of points. The number of * characters determines the nesting level of a (sub)list.

A list item ends with:

Bullet Lists and Numbered Lists can be mixed. See http://asciidoctor.org/docs/user-manual/#unordered-lists for the precise rules.

The input

will produce:

The input

will produce:

An empty line is required before and after a BulletList.

Mark up for a named paragraph.

A NamedParagraph produces a named paragraph of a level that is determined by the number of # characters preceding the ParagraphName.

The input:

## Paragraph

will give

Introduce a new paragraph.

A new paragraph is created by a single empty line.

The input:

will produce:

line1 line2

line3 line4

A (possibly nested) list of numbered points.

Numbered Lists create, possibly nested, lists of numbered points. They either start with a period (.) or a number. The number of periods indicates the nesting level.

A list item ends with:

Bullet Lists and Numbered Lists can be mixed. See http://asciidoctor.org/docs/user-manual/#ordered-lists for the precise rules.

The input

will produce:

The input

will produce:

An empty line is required before and after a NumberedList.

Mark up for a table.

The simplest table starts and ends with |===, each row is separetd by an empty line and each column starts with |. There are, hwoever, other formats and options to specify the formatting of cells and columns. See http://asciidoctor.org/docs/user-manual/#tables for details.

Generate a local table of contents of current concept.

loctoc::[Depth]

Generate a local table of contents for all subconcepts of the current concept to a depth of Depth. When OptDepth is missing, 1 will be used as default depth.

This is useful for summary pages.

A table of contents of 1 level deep is generated by loctoc::[1]. The local table of contents for this course is generated by loctoc[3], see Tutor.