If you want to write lesson files, my advise is to look at some of the files in lesson-files/ and use this document and the music format spec for reference. To use the lesson files, you have to save them in $HOME/lessonfiles/.
New in version 2.0 is that Solfege by default expect the content of lesson files to be in UTF-8 encoding. gedit is a nice little editor that let you edit unicode files.
If you don't like unicode, you can tell Solfege that the file has another encoding by inserting a special comment line as the first line of the file. The following example set the charset to ISO 8859-1, a charset commonly used in many west-european language:
# -*- coding: iso-8859-1 -*-
Russians might wan't to use koi8-r:
# -*- coding: koi8-r -*-
The program use the python libs to convert to unicode, so it should understand almost any encoding you can think of. If you see some characters are missing, for example when the name of questions are displayed on buttons, then most likely you have done somethings from with the encoding.
A lesson file contains of a header block and one or more question blocks:
header { ASSIGNMENT ASSIGNMENT ... } question { ASSIGNMENT ... }
The header block can be placed anywhere in the file, but by convention it should be the first block in the file. If more that one header block is found, for example when using the include function, only the first header block is used, the rest are ignored.
Definitions to put in the header block:
Tell the oldest version of solfege the lessonfile is known to work with. For example version = "1.1.1" This variable is not required, but it should be used because it can (but don't guarantee to) help avoid trouble if the lesson file format changes in the future.
Short oneline description.
Long description that can contain html tags.
Possible values: chord, dictation, id-by-name, harmony and sing-chord
Some lessonfiles can be useful for more than one exercise. For example, a file with chords can also be used by the id-by-name exercise, and should have: content = chord, id-by-name
The default value.
Any music "MUSIC CODE" will be interpreted as:
\staff{ < MUSIC CODE > }
or:
\staff\transpose NOTENAME{ < MUSIC CODE > }
chord format is necessary if lesson files written for the chord exercise should be used by for example the id-by-name exercise.
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.
In some exercises the program can transpose the music to create variation. The variable is ignored in exercises that does not support transposing.
This is the default value. No transposition will be done.
The exercise will do random transposition. What kind of transposition depends on the exercise, but you get a ok result from this.
Transpose the music by random. But make sure the number of flats or sharps are within the range specified by INTEGER, INTEGER. To explain how this works, think of flats as negative numbers and sharps as positive numbers. The code
random_transpose = accidentals, -2, 3
will give you questions with 1 or 2 flats, 0 accidentals or 1, 2 or 3 sharps. The code
random_transpose = accidentals, 2, 3
will create questions with two or three sharps.
Please notice that the music in the lessonfile has to be in c major or a minor for this to work correctly.
Transpose the music INTEGER1 steps down or INTEGER2 steps steps up the circle of fifth. (And by my own definition, up is more sharps and down is more flats ... :-) )
Transpose the music at most INTEGER1 steps down or INTEGER2 steps down. The code
random_transpose = semitones, -2, 6
will transpose the questions no more than 2 semitones down and 6 semitones up. This is the same as the old random_transpose = INTEGER, INTEGER syntax.
(Default: normal)
Questions written for id-by-name and chord exercise need a name.
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}" }
beats per minute / notelen per beat
In lesson files that is written to work with chord exercise, two more variables can used:
0 = root position, 1 = first inversion etc.
1, 3, 5, 7
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=1/4 will display all music in the first quarter note.
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.)
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
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.
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")
includes another file in to this file. Example:
include(singchord-1)
is quoted using the " character, like this: "this is a string". Use tripple quotes for strings that contain line breaks:
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."""
NB: All strings have to be unicode strings. You can change the encoding of a file using the iconv program:
iconv -f YOUR_ENCODING -t utf8 your.file
is an integer is an integer...
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.
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. One example:
"\staff\relative c'{%s}" % "c d e"
evaluates to
"\staff\relative c'{c d e}"
To be put on the right side of assignments. The current parser does not complain if you redefines the identifiers, so don't do that!
Possible values for content
Used for table filling in id-by-name exercise
labelformat values.