\input texinfo
@setfilename README.info
@include topdocs/defs.texi
@settitle README

@contents 

@chapter GNU Solfege @value{SOLFEGEVERSION}

Solfege is a free eartraining program written in python using gtk+
and GNOME libs. Using GNOME is optional, but the user interface is
nicer using GNOME. Solfege is expected to work on any OS where python,
gtk+ and pygtk are ported.

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

MS Windows users can download the installer program
@file{solfege-win32-@value{SOLFEGEVERSION}.exe} that contains everything
they need. The rest of us should check that the following
is installed:

@itemize @bullet
@item Python >= 2.1
@item Gtk+ 1.2, preferable >= 1.2.8
@item Gnome >= 1.0.50 (optional, but recommended)
@item PyGTK, Python bindings for Gtk
@item PyGNOME >= 1.0.50 - Python bindings for GNOME (optional but recommended)
@item Midi working on /dev/music or /dev/sequencer (for example using
OSS or ALSA with OSS emulation). Or at least possible
to play midi files on some external program. On MS Windows,
any soundcard that has the proper drivers installed should
be supported.
@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).

Beside this, the version number has no other magical meaning, than to
tell that one release is older or newer than another release.

@section Internationalisation
You get translated messages the same ways as with most GNU programs,
by setting environment variables. For example, one of these will give
you norwegian translations:

@example
  export LC_MESSAGES=no_NO
  export LANG=norwegian
@end example

@section Sound issues

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

@subsection @option{--no-sound} command line option

If you plan to play sounds using
an external midiplayer, or if you get other error messages that you
think might be caused by your sound setup or Solfeges sound code, then
you should start the program with the @option{--no-sound} command line
option the first time you run the program, and then configure sound from
the preferences window.

@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/.solfegerc@value{SOLFEGESHORTVERSION}.
You can also try to delete the $HOME/.solfege@value{SOLFEGESHORTVERSION}
directory that contains the statistics. (You might want to backup the
files in case they are not what is causing the your problems, and
you want to keep your statistics!)

If you find a way to reproduce an error that is fixed by deleting 
$HOME/.solfegerc@value{SOLFEGESHORTVERSION} or
$HOME/.solfege@value{SOLFEGESHORTVERSION}, you should email 
@email{solfege-devel@@lists.sourceforge.net}.


@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, 2002  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}

