• View
• Edit
• History
• Print

How it can be done

This page does not desribe the current implementation. It was a draft used for discussion. Parts of it has been implemented.

How can this be done - technical point of view

File types

There are a few data types:

• Already existing types:
  • Lessonfiles (all terms can be translated, from whithin the file and by solfege).
  • Theory pages (html, translatable, technically the same as help files.)
  • Help pages (html, translatable)
  • images (png, translatable)
  • .midi, .wav... files that can be shared between items, for example, they can be used both in a theory page and in a help page.
• New types:
  • Leveldirectory. This is a directory that groups all files for 1 topic. It can contain lessonfiles, help pages, theory pages, png-midi-wav...

A topic directory

A topic directory is a directory that is in one of the configured lessonfiles directories. What is new to lesson files is that they also can define levels that point to exercises like harmonicinterval and rhythm.

It contains theory pages, exercises, help on exercises, tests, png, wav, midi...

Comment : The first idea was to use a index.html file in a leveldirectory that would configure all kinds of stuff. Until now, it's possible to work without this kind of index - which is the easiest and most flexible. All configuraton stuff goes into the lessonfiles.

Each lessonfile represents a level. So solfege needs to be able to find out in which order the lessonfiles should be sorted. I - tom e - propose we simply use prefixes in the filenames: The teacher uses filenames that begin with 10 , 20 , 30... and this makes it easy to add, insert and delete lessonfiles (=levels). TomCato warned somewhere else in the wiki that solfege needs to be able to retain user scores of levels, even if the levels change number/name/order...

At runtime, all lessonfiles in the directory will be sorted by filename and will be given a level-number.

Each lessonfile can set requirements to make the NEXT level accessible to the user. This is done in 4 parameters: quota = a, b, c, d.

• The number of questions that must be answered correctly: a
• If the a correct answers are not all in a row, the maximum number of errors that is allowed in that row: b (of course, the last answer in that row must be correct; it would be really strange if the program rewarded the user directly after a wrong answer.) If this quota is met, the user will be asked if he wants to take a test.

The test will be configured in the lessonfile, because a test is simply the exercise with scores that will be kept. The configuration of the test is done by two parameters:

• How many questions will be asked: c
• How many questions that may be answered WRONG to pass the test: d

Of course if c=0 or d > c, no test will be done and the user gets acces to the next level as soon as parameters a and b are OK.

For each of the levels, the teacher can choose whether the configuration tab should be on or off. I guess in most cases, the teacher will disable the config tab, and use a special level to enable the config tab. We could make a 'level 0' or something like that.

For each level, the help tab will be available. Normally the help-on-current-exercise will be displayed there. However, the lessonfile can point to a specific helpfile. The specific helpfile will be searched in the same directory as its lessonfile, and if not found there, in the solfege data directories. If not found there, solfege will fall back to the default page. Of course, translations in the users LANG go before English.

A similar system will be used for the theory files. Very likely, the teacher will want the content of the theory file to advance along with the levels. So there should be an easy way to tell solfege at which levels the theory text should change.

A lessonfile can point to a theory page. (search and translation works like the help pages - see higher.) This theory page will be used for that level and all higher levels, until another theory page is specified in another level.

Changes to lesson file contents

Files to add non-lessonfile exercises to topics

Exercises like harmonicinterval and rhythm don't use lesson files. But we need to have a file in the topic directory that configures the exercises and define the test. The syntax is similar to lesson files. The names of the blocks and variables are only suggestions.

  
header {
 name = "Minor and major third"
 url= solfege:practise/idbyname?intervals=[2, 3]
}

test {
  TEST DEFINITION AS IN LESSON FILES
}

Defining the test, adding the test block to lesson files

We define the test the user has to pass to get to the next level in the test block on the lesson file.

 
test {
   start_msg = "This message will be shown to the user before the test starts."
   # all questions will be repeated 3times.
   test_repetitions = 3
   # 80% of the questions must be answered correctly to pass the test
   test_requirement = 80%
   # for each question, it has to be answered correctly at least 66%
   test_questions_requirement = 66%  
}

LessonFileManager

We will have to extend LessonFileManager to parse leveldirectories too.

The topic index

At startup, solfege scans for available leveldirectories and lessonfiles and builds an indexfile at runtime.

Solfege shows the welcome page, The exercise index is just another html page with links. It should have a link back to the welcome page. (it doesn't seem so elegant to replace the welcome page completely, besides: the welcome page links to all kinds of info pages)

Solfege should have at least one content index to show how it works, and have a help page about it. Could content indexes be nested? this could cause confusing in navigation.

Building the topic index

For most teachers and pupils, several 'exercise indexes' will be in use. For example, one index for each class or period. So solfege should have a way to select the right index for each pupil. A pupil could be identified by her linux user name, but that won't work on windows 98, will it :-)

Single working lessonfile that were found should get a link too, somewhere!

If all exercises remain available via separate lessonfiles, a 'File | Open lessonfile' dialog box becomes inevitable.

Graphical interface

Tabs These actions are shown with tabs:

• left tab is theory-text,
• next tab is the 'help on current exercise' page
• next tab is practice,
• right tab is test.
• extra tab is 'config' (don't show if the teacher doesn't want it. If the config tab is shown, then it should be different from the one we have now. At least the "Select lessonfile" button should be removed.)

Footer

• link left: link to an easier item in this topic (if there is one)
• number, title and description of the item.
• link up: link to content index
• link right: link to a more difficult item in this topic (if there is one)

Theory tab Are already possible, one working example is theory-intervals.html

• put in tab
• vertical scrollbar in the tab when needed

Exercise HELP tab

• put in tab

Practice tab Are already used in solfege today, both for exercises that use lesson files and exercises that don't use them.

Test tab A test is just another pre-configured exercise. The only difference is that the result are stored into another table/database/record/whatever.

• Show clearly that solfege is taking a test.
• Data needs to be stored slightly different.
• Navigating away form the test finishes the test.
• Decide what to do with the results when the test is not done to the end.

Config tab already in place

• Can be hidden

The help pages and navigation

• The 'help on current exercise' page will be viewed in their own tabs
• The help on the preferences can be opened for a 'help' button in the preferences window (but which window will show the help ?? Good question. Maybe a new window? But then what if the help text in the preferences window has a link to a exercise? solfege:practise/harmonicinterval for example.) what about the balloon-help idea: when you click on the questionmark-button on the right top of the window, you'll see a description for each item you click on. It's not in the hig iirc. Is it KDE stuff?
• The rest of the existing pages are accessible via the welcome page ("welcome" or "home" or another name?) :
  • How to use solfege (UI)
  • solfege on the internet (Online resources)
  • report an error (Bugs)
  • Copyright notices : GPL, FDL
  • Extending and translating Solfege. This links to:
    • Translating Solfege
    • indexes and Help files
    • Music format
    • Lesson files
    • Chord names used in GNU Solfege

Since all exercise, theory, test, exercise-help and program-help pages have their place, the navigation buttons have become redundant.

About the toolbar: Why not reimplement the icons into the default exercise index?

<< Word Definitions | NewExerciseSetup | Topic index >>