\input texinfo
@setfilename README.info
@settitle README

@contents 

@chapter GNU Solfege

Solfege is a free eartraining program written in python using the gtk+
and GNOME libs. The first versions of the program required GNOME, but
now it is possible to compile the program on operating systems where
only python, gtk+ and pyGTK are ported to. (But a few exercises will not
work without GNOME.)

Check out the latest news and precompiled binaries at 
@uref{http://www.solfege.org}. Get the source code for the stable releases
at @uref{ftp://ftp.gnu.org/gnu/solfege} and bleeding edge at
@uref{ftp://alpha.gnu.org/gnu/solfege}.

Eartraining is a big subject with many connections to music theory and
performance of music, so I won't even try to make "a complete
computerbased eartraining course". To use this software, you need some
basic knowledge about music theory. 

As of 18 June 2000, Solfege is an official part of the GNU project.
Visit @uref{http://www.gnu.org} for more info.

@section You need this to run Solfege

@itemize @bullet
@item Python >= 1.5.2 (1.5.2, 2.0.1, 2.1.1 and 2.2a1 has been tested)
@item Gtk+ 1.2, preferable >= 1.2.8
@item Gnome >= 1.0.50
@item PyGNOME >= 1.0.50 - Python bindings for GNOME
@item Midi working on /dev/music or /dev/sequencer. Or at least possible
to play midi files on some external program.
@end itemize

Check the @file{INSTALL} file for build time requirements.
@section Versioning

Solfege uses a versioning scheme similar to the Linux kernel.
In a version "x.y.z", an even (0, 2, 4, 6, 8) second number 'y'
denotes a stable version. So releases called 1.0, 1.2.2, 2.0.0 and
similar should work as documented, while a release versioned 1.1.x
is a test release that is expected to cause some troubles (that should
be reported to solfege-devel@@lists.sourceforge.net)

@section Internationalisation
For translated messages:
@example
  export LC_MESSAGES=de_DE
@end example

At the moment only incomplete norwegian, german, french and italian
translations exist. Don't be smart and set the @env{LANG} variable,
this will cause gettext to believe you want to change @env{LC_NUMERIC}
too, and you definately don't want this. The combination of python,
PyGTK and @env{LC_NUMERIC} set to something else than 'C' do funny things
to how the python interpreter do math and integer->string conversion.

@section Sound issues

You configure how Solfege should play sounds from the preferences
window available from the File menu.

@subsection Missing @file{/dev/music}

If you have a recent linux kernel (at least late 2.2.x and newer,
someone please confirm when /dev/music was added...) but @file{/dev/music}
is missing, you can probably create the device file yourself with
MAKEDEV or @command{mknod /dev/music u 14 8} as root.

@section If it just won't work

One useful tips if you get strange errors is to delete the file
$HOME/.gnome/solfege1.1 ($HOME/solfegerc1.1 if you don't run GNOME)
You can also try to delete the $HOME/.solfege1.1 directory that
contains the statistics. (You might want to backup the files if they
are not what is causing the your problems!)


@subsection Unset LC_NUMERIC
If you get an errormessage that ends something like this:

@example
    ValueError: computed value for NV_MAGICCONST deviates too much (computed 2,82843, expected 1)
@end example

you need to change the value of the environment variable LC_NUMERIC.
(This is a bug that is fixed in the latest PyGNOME bindings.)
You can run solfege like this:

@example
    LC_NUMERIC=C solfege
@end example

or set the variable in you ~/.bash_profile or ~/.bashrc file:

@example
  export LC_NUMERIC=C
@end example

If your shell is something else than bash, you probably know how
to do this.

@subsection It still won't work!

See the INSTALL file if you have problems building and installing
Solfege, and check the man page or run the program with the '---help'
command line option for a list of command line options.

The users guide is located in the online-docs/ directory from the
unpacked source, and also available from inside the program from
the 'Help' menu.

Report your problems to @email{solfege-devel@@lists.sourceforge.net}

@section History

The first versions of Solfege was written in the first quarter
of 1999 when I studied my 4th and last year at Malmö Academy of Music.
I was writing a "special subject" (what is the english term??) about
eartraining and used GNU Lilypond and LaTeX to typeset the paper.

I accidentally browsed the "help needed" page at the GNU web site when
I saw they needed someone to write an eartraining program for music
students.

In the beginning I was experimenting with
wxWindows, a cross platform C++ GUI toolkit, but luckily, at some
point I found the python bindings for gtk+ and have never looked back.

@section No CVS

Don't ask me to put Solfege under CVS, because I won't use my private
payed phone line to keep my working version of Solfege in sync with
a CVS server. If I ever get net access at home where I pay only a
monthly fee, this will of course change. 
But don't let this stop you from contributing code, just send me the
patches.

@section Copyright notice

Copyright (C) 2000, 2001  Tom Cato Amundsen

This if free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2.

This is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License with
your Debian GNU/Linux system, in /usr/doc/copyright/GPL, with the
solfege source package as the file COPYING and available in the online
help system..  If not, write to the Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Tom Cato Amundsen
@email{tca@@gnu.org}

