Script structure¶

An Automathics script is a YAML-based definition for worksheets and slideshows. A script file maps names to script definitions, each containing metadata and a single exercise (a block of one or more questions).

script_name:
  - preset: "grid"
  - title: "My worksheet"
  - exercise:
    - shuffle_questions: true
    - questions: |
        (3) multi_direct 2-9×2-9
        (2) divi_direct 2-9×2-9 -- variant=one_nth_of

preset is mandatory and determines the document type ("grid" or "slideshow"). shuffle_questions is optional. Questions are defined in a YAML literal block string under the questions: key.

Comments¶

A # opens a comment: the rest of the line is ignored, and a line holding nothing else is skipped. This holds everywhere in a script file, the questions: block included — where a comment is not YAML's business, since a literal block hands its lines over verbatim, but Automathics honours it just the same:

# The white belt tables, revised each September.
tables:
  - preset: "grid"
  - title: "My worksheet"     # to rename
  - exercise:
    - questions: |            # ten questions in all
        # the two easy ones first
        (2) multi_direct 2-5×2-5
        (8) multi_direct 2-9×2-9   -- variant=wording

As in YAML, a # only opens a comment when it starts the line or follows a space. To use the character itself in a title or any other free-text field, quote the value:

  - title: "Exercise #3"

Without the quotes, title: Exercise #3 titles the document Exercise — #3 is a comment.

Apart from that #, a free-text field needs no quoting at all: title, title_prefix, header, subtitle, text, answers_title and wording are quoted for you before the file is read, so prose holding a : — title: Calcul : les aires — parses verbatim instead of being taken for a mapping. A value you quote yourself is left as you wrote it, and so is one you wrap onto a second line:

  - title: A title long enough
      to be wrapped

reads as A title long enough to be wrapped, as YAML says it should. The same holds for the q and a fields of an .atmxs snapshot.

Language¶

A free-text field is rendered verbatim, in the language you wrote it in. Nothing in a script is translated: the shipped scripts live under data/content/<locale>/ — fr_FR/6e/cm1_blanche.yaml and so on — and each tree is authored in its own language. Serving another language means another content tree, with its own school levels and its own progression, not a translation of this one.

What does follow the render locale is everything Automathics writes itself: the page furniture and the wordings of the generated questions. So --locale=en_US on a fr_FR script gives English question wordings under a French title — pick the wording language with --locale, the content tree with --sl-locale.

A slideshow takes one section of its own besides: title_prefix, which heads the name of the browser tab — see Using HTML slideshows.

answers_title, header, subtitle and text are accepted at the top level but not implemented yet: a grid document titles its answers page after its own title, and the other three reach no template. A script carrying one stays valid — validation reports it as having no effect for now, so nobody counts on a customisation that does not happen. They may be honoured later without any change to existing scripts.