~ubuntu-branches/ubuntu/saucy/solfege/saucy

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Lesson files</title><link rel="stylesheet" href="../style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="GNU Solfege 3.14.5 Manuel utilisateur"><link rel="up" href="extending-solfege.html" title="Chapitre 4. Extending GNU Solfege"><link rel="prev" href="extending-solfege.html" title="Chapitre 4. Extending GNU Solfege"><link rel="next" href="chord-module.html" title="The chord module"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Lesson files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="extending-solfege.html">Précédent</a> </td><th width="60%" align="center">Chapitre 4. Extending GNU Solfege</th><td width="20%" align="right"> <a accesskey="n" href="chord-module.html">Suivant</a></td></tr></table><hr></div><div class="sect1" lang="fr"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="lesson-files"></a>Lesson files</h2></div></div></div><p>In GNU Solfege, each exercise is created by a lesson file

interpreted by one of the exercise modules.</p><div class="variablelist"><p class="title"><b>Exercise modules</b></p><dl><dt><span class="term">

<code class="literal">harmonicintervals</code></span></dt><dd><p>Train harmonic intervals.</p></dd><dt><span class="term">

<code class="literal">melodicintervals</code></span></dt><dd><p>Train one or more melodic intervals.</p></dd><dt><span class="term">

<code class="literal">singinterval</code></span></dt><dd><p>This is an exercise where the

program display an interval and play the first tone. Then the user

should sing the interval, and then click a button to hear the correct

answer. There is no microphone support yet.</p></dd><dt><span class="term">

<code class="literal">idbyname</code></span></dt><dd><p>This is a very

generic exercise. In its most basic form, the program will play some sound,

and you have to select among several buttons that in some way represents

the music.</p></dd><dt><span class="term">

<code class="literal">chord</code></span></dt><dd><p>The chord module act as a specialized

idbyname module. The difference is that with the chord module

you can write lesson files where the user should tell what inversion the

chord is in, and what the top tone is.</p></dd><dt><span class="term">

<code class="literal">chordvoicing</code></span></dt><dd><p>A two-step

exercise. First you should identify the chord. Then you should stack the

tones in the chord in the correct order.</p></dd><dt><span class="term">

<code class="literal">compareintervals</code></span></dt><dd><p>Solfege

plays two intervals, and you should say which one is largest.</p></dd><dt><span class="term">

<code class="literal">rhythm</code></span></dt><dd><p>A simple rhythm exercise. Solfege will randomly generate

rhythm patterns that the user should recreate by clicking on

buttons.</p></dd><dt><span class="term"><code class="literal">dictation</code></span></dt><dd><p></p></dd><dt><span class="term"><code class="literal">harmonicprogressiondictation</code></span></dt><dd><p></p></dd><dt><span class="term"><code class="literal">idtone</code></span></dt><dd><p></p></dd><dt><span class="term"><code class="literal">identifybpm</code></span></dt><dd><p></p></dd><dt><span class="term"><code class="literal">twelvetone</code></span></dt><dd><p></p></dd><dt><span class="term"><code class="literal">singchord</code></span></dt><dd><p></p></dd></dl></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="File-encoding"></a>File encoding</h3></div></div></div><a class="indexterm" name="id2730208"></a><p>Solfege by default expects the content of lesson files to be in UTF-8

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Lesson files</title><link rel="stylesheet" href="../style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="GNU Solfege 3.15.9 Manuel utilisateur"><link rel="up" href="extending-solfege.html" title="Chapitre 4. Extending GNU Solfege"><link rel="prev" href="extending-solfege.html" title="Chapitre 4. Extending GNU Solfege"><link rel="next" href="chordvoicing-module.html" title="The chordvoicing module"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Lesson files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="extending-solfege.html">Précédent</a> </td><th width="60%" align="center">Chapitre 4. Extending GNU Solfege</th><td width="20%" align="right"> <a accesskey="n" href="chordvoicing-module.html">Suivant</a></td></tr></table><hr></div><div class="sect1" title="Lesson files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="lesson-files"></a>Lesson files</h2></div></div></div><p>In GNU Solfege, each exercise is created by a lesson file

interpreted by one of the exercise modules.</p><p>Deprecated modules: chord, harmonicprogressiondictation,

</p><p>Missing documentation: chordvoicing, identifybpm, twelvetone

</p><div class="sect2" title="File encoding"><div class="titlepage"><div><div><h3 class="title"><a name="File-encoding"></a>File encoding</h3></div></div></div><a class="indexterm" name="id2669711"></a><p>Solfege by default expects the content of lesson files to be in UTF-8

encoding.

Modern editors often let you

specify the encoding in the "Save As" dialog. One example is

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 something wrong

with the encoding.</p></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="Useful-characters"></a>Useful unicode characters</h3></div></div></div><p>Unicode has some characters that you might want to use to make labels

with the encoding.</p></div><div class="sect2" title="Useful unicode characters"><div class="titlepage"><div><div><h3 class="title"><a name="Useful-characters"></a>Useful unicode characters</h3></div></div></div><p>Unicode has some characters that you might want to use to make labels

look more professionally. If your editor use unicode by default, you may

copy-and-paste the characters you need from here, if you are viewing this

documentation in a web browser. The number is a hexidecimal number.</p><div class="variablelist"><dl><dt><span class="term">ø <code class="literal">00F8 LATIN SMALL LETTER O WITH STROKE</code></span></dt><dd><p>Half-diminished seventh chord.</p></dd><dt><span class="term">° <code class="literal">00B0 DEGREE SIGN</code></span></dt><dd><p>Diminished seventh chord.</p></dd><dt><span class="term">△ <code class="literal">25B3 WHITE UP-POINTING TRIANGLE</code>, </span><span class="term">Δ <code class="literal">0394 GREEK CAPITAL LETTER DELTA</code></span></dt><dd><p>Major seventh chord. We do not know

the symbol you like.

</p></dd><dt><span class="term">♭ <code class="literal">266D MUSIC FLAT SIGN</code></span></dt><dd><p>This sign can be used instead of the letter 'b' for a

flat sign.</p></dd><dt><span class="term">♯ <code class="literal">266F MUSIC SHARP SIGN</code></span></dt><dd><p>This can be used instead of the letter '#' for the

sharp sign.</p></dd></dl></div></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="Comments"></a>Comments</h3></div></div></div><a class="indexterm" name="id2730418"></a><p>Everything after # on a line is ignored. Example:</p><pre class="programlisting"># This line is ignored. The next line is not.

sharp sign.</p></dd></dl></div></div><div class="sect2" title="Comments"><div class="titlepage"><div><div><h3 class="title"><a name="Comments"></a>Comments</h3></div></div></div><a class="indexterm" name="id2669917"></a><p>Everything after # on a line is ignored. Example:</p><pre class="programlisting"># This line is ignored. The next line is not.

question { bla bla }

</pre></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="Types"></a>Types</h3></div></div></div><div class="sect3" lang="fr"><div class="titlepage"><div><div><h4 class="title"><a name="lf-types-strings"></a>Strings</h4></div></div></div><a class="indexterm" name="id2730450"></a><p>Strings are quoted with the <code class="literal">"</code> character. Example:</p><pre class="programlisting">"this is a string"</pre><p>Use tripple quotes for strings that contain line breaks, or

</pre></div><div class="sect2" title="Types"><div class="titlepage"><div><div><h3 class="title"><a name="Types"></a>Types</h3></div></div></div><div class="sect3" title="Strings"><div class="titlepage"><div><div><h4 class="title"><a name="lf-types-strings"></a>Strings</h4></div></div></div><a class="indexterm" name="id2669949"></a><p>Strings are quoted with the <code class="literal">"</code> character. Example:</p><pre class="programlisting">"this is a string"</pre><p>Use tripple quotes for strings that contain line breaks, or

if the string itself has to contain the <code class="literal">"</code> character:</p><pre class="programlisting">

description = """<h1>Long desription<h1> This lessonfile need

very much descriptions. Qoutes (") are ok here. bla bla bla"""</pre><p>NB: All strings have to be unicode strings. If you get error messages like this one:</p><pre class="programlisting">

(line 21): question {

(line 22): name = _("Ionia�)

</pre><p>then you must check the encoding of your file, and maybe you should

read <a class="xref" href="lesson-files.html#File-encoding" title="File encoding">la section intitulée « File encoding »</a>. You can change the encoding of a file using the <span class="command"><strong>iconv</strong></span> program:</p><pre class="programlisting">iconv -f YOUR_ENCODING -t utf8 your.file</pre></div><div class="sect3" lang="fr"><div class="titlepage"><div><div><h4 class="title"><a name="lf-type-tempo"></a>Tempo</h4></div></div></div><p>The tempo of music is entered as <code class="literal">bpm/beatlen</code>. The

read <a class="xref" href="lesson-files.html#File-encoding" title="File encoding">la section intitulée « File encoding »</a>. You can change the encoding of a file using the <span class="command"><strong>iconv</strong></span> program:</p><pre class="programlisting">iconv -f YOUR_ENCODING -t utf8 your.file</pre></div><div class="sect3" title="Tempo"><div class="titlepage"><div><div><h4 class="title"><a name="lf-type-tempo"></a>Tempo</h4></div></div></div><p>The tempo of music is entered as <code class="literal">bpm/beatlen</code>. The

following example will set the tempo to 120 beats per minute, each beat being a

quarter note.</p><pre class="programlisting">tempo = 120/4</pre></div></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="Global-variables"></a>Global variables</h3></div></div></div><a class="indexterm" name="id2730815"></a><p>Global variables can save you a few key strokes.</p><pre class="programlisting">

quarter note.</p><pre class="programlisting">tempo = 120/4</pre></div></div><div class="sect2" title="Global variables"><div class="titlepage"><div><div><h3 class="title"><a name="Global-variables"></a>Global variables</h3></div></div></div><a class="indexterm" name="id2670044"></a><p>Global variables can save you a few key strokes.</p><pre class="programlisting">

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

question {

# instead of music = music("\score\relative c'{ c d e f g2 g2 }")

music = music(s % "c d e f g2 g")

}

</pre></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="Lesson-file-contents"></a>Lesson file contents</h3></div></div></div><p>A lesson file consist of one header block and zero or more

</pre></div><div class="sect2" title="Lesson file contents"><div class="titlepage"><div><div><h3 class="title"><a name="Lesson-file-contents"></a>Lesson file contents</h3></div></div></div><p>A lesson file consist of one header block and zero or more

question blocks:</p><pre class="programlisting">

header {

ASSIGNMENT

...

}

</pre></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="Header-block"></a>Header block</h3></div></div></div><a class="indexterm" name="id2730858"></a><p>The header block can be placed anywhere in the file, but by convention it should be the first block in the file.</p><div class="variablelist"><a name="lesson-header-vars"></a><p class="title"><b>Variables shared by many exercise modules</b></p><dl><dt><span class="term">

</pre></div><div class="sect2" title="Header block"><div class="titlepage"><div><div><h3 class="title"><a name="Header-block"></a>Header block</h3></div></div></div><a class="indexterm" name="id2670091"></a><p>The header block can be placed anywhere in the file, but by convention

it should be the first block in the file. And there is a limitation that

the header has to be within the first 40000 characters of the file.</p><div class="variablelist" title="Variables shared by many exercise modules"><a name="lesson-header-vars"></a><p class="title"><b>Variables shared by many exercise modules</b></p><dl><dt><span class="term">

<code class="varname"><a name="lf-module"></a>module</code></span></dt><dd><p>Tell what execise module that will run the lesson file. This

variable is requried for all lesson files. (The variable was added in

Solfege 2.9.0 where it replaced the <code class="varname">content</code>

variable.). Example:</p><pre class="programlisting">module = idbyname</pre></dd><dt><span class="term"><code class="literal"><a name="lf-lesson_id"></a>lesson_id</code></span></dt><dd><a class="indexterm" name="id2730918"></a><p>Each file need a unique identifier. The identifier can be any string

variable.). Example:</p><pre class="programlisting">module = idbyname</pre></dd><dt><span class="term">

<code class="varname"><a name="lf-replaces"></a>replaces</code></span></dt><dd><p>A string or list of strings with hash values of lesson files that

this lesson file can replace without dropping the statistics. Use this only when

you know what you are doing. The hash value is calculated by

<code class="literal">solfege.lessonfile.hash_of_lessonfile()</code>.

<span class="command"><strong>tools/hash-of-file.py</strong></span> can be used to get the hash value

of files before modifying them.</p><pre class="programlisting">replaces = "bf7dd374206451bff43d61fc8191f5fb3e88d007"

replaces = "bf7dd374206451bff43d61fc8191f5fb3e88d007", "cdb2f9415171650ee7682028788c1c42c62fdbf"

</pre></dd><dt><span class="term"><code class="literal"><a name="lf-lesson_id"></a>lesson_id</code></span></dt><dd><a class="indexterm" name="id2670458"></a><p class="remark"><i><span class="remark">This variable is deprecated in Solfege 3.15.3. It should remain in

existing lesson files for some time for backward compatability. But it should

not be added to new lesson files.</span></i></p><p>Each file need a unique identifier. The identifier can be any string

you like, and if you don't add one, Solfege will add one for you. Solfege

will also offer to create a new <code class="literal">lesson_id</code> if you have

two files with identical <code class="literal">lesson_id</code>. Example:

</p><pre class="programlisting">lesson_id = "5b30c9ae-09f1-40b3-9333-4789638dc851"</pre></dd><dt><span class="term">

<code class="varname"><a name="lf-version"></a>version</code></span></dt><dd><p>

Tell the version of

100

solfege the lessonfile is known to work with. This variable is not

101

required, but it should be used because it can (but don't guarantee to)

103

Example:</p><pre class="programlisting">version = "3.0.7"</pre></dd><dt><span class="term">

104

105

<code class="varname"><a name="lf-title"></a>title</code></span></dt><dd><p>

106

107

100

Short one-line description that will be used for

108

101

creating the menu entry for the exercise. You should add this to all lesson

109

102

files. Example:</p><pre class="programlisting">title = "Minor and major chords in root position"</pre></dd><dt><span class="term">

110

103

111

104

<code class="varname"><a name="lf-lesson_heading"></a>lesson_heading</code></span></dt><dd><p>

112

105

113

106

A short heading that will be displayed above the exercise. It

114

107

should say what the purpose of the exercise is. Some modules provide a

115

108

default value, others leave the string empty. Example:</p><pre class="programlisting">lesson_heading = _("Identify the chord")</pre></dd><dt><span class="term">

116

109

117

110

118

111

119

112

This variable say which help file from the user manual will be

120

113

displayed when the user presses F1.

121

114

Example:</p><pre class="programlisting">help = "idbyname-intonation"</pre><p>By default, Solfege will display the help file that has the same

122

115

name as the exercise module being used in the lesson file.</p></dd><dt><span class="term">

123

116

124

117

<code class="varname"><a name="lf-theory"></a>theory</code></span></dt><dd><p>

125

118

126

119

This variable say which help file from the user manual will be

127

120

displayed when the user presses F3. Pressing F3 should display

128

121

music theory about the exercise. Don't include this variable if there

129

122

are no music theory written.

130

123

Example:</p><pre class="programlisting">theory = "scales/maj"</pre></dd><dt><span class="term">

131

124

132

<code class="varname">random_transpose</code></span></dt><dd><a class="indexterm" name="id2731115"></a><p>In some exercises the program can transpose the music to

125

<code class="varname">random_transpose</code></span></dt><dd><a class="indexterm" name="id2670661"></a><p>In some exercises the program can transpose the music to

133

126

create variation. The default value is <code class="literal">yes</code>. (The

134

127

default value changed from <code class="literal">no</code> to

135

128

<code class="literal">yes</code> in Solfege 3.0.)</p><p>Used in modules: <code class="literal">chord</code>,

136

129

<code class="literal">chordvoicing</code>, <code class="literal">harmonicprogressiondictation</code>,

137

130

<code class="literal">idbyname</code>, <code class="literal">singanswer</code>,

138

<code class="literal">singchord</code></p><div class="variablelist"><p class="title"><b>Possible values</b></p><dl><dt><span class="term">random_transpose = no</span></dt><dd><p>No transposition will be done.</p></dd><dt><span class="term">random_transpose = yes</span></dt><dd><p>The exercise will do random transposition. What

131

<code class="literal">singchord</code></p><div class="variablelist" title="Possible values"><p class="title"><b>Possible values</b></p><dl><dt><span class="term">random_transpose = no</span></dt><dd><p>No transposition will be done.</p></dd><dt><span class="term">random_transpose = yes</span></dt><dd><p>The exercise will do random transposition. What

139

132

kind of transposition depends on the exercise, but you get a

140

133

ok result from this. This is the default value.</p></dd><dt><span class="term">random_transpose = accidentals, INTEGER1, INTEGER2</span></dt><dd><p>

141

134

Transpose the question by random and make sure the key signature

145

138

flats (b), and a positive number denote a number o sharps (#).

146

139

Zero mean no accidentals. The integers INTEGER1 and INTEGER2

147

140

defines a range of allowed number of accidentals.

148

</p><p>

149

For this transposition mode to work properly, the music in

150

the lessonfile has to be in the keys c major or a minor,

151

or the question must have a <code class="varname">key</code>

152

variable telling the key signature.

153

</p></dd><dt><span class="term">random_transpose = key, INTEGER1, INTEGER2</span></dt><dd><p>

141

</p><p>For this to work properly the music must

142

either be in C major or A minor, or the key of the music has

143

to be set with the

144

<a class="link" href="lesson-files.html#lf-key"><code class="literal">key</code></a> variable.

145

</p></dd><dt><span class="term">random_transpose = key, INTEGER1, INTEGER2</span></dt><dd><p>

154

146

Transpose the music INTEGER1 steps down or INTEGER2 steps up the

155

147

circle of fifth. In this context up is more sharps and down is

156

148

more flats. This is real transposition where both the key and the

157

notes are transposed.

158

</p></dd><dt><span class="term">random_transpose = semitones, INTEGER1, INTEGER2</span></dt><dd><p>

149

notes are transposed.</p><p>For this to work properly the music must

150

either be in C major or A minor, or the key of the music has

151

to be set with the

152

<a class="link" href="lesson-files.html#lf-key"><code class="literal">key</code></a> variable.

153

</p></dd><dt><span class="term">random_transpose = semitones, INTEGER1, INTEGER2</span></dt><dd><p>

159

154

Transpose the music at most INTEGER1 semitones down or INTEGER2

160

155

semitones up. This is real transposition where both the key and

161

156

the notes are transposed. You will easily end up with music in the

162

157

keys with LOTS of accidentals.

158

</p></dd><dt><span class="term">random_transpose = atonal, INTEGER1, INTEGER2</span></dt><dd><p>

159

Transpose the music at most INTEGER1 semitones down or INTEGER2

160

semitones up. Similar to <code class="literal">semitones</code>, but the

161

notes will be tranposed one by one, and the key will not change.

163

162

</p></dd></dl></div></dd><dt><span class="term"><code class="literal">enable_right_click = no</code></span></dt><dd><p>By default, Solfege will let the user right-click on buttons to hear

164

163

the music they represent without guessing. Set this variable to

165

164

<code class="literal">no</code> for lesson files where it does not make sense, for

187

186

<code class="literal">singinterval</code>.</p></dd><dt><span class="term"><code class="varname"><a name="lf-intervals"></a>intervals</code></span></dt><dd><p>This variable tell which intervals should be asked for in exercises

188

187

using the <code class="literal">harmonicinterval</code> module. 1 for minor second, 2 for major

189

188

second, 3 or minor third etc. Example that will practise thirds:</p><pre class="programlisting">intervals = [3, 4]</pre><p>Modules: <code class="literal">harmonicinterval</code>.</p></dd><dt><span class="term">

190

189

191

190

This variable defines the test for the exercise. In a test,

192

191

Solfege will ask all the questions in the lesson file a number

193

192

of times.

199

198

and <code class="literal">singinterval</code>.</p></dd><dt><span class="term">

200

199

201

200

<code class="varname"><a name="lf-test_requirement"></a>test_requirement</code></span></dt><dd><p>

202

201

203

202

This variable defines how large percentage of the questions

204

203

has to be answered correctly to pass the test. Example:

205

204

</p><pre class="programlisting">test_requirement = "90%"</pre><p>Modules: <code class="literal">harmonicinterval</code>,

230

229

<code class="literal">elembuilder</code>.</p></dd><dt><span class="term">

231

230

232

231

<code class="varname"><a name="lf-at_question_start"></a>at_question_start</code>

233

232

234

233

235

234

<code class="literal"></code></span></dt><dd><p>This variable changes what happens when the user clicks

236

235

<span class="guibutton">New</span>. By default, Solfege will play the music when

288

287

31:<span class="inlinemediaobject"><img src="../../graphics/rhythm-c8c16c16c16c16.png" alt="c8 c16 c16 c16 c16"></span> ,

289

288

32:<span class="inlinemediaobject"><img src="../../graphics/rhythm-c16c16c8c16c16.png" alt="c16 c16 c8 c16 c16"></span> ,

290

289

33:<span class="inlinemediaobject"><img src="../../graphics/rhythm-c16c16c16c16c8.png" alt="c16 c16 c16 c16 c8"></span> ,

291

34:<span class="inlinemediaobject"><img src="../../graphics/rhythm-c16c16c16c16c16c16.png" alt="c16 c16 c16 c16 c16 c16"></span> </p><p>Modules: <code class="literal">rhythm</code> and <code class="literal">rhythmtapping2</code></p></dd></dl></div><div class="sect3" lang="fr"><div class="titlepage"><div><div><h4 class="title"><a name="lf-obsolete-vars"></a>Variables that has been obsoleted</h4></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="literal">number_of_intervals = INTEGER</code></span></dt><dd><p>Made obsolete in Solfege 3.1.5. Solfege will find this number automatically now, so this variable is ignored.</p></dd></dl></div></div></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="Question-block"></a>Question block</h3></div></div></div><div class="variablelist"><p class="title"><b>Variables you can define in the question block</b></p><dl><dt><span class="term"><code class="literal"><a name="lf-name"></a>name</code></span></dt><dd><p>Questions written for the

290

34:<span class="inlinemediaobject"><img src="../../graphics/rhythm-c16c16c16c16c16c16.png" alt="c16 c16 c16 c16 c16 c16"></span> </p><p>Modules: <code class="literal">rhythm</code> and <code class="literal">rhythmtapping2</code></p></dd></dl></div><div class="sect3" title="Variables that has been obsoleted"><div class="titlepage"><div><div><h4 class="title"><a name="lf-obsolete-vars"></a>Variables that has been obsoleted</h4></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="literal">number_of_intervals = INTEGER</code></span></dt><dd><p>Made obsolete in Solfege 3.1.5. Solfege will find this number automatically now, so this variable is ignored.</p></dd></dl></div></div></div><div class="sect2" title="Question block"><div class="titlepage"><div><div><h3 class="title"><a name="Question-block"></a>Question block</h3></div></div></div><div class="variablelist" title="Variables you can define in the question block"><p class="title"><b>Variables you can define in the question block</b></p><dl><dt><span class="term"><code class="literal"><a name="lf-name"></a>name</code></span></dt><dd><p>Questions written for the

292

291

<a class="link" href="idbyname-module.html" title="The idbyname module">idbyname</a> or

293

292

<a class="link" href="elembuilder-module.html" title="The elembuilder module">elembuilder</a>

294

293

exercise modules need a name. A name is optional for

331

330

name matches the button clicked. If no match is found,

332

331

the program will select a question to play as if the

333

332

<code class="literal">set</code> variable was not used at all.</p><p>Modules: <code class="literal">idbyname</code> and

334

<code class="literal">chordvoicing</code>.</p></dd></dl></div></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="music-object"></a><code class="literal">music</code> objects</h3></div></div></div><p>Each question in your lesson files will define one or more

333

<code class="literal">chordvoicing</code>.</p></dd><dt><span class="term"><code class="literal"><a name="lf-key"></a>key</code></span></dt><dd><p>Needed to make some random transposition work properly

334

if the music is not in C major on A minor. Two examples:</p><pre class="programlisting">key="b \minor"

335

key="g \major"</pre></dd></dl></div></div><div class="sect2" title="music objects"><div class="titlepage"><div><div><h3 class="title"><a name="music-object"></a><code class="literal">music</code> objects</h3></div></div></div><p>Each question in your lesson files will define one or more

335

336

<code class="literal">music</code> objects.</p><div class="variablelist"><dl><dt><span class="term"><span class="bold"><a name="lfunc-music"></a><strong>music</strong></span>(<span class="emphasis"><em>musiccode</em></span>)</span></dt><dd><p>This is music entered completely following the music format FIXME spec. This means you

336

337

have to enter complete code with a <code class="literal">\staff</code> command. Example:</p><pre class="programlisting">variable = music("\staff\relative c' { c' d' }")</pre></dd><dt><span class="term"><span class="bold"><a name="lfunc-music3"></a><strong>music3</strong></span>(<span class="emphasis"><em>musiccode</em></span>)</span></dt><dd><p>The music object can be used for music that has 3 or more staffs.

337

338

It works the same way as <a class="xref" href="lesson-files.html#lfunc-music">music</a>,

378

379

a string with the name of the groove, and <code class="literal">mmacode</code> is

379

380

comple MMA code, except it could be missing the initial

380

381

"Groove" instruction. The groove from <code class="literal">groove</code>

381

will be prepended the string.</p></dd><dt><span class="term"><span class="bold"><a name="lfunc-cmdline"></a><strong>cmdline</strong></span>(<span class="emphasis"><em>shell code</em></span>)</span></dt><dd><p>Run an external program. Example:</p><pre class="programlisting">cmdline("./bin/csound-play-harmonic-interval.sh 220.000000 320.100000")</pre></dd></dl></div></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="functions"></a>Functions</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p class="fdef"><code class="literal">_(<em class="replaceable"><code>message</code></em>)</code></p><p>

382

will be prepended the string.</p></dd><dt><span class="term"><span class="bold"><a name="lfunc-cmdline"></a><strong>cmdline</strong></span>(<span class="emphasis"><em>shell code</em></span>)</span></dt><dd><p>Run an external program. Example:</p><pre class="programlisting">cmdline("./bin/csound-play-harmonic-interval.sh 220.000000 320.100000")</pre></dd></dl></div></div><div class="sect2" title="Functions"><div class="titlepage"><div><div><h3 class="title"><a name="functions"></a>Functions</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p class="fdef"><code class="literal">_(<em class="replaceable"><code>message</code></em>)</code></p><p>

382

383

Return the translation of <em class="replaceable"><code>message</code></em> if it exist.

383

Return the string unchanged if not.</p><pre class="programlisting">title = _("Bla bla title")</pre></li><li><p class="fdef"><code class="literal">include(<em class="replaceable"><code>filename</code></em>)</code></p><p>Read the file <em class="replaceable"><code>filename</code></em> into the lesson file

384

Return the string unchanged if not.</p><pre class="programlisting">title = _("Bla bla title")</pre></li><li class="listitem"><p class="fdef"><code class="literal">include(<em class="replaceable"><code>filename</code></em>)</code></p><p>Read the file <em class="replaceable"><code>filename</code></em> into the lesson file

384

385

and parse it as a part of the file.

385

386

The filename is relative to the location of the lesson file.</p><pre class="programlisting">include("singchord-1")</pre><p>The lesson header variables will be taken from the including lesson

386

387

file. Only if a variable is only defined in the included lesson file,

387

388

and not in the including lesson file, then the value will be taken from the

388

included file.</p></li><li><p class="fdef"><code class="literal">load(<em class="replaceable"><code>filename</code></em>)</code></p><p>Read the file <em class="replaceable"><code>filename</code></em> from disk and return

389

included file.</p></li><li class="listitem"><p class="fdef"><code class="literal">load(<em class="replaceable"><code>filename</code></em>)</code></p><p>Read the file <em class="replaceable"><code>filename</code></em> from disk and return

389

390

it as a string. The filename is relative to the location

390

of the lesson file.</p><pre class="programlisting">orc = load("share/sinus.orc")</pre></li></ul></div><div class="itemizedlist"><a name="labelfunctions"></a><p class="title"><b>Label functions</b></p><p>We call these functions <span class="emphasis"><em>label functions</em></span> because

391

of the lesson file.</p><pre class="programlisting">orc = load("share/sinus.orc")</pre></li></ul></div><div class="itemizedlist" title="Label functions"><a name="labelfunctions"></a><p class="title"><b>Label functions</b></p><p>We call these functions <span class="emphasis"><em>label functions</em></span> because

391

392

we use them to create the label for some questions in the program.

392

You should only use these functions where they are documented to work.</p><ul type="disc"><li><p class="fdef"><a name="lfunc-pangomarkup"></a><code class="literal">pangomarkup</code>(<em class="replaceable"><code>pangostring</code></em>)</p><p>Return a label that the program can put on a button. The label

393

You should only use these functions where they are documented to work.</p><ul class="itemizedlist" type="disc"><li class="listitem"><p class="fdef"><a name="lfunc-pangomarkup"></a><code class="literal">pangomarkup</code>(<em class="replaceable"><code>pangostring</code></em>)</p><p>Return a label that the program can put on a button. The label

393

394

is created using GTK pangomarkup.

394

395

395

396

Google for "pango markup"</a> to get the markup explained.

396

397

Notice that you have to use triple qoutes around the string.</p><pre class="programlisting">

397

pangomarkup("""<span size="xx-large">V</span>""")</pre></li><li><p class="fdef"><a name="lfunc-progressionlabel"></a><code class="literal">progressionlabel(<em class="replaceable"><code>str</code></em>)</code></p><p class="remark"><i><span class="remark">This function has existed in Solfege for a while, but it has

398

pangomarkup("""<span size="xx-large">V</span>""")</pre></li><li class="listitem"><p class="fdef"><a name="lfunc-progressionlabel"></a><code class="literal">progressionlabel(<em class="replaceable"><code>str</code></em>)</code></p><p class="remark"><i><span class="remark">This function has existed in Solfege for a while, but it has

398

399

not been documented until now. Should we find a shorter function name?

399

400

An alias can be added so that the old long function name still works.

400

401

</span></i></p><p>Return a label. <em class="replaceable"><code>str</code></em> is interpreted like

401

this:</p><div class="itemizedlist"><ul type="circle"><li><p>Each letter outside of a parentheses is displayed with

402

a large serif font.</p></li><li><p>The text

402

this:</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Each letter outside of a parentheses is displayed with

403

a large serif font.</p></li><li class="listitem"><p>The text

403

404

inside parentheses is displayed as a superscript: smaller letters above

404

the baseline.</p></li><li><p>If the text inside the parentheses is divided by a comma,

405

the baseline.</p></li><li class="listitem"><p>If the text inside the parentheses is divided by a comma,

405

406

the text before the comma is superscript and after the comma is subscript.

406

407

</p></li></ul></div><pre class="programlisting">progressionlabel("I-IV-(6,4)V(5,3)-I")

407

408

progressionlabel("I-VI-V(6)-I")"

408

409

progressionlabel("C(maj7)")

409

</pre><div class="informalfigure"><a name="lfunc-progressionlabel-example1"></a><div class="screenshot"><div class="mediaobject"><img src="figures/progressionlabel-example-1.png"></div></div></div></li><li><p class="fdef"><a name="lfunc-rnc"></a><code class="literal">rnc(<em class="replaceable"><code>str</code></em>)</code></p><p>Display a sequence of roman numeral chords. The chords are separated

410

</pre><div class="informalfigure"><a name="lfunc-progressionlabel-example1"></a><div class="screenshot"><div class="mediaobject"><img src="../C/figures/progressionlabel-example-1.png"></div></div></div></li><li class="listitem"><p class="fdef"><a name="lfunc-rnc"></a><code class="literal">rnc(<em class="replaceable"><code>str</code></em>)</code></p><p>Display a sequence of roman numeral chords. The chords are separated

410

411

by whitespace and an optional hyphen. The exact implementation of this is

411

412

still open for discussion. The current developent version of Solfege will

412

413

divide each chord in 3 parts and give them different font sizes, and also try

413

414

to make the chord compact, so that it should not take too much space on

414

screen.</p><div class="itemizedlist"><ul type="circle"><li><p>The first part of the chord is the roman numberal, including

415

screen.</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>The first part of the chord is the roman numberal, including

415

416

an optional <code class="literal">b</code> or <code class="literal">♭</code>

416

417

(unicode character <code class="literal">U+266D MUSIC FLAT SIGN</code>).

417

</p></li><li><p>The second part is the letters (if any) between the first

418

and the third part.</p></li><li><p>The third part is from the first digit and the rest of the

419

chord.</p></li></ul></div><pre class="programlisting">rnc("Imaj7-IIm7-V9-Imaj7")</pre><div class="informalfigure"><a name="fig-rnc"></a><div class="screenshot"><div class="mediaobject"><img src="figures/rnc-example.png"></div></div></div><p>Spaces are not allowed in the chord name.</p><p>New in version 3.11.0.</p></li><li><p class="fdef"><a name="lfunc-chordname"></a><code class="literal">chordname(<em class="replaceable"><code>str</code></em>)</code></p><p>Display a sequence of chords. The chords are separated by whitespace.

418

</p></li><li class="listitem"><p>The second part is the letters (if any) between the first

419

and the third part.</p></li><li class="listitem"><p>The third part is from the first digit and the rest of the

420

chord.</p></li></ul></div><pre class="programlisting">rnc("Imaj7-IIm7-V9-Imaj7")</pre><div class="informalfigure"><a name="fig-rnc"></a><div class="screenshot"><div class="mediaobject"><img src="../C/figures/rnc-example.png"></div></div></div><p>Spaces are not allowed in the chord name.</p><p>New in version 3.11.0.</p></li><li class="listitem"><p class="fdef"><a name="lfunc-chordname"></a><code class="literal">chordname(<em class="replaceable"><code>str</code></em>)</code></p><p>Display a sequence of chords. The chords are separated by whitespace.

420

421

Each chord consist of up to four parts, and part two to four are optional:

421

422

</p><pre class="programlisting">[notename][txt1][:txt2][/bass]</pre><p><code class="literal">notename</code> and <code class="literal">bass</code> music be

422

423

a notename in the format understood by the music parser. You can read

423

more about this in <a class="xref" href="mpd-module.html" title="The mpd module">la section intitulée « The <code class="literal">mpd</code> module »</a>. Example:</p><pre class="programlisting">g:11b9 cm/g ges:Δ besm:7/f</pre><div class="informalfigure"><a name="fig-chordname"></a><div class="screenshot"><div class="mediaobject"><img src="figures/chordname-example.png"></div></div></div><p>New in version 3.11.1.</p></li></ul></div></div><div class="sect2" lang="fr"><div class="titlepage"><div><div><h3 class="title"><a name="lf-operators"></a>Operators</h3></div></div></div><p>Operators can only be used on strings. <code class="literal">+</code> is used for

424

more about this in <a class="xref" href="mpd-module.html" title="The mpd module">la section intitulée « The <code class="literal">mpd</code> module »</a>. Example:</p><pre class="programlisting">g:11b9 cm/g ges:Δ besm:7/f</pre><div class="informalfigure"><a name="fig-chordname"></a><div class="screenshot"><div class="mediaobject"><img src="../C/figures/chordname-example.png"></div></div></div><p>New in version 3.11.1.</p></li></ul></div></div><div class="sect2" title="Operators"><div class="titlepage"><div><div><h3 class="title"><a name="lf-operators"></a>Operators</h3></div></div></div><p>Operators can only be used on strings. <code class="literal">+</code> is used for

424

425

joining strings, and <code class="literal">%</code> is similar to what you find in

425

426

python, but it is very limited. It only know about <code class="literal">%s</code>. One

426

example:</p><pre class="programlisting">"\staff\relative c'{%s}" % "c d e"</pre><p>evaluates to</p><pre class="programlisting">\staff\relative c'{c d e}</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extending-solfege.html">Précédent</a> </td><td width="20%" align="center"><a accesskey="u" href="extending-solfege.html">Niveau supérieur</a></td><td width="40%" align="right"> <a accesskey="n" href="chord-module.html">Suivant</a></td></tr><tr><td width="40%" align="left" valign="top">Chapitre 4. Extending GNU Solfege </td><td width="20%" align="center"><a accesskey="h" href="index.html">Sommaire</a></td><td width="40%" align="right" valign="top"> The <code class="literal">chord</code> module</td></tr></table></div></body></html>

427

example:</p><pre class="programlisting">"\staff\relative c'{%s}" % "c d e"</pre><p>evaluates to</p><pre class="programlisting">\staff\relative c'{c d e}</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extending-solfege.html">Précédent</a> </td><td width="20%" align="center"><a accesskey="u" href="extending-solfege.html">Niveau supérieur</a></td><td width="40%" align="right"> <a accesskey="n" href="chordvoicing-module.html">Suivant</a></td></tr><tr><td width="40%" align="left" valign="top">Chapitre 4. Extending GNU Solfege </td><td width="20%" align="center"><a accesskey="h" href="index.html">Sommaire</a></td><td width="40%" align="right" valign="top"> The <code class="literal">chordvoicing</code> module</td></tr></table></div></body></html>

Older »