Uten navn

### 0.1 Lesbestanden

Als je zelf lesbestanden wilt schrijven, kun je het beste kijken naar de bestaande lesbestanden in lesson-files/. Gebruik dit document en het muziekformaat document als naslagwerk.

#### 0.1.1 De inhoud van een lesbestand

Een lesbestand bestaat uit een zogenaamd header-blok en een of meerdere question-blokken:

         header {
           toekenning
           toekenning
           ...
         }
         question {
           toekenning
           ...
         }

#### 0.1.2 Het headerblok

Het headerblok kun je overal in het bestand opnemen. Het is echter gebruikelijk om dit blok aan het begin van het bestand op te nemen. Als je meer dan een headerblok opgeeft zal Solfege alleen de eerste gebruik en de overigen negeren. Dit kan bijvoorbeeld voorkomen als je het `include` commando gebruikt.

Definities die je kunt gebruiken in het headerblok:

`title = tekst`
  Een korte eenlijnige omschrijving.
`description = tekst`
  Een lange omschrijving waarin je zelfs html-tags mag opnemen.
`content = lijst`
  Mogelijke waardens: `chord`, `dictation`, `id-by-name`, `harmony` en `sing-chord`

  Sommige lesbestanden kun je gebruiken voor meer dan een oefening. Een lesbestand met akkoorden kun je bijvoorbeeld ook heel goed gebruiken bij de Identificeer via naam oefening. Je moet hier in dit geval `content = chord, id-by-name` gebruiken.

`musicformat = FORMAT`
  `normal` : The default value `chord` : any music "MUSIC CODE" will be interpreted as:

                          \staff{ < MUSIC CODE > }

  or

                          \staff\transpose NOTENAME{ < MUSIC CODE > }

  `musicformat = chord` is necessary if lesson files written for the chord exercise should be used by for example the id-by-name exercise.

  `satb` : the music `"c | bes g | e | G C"` will be interpreted as:

                       \staff{ \stemUp < c > }
                       \addvoice{ \stemDown < bes g > }
                       \staff{\clef bass; \stemUp < e > }
                       \addvoice{ \stemDown < G C > }

  This is used by the sing-chord exercise.

`random_transpose = yes | no`
  (Default: no) In some exercises the program can transpose the music to create variation. The variable is ignored in exercises that does not support transposing.
`labelformat = normal | progression`
  (Default: normal)

##### 0.1.2.1 For "Id by name" exercise only

`filldir = horiz | vertic`
`fillnum = INTEGER`
  These two variables control how the buttons are layed out. `filldir` tell the direction the buttons are filled, and `fillnum` tell how many buttons there are in each row or column.

#### 0.1.3 Question block

`name = "some short name"`
  Questions written for id-by-name and chord exercise need a name.
`music = "\staff{c'2 g' e4 e c1}"`
  The music in the question. Note that there is a shortcut. Instead of:

                   question {
                   tempo = 160/4
                   name = "Lisa gikk til skolen"
                   music = "\staff\relative c'{c d e f g2 g2}"
                }

  you can write:

                question {
                   tempo = 160/4
                   name = "Lisa gikk til skolen"
                   "\staff\relative c'{c d e f g2 g2}"
                }

`tempo = 130/4`
  beats per minute / notelen per beat

##### 0.1.3.1 Chord questions only

In lesson files that is written to work with `chord` exercise, two more variables can used:

`inversion`
  0 = root position, 1 = first inversion etc.
`toptone`
  1, 3, 5, 7

##### 0.1.3.2 Dictation exercise

By default, the dictation exercise will show the first column of music, and then the user should write the rest. But if the first column is not good enough, if there for example are only rests on the first beat, these two variables can tell the program how much music to display:

`clue_end = nn/dd`
  `clue_end=1/4` will display all music in the first quarter note.
`clue_music = MUSIC`
  Write the exact music you want to display. If for example you want to display the whoe bar in the upper staff, and only one note in the lower staff.

(Use only one if these variables in a question. Using both are undefined.)

##### 0.1.3.3 Sing chord exercise

Questions for this exercise need to have the `key` variable set if the key signature is anything else than c major (or a minor). Example:

         question { "c''|e'|g|c" }
         question { "a'|e'|c'|a" }
         question { key="d \major" "a'|fis'|d'|d"}
         question { key="f \minor" "as'|f'|c'|f"}

#### 0.1.4 Global variables

Global variables can save you a few key strokes.

         s = "\score\relative c'{ %s }

         question {
           # instead of music = "\score\relative c'{ c d e f g2 g2 } :
           music = s % "c d e f g2 g"
         }

The global variable `tempo` will be the default tempo for the questions following the definition. If not set, the default value is 120 beats per minute. That equals the definition

`tempo = 60/4`

#### 0.1.5 Comments

Everything after # on a line is ignored

#### 0.1.6 Grammar

Disclaimer: I don't know any of the standard ways of describing grammar, like BNF. So this is just an attemt to describe the file format to get people started writing lesson files.

Lessonfiles consists of assignment statements and blocks containing assignment statements.

##### 0.1.6.1 Functions

`_`
  takes a string as its only argument. Use this if you want Solfege to translate the string for you. Example:

  `description = _("This is a short description")`

`include`
  includes another file in to this file. Example:

  `include(singchord-1)`

##### 0.1.6.2 Types

`string`
  is quoted using the `"` character, like this: `"this is a string"`. The string can contain line breaks, so this is valid:

                description = "<h1>Long desription</h1>
                               This lessonfile need very much descriptions.
                               bla bla bla"

  If the string need to contain the `"` character, you have to use tripple quotes:

                description = """Try <a href="solfege:practise/melodic-interval">this
                </a> for a simpler interval exercise."""

`integer`
  is an integer is an integer...
`tempotype (in lack of a better name)`
  is entered as `bpm/beatlen`. An example:

  `tempo = 120/4`

  will set the tempo to 120 beats per minute, each beat being a quarter note.

#### 0.1.7 Operators

The operators can only be used on strings

`+`
  is used for joining strings
`%`
  is similar to what you find in python, but it is very limited. It only know about `%s`. Examples:

                "\staff\relative c'{%s}" % "c d e"

  evaluates to

                "\staff\relative c'{c d e}"

#### 0.1.8 Reserved words

To be put on the right side of assignments. The current parse does not complain if you redefines the identifiers, so don't do that!

`chord, dictation, id-by-name, sing-chord`
  Possible values for `content`
`horiz, vertic`
  Table filling in id-by-name exercise
`normal, progression`
  `labelformat` values.
`yes, no`

#### 0.1.9 Identifiers

Identifiers match the regular expression "[a-zA-Z]+[\w_-]*".

#### 0.1.10 Block

There are two block types, `header` and `question`

         blocktype {
           CONTENTS
         }