pulled fixes from release into trunk

1 files changed, 116 insertions, 49 deletions

diff --git a/muse2/README b/muse2/README
index 1770950b..f9287458 100644
--- a/muse2/README
+++ b/muse2/README
@@ -17,99 +17,145 @@ details.
 `-----------------------------------------------------------------'
 
   =============================
-      Requirements
+      Requirements:
   =============================
       
 
       - CMake >= 2.4 
-        http:/www.cmake.org/HTML/Download.html
+          http:/www.cmake.org/HTML/Download.html
 
       - QT: Qt >= 4.2.0 
-        ftp://ftp.trolltech.com/qt/source
-        MusE does _not_ compile with older versions
+          http://qt.nokia.com/products/
+          MusE does _not_ compile with older versions
 
       - gcc >= 4.x.x
 
       - libsndfile >= 1.0.1
-        http://www.mega-nerd.com/libsndfile/
+          http://www.mega-nerd.com/libsndfile/
 
       - libsamplerate
+          http://www.mega-nerd.com/SRC/
 
       - JACK >= 0.103
           http://jackit.sourceforge.net/download/
 
+      - libuuid
+         e2fsprogs package http://e2fsprogs.sourceforge.net/
+         Some distros may include it in another package, offering a choice.
+
       Optional:
 
       - fluidsynth >= 1.0.3 (formerly known as iiwusynth) from
         http://savannah.nongnu.org/download/fluid
 
-      - OSC (Open Sound Control) 
-      - DSSI (Disposable Soft Synth Interface) with support for DSSI vst plugins.
-        (Both recommended - DSSI alone will have no DSSI GUIs. OSC alone does nothing, for now.)
+      - liblo           Lightweight OSC (Open Sound Control)    http://liblo.sourceforge.net/
+      - DSSI            Disposable Soft Synth Interface.        http://dssi.sourceforge.net/
+          (Both recommended - DSSI alone will have no native GUIs, OSC alone does nothing, for now.)
+
+      - dssi-vst        Support for DSSI vst plugins            http://www.breakfastquay.com/dssi-vst/
 
-      - LASH Audio Session Handler
+      - LASH            Audio Session Handler                   http://lash.nongnu.org/
+         Recently LADISH has been emulating it instead.         http://ladish.org/
       
       - ConTeXt (for building documentation, by default the build
                script tries to build documentation, can be
                disabled by setting ENABLE_DOCUMENTATION to OFF)
 
   =============================
-      Compiling:
+      Building MusE:
   =============================
 
       - Download source from http://lmuse.sourceforge.net/
 
-      - Command line to unpack source:
-            tar xvofz muse-x.y.z.tar.gz 
-         where x.y.z is the version number.
-        Or just use a graphical de-compressor to unpack it somewhere.  
+      - Unpack the source somewhere.  
+
+        You may also try the various MusE development SVN branches for 
+         up-to-the-minute features and fixes, but they may be less stable. 
 
       - To compile MusE, run the following commands from the 
          top level directory where the source code was unpacked
-         (the directory where THIS README FILE is): 
+         (the directory where THIS README FILE is found): 
        
 	******************************************************
         *                      Notice:                       *
-        * a quicker way is to run the ./compile_muse.sh      *
+        * A quick way is to run the ./compile_muse.sh        *
         * script in the same dir, it should perform the same *
         * steps for a basic setup without asking any         *
-        * questions. If it fails you may be better of using  *
+        * questions. If it fails you may be better off using *
         * the instructions below.                            *
         ******************************************************
  
-          # Create build directory. Choose any name like 'build'.
-              mkdir build                                      
-          # Enter build directory.
-              cd build                                         
-          
-          # Create make system in the build directory.
-          # Optional <Prefix> is the location to install MusE, default /usr/local.
-          # Build type can be blank (to reset a previous cached type to 'empty'), 
-          #  debug, release, RelWithDebInfo and MinSizeRel.
-          # If no CMAKE_BUILD_TYPE is given at all, cmake uses either the previous 
-          #  cached value, or else 'empty' (plain unoptimized).
-          # ('Release' type is recommended, otherwise it builds a plain unoptimized program.)
-              cmake -DCMAKE_BUILD_TYPE=release [-DCMAKE_INSTALL_PREFIX=<prefix>] ../
-          
-          # Compile muse
-              make                                             
-            
-      - Install MusE:
-              Run "make install"  (as root user)
+        The build directory:
+        --------------------
+          Building in a subdirectory is recommended to keep the build directory separate from the source tree. 
+          So create a new subdirectory with a useful name like "build" or "debug" or "release": 
+            mkdir build
+          Change directory (cd) to the new directory: 
+            cd build  
+
+        Configuration:
+        --------------
+          There are a few different ways to configure (notice the two dots):
+
+          Type "cmake -i .." to run in step-by-step 'Wizard' mode. 
+
+          Or type "cmake -L .." to see options, then compose "cmake <options>" yourself. 
+          Some <options> are:
+
+            -DCMAKE_BUILD_TYPE=<type>
+               <type> can be blank (to reset a previous cached type to 'empty'), 
+                debug, release, RelWithDebInfo and MinSizeRel.
+               Release is recommended, to get optimizations.
+               If no CMAKE_BUILD_TYPE is given at all, cmake uses either the previous 
+                cached value, or else 'empty' (plain or default system optimizations).
+
+            -DCMAKE_INSTALL_PREFIX=<prefix>
+               The installation <prefix> where the program is installed.
+               The default is to install in /usr/local.
+
+          Or type "ccmake .." (if you have it - text-mode GUI). It may be blank so hit  
+           'C' to first-time configure. Fiddle with yer options if ye so desire, then hit 
+           'C' to configure then 'G' to generate and exit, or 'Q' to quit without 
+           generating. 
+
+          Or there is also a desktop GUI for cmake called cmake-gui.
+
+        Compiling:
+        ----------  
+          After configuration, while still in the build directory,type:
+            make 
+
+        Installing:
+        ----------  
+          After compiling, type:
+            make install (as root) 
+           or
+            sudo make install
 
   =============================
-      running MusE
+      Running MusE:
   =============================
 
-      MusE is a realtime program which requires special rights to
-      work poperly.
       Recommended setup:
+      ------------------
+        MusE is a realtime program which requires special rights to work properly.
 
-      - check if you are running a sufficiently new linux kernel > 2.6.x
+      - Check if you are running a sufficiently new linux kernel > 2.6.x
+        A modern, standard destop kernel might suit your needs.
+        However, for the best performance a so-called 'low latency' or 'realtime' 
+         kernel may be required. Check your distro's packages for availability. 
 
       - create an "audio" group if it does not already exists
         and put yourself into this group
 
+      - For realtime priority, you may want to ensure either the file:
+           /etc/security/limits.conf
+         or
+           /etc/security/limits.d/audio.conf
+         contains:
+           @audio   -  rtprio     95
+           @audio   -  memlock    unlimited
+
       - make sure you can acces the realtime clock (RTC)
             chmod 660 /dev/rtc
             chgrp audio /dev/rtc
@@ -119,18 +165,39 @@ details.
             inspect with:
             cat /proc/sys/dev/rtc/max-user-freq
 
-      - for MusE to gain RT priviledges load the "realtime-lsm"
-        modul; the modul should be configured to give all "audio"
-        group members realtime priviledges
-
       - some distros do not load the alsa sequencer module by default.
         if necessary, load the alsa sequencer module with:
             /sbin/modprobe snd-seq
 
-      - start qjackctl
-            - start JACK with qjackctl
-
-      - start MusE
+      - Start jack, typically by using the qjackctl application.
+        MusE can also be run without Jack. MusE will use a dummy audio 
+         driver if Jack is not detected, or the -a option is given.
+
+
+      Running:
+      ------------------
+        start MusE by typing:
+            muse2 <options>
+
+          Some <options> are:
+            -h       help
+            -v       print version
+            -d       debug mode: no threads, no RT
+            -D       debug mode: enable some debug messages
+                                  specify twice for lots of debug messages
+                                  this may slow down MusE massively!
+            -m       debug mode: trace midi Input
+            -M       debug mode: trace midi Output
+            -s       debug mode: trace sync
+            -a       no audio
+            -P  n    set audio driver real time priority to n
+                      (Dummy only, default 40. Else fixed by Jack.)
+            -Y  n    force midi real time priority to n (default: audio driver prio +2)
+            -p       don't load LADSPA plugins
+            -I       don't load DSSI plugins
+            -L       don't use LASH
+            -l  xx   force locale to the given language/country code
+                      (xx = de,en,es,fr,pl,ru,sv_SE)
 
       (JACK and all its clients (qjackctl & MusE) must run with the
       same user id)
@@ -140,7 +207,7 @@ details.
       known bugs
   =============================
 
-      - many
+      - not so many: only some usability quirks we're working on currently
 
 ====================================================================
 Let us know whether MusE works for you !!!