LMUSe v0.7b
11/22/98
================
Changes from v0:
================
11/22/98: Better (hopefully) avoidance of arithmetic exceptions.
11/19/98: The irritatingly poor precision of the spread-parameter
               sliders is 'fixed' by adding an editable text field
11/03/98: Bug fix in the play screen 'jump to time'
10/16/98: Added multiple maps and a new symbol, 'm', to the
               L-system alphabet to move between interpreting maps.
10/10/98: Changed the 'Make' function so that it now doesn't
               load a rule file, and added a 'Load Rules' button.
               Setting of the RNG seed fixed. Small bug fixes.
10/03/98: Option to change maximum production length within
               program. Option to turn off sound.
09/28/98: Option to disable saving of the map parameters
               as a text field in saved MIDI files. (This text
               field is rather long for a track title and may
               have been giving problems to certain sequencers).
09/22/98: Overdue implementation of loading & saving of
               map, scale, and other parameters to/from a map file.
03/19/98: Various small changes and fixes. (nothing major)
03/12/98: Extended the range of the `spread' parameters to
               negative values to `invert' maps.
03/11/98: new symbol '*(x)' to write to MIDI channel x. Transpose
               stack, T(x)...T, bug fix. (wasn't transposing *down*!)
03/09/98: Added some graphical buttons. small bug fixes.
03/03/98: bug fixes and cosmetic changes
03/01/98: new symbols for push (`\') and pop (`/') time without
               otherwise changing the current state. This makes
               creating parallel (in time) musical lines more
               flexible.
02/28/98: Fixed a major flaw that was not popping the angle from
               the state stack properly.
02/27/98: Fixed a bug that was crashing on state stack underflow.
02/26/98: Added three independent stacks. Pitch transpostion stack,
               velocity multiplier and duration multiplier stacks.
02/25/98: Added "v(x)" to the symbol alphabet. v(x) multiplies
               note velocities.
02/23/98: Changes to mutation routines. More small cosmetic changes.
02/21/98: Added: DOS shell command. Option to load new file when
               returning from 'Edit'. Save rule file command.
02/19/98: Made it possible to combine two-sided context-sensitivity with a
               stochastic condition in a single rule (though I  haven't quite 
               figured out how to use this for any practical purpose).
02/17/98: Added "spread" parameters to the map dialog to amplify the
               interpretation of pitch, durations and volumes.
               Replaced the various *.hlp files with one "help.dat"
02/15/98: Bug fixes and cosmetic changes

========
PURPOSE:
========
LMUSe is intended to interpret Lindenmayer L-systems into MIDI files,
or MIDI generated sound. L-systems are "string rewriting rules" which
are applied to a starting string, and reapplied a number of times. The
resulting string can then be interpreted as music. (Usually, though,
the string is interpreted as computer drawing commands.)
LMUSe takes state parameters (from 3-dimensional turtle movement and
direction) and maps them to pitch, note duration, and volume. A state
stack is used to build parallel/polyphonic lines. 

So far as I know, LMUSe accepts any "*.ls" file that works with Laurens
Lapre's LParser program since virtually the same symbol alphabet is used.
Other L-system production program files can be used as well, though usually
they require some modifications. I recommend anyone with an interest in
L-systems to download a copy of Lparser from http://www.xs4all.nl/~ljlapre/

===================
Equipment required:
===================
386/486/Pentium, MSDOS, 640x480 256 color graphics, mouse,
midi capable sound card or midi interface, speakers (or headphones).

==============================
LICENSE, STATUS, DISTRIBUTION:
==============================
LMUSe is a free program distributed without any warranties, and
no restrictions on its free redistribution as long as the program
and attendant files are intact without modification.
To redistribute with modification, please request permission from
the author: David Sharp, dsharp@interport.net

===========
INSTALLING:
===========
LMUSe.ZIP should all be unzipped into the same directory.  It is
probably best (easier in the long run) to create a directory named
LMUSe. Copy the lmuse.zip file to the lmuse directory and change to
to the lmuse directory. Unzip the lmuse.zip file in the lmuse
directory. If using PKUNZIP, use the -d option:
        pkunzip -d lmuse.zip

To run LMUSe under plain DOS (i.e. not in a Windows DOS box), the file
CWSDPMI.EXE needs to be in the LMUSe directory or in your PATH.

================
GETTING STARTED:
================
After starting the program (run LMUS.EXE),
click on 'Make and Interpret'. A file selector dialog opens and displays
files with 'L', 'LS', or 'LM' extensions. Just for an example, look in
the EXAMPLES directory and select the file 'AIRHORSE.LS', and click on
'OK'. LMUSe reads the 'LS' file and shows you the recursion level,
basic angle, axiom, and transformation rules that it just loaded from
AIRHORSE.LS. Here you have the opportunity to change the recursion level
or basic angle. For now, just click on 'OK'. LMUSe then makes the
production string from the axiom, using the transformation rules.
The butterfly mouse cursor shows you that LMUSe is making the production
string. The cursor switches to a flying saucer when LMUSe starts the
'interpreting' stage. When LMUSe is ready to begin interpreting the
production as MIDI messages, it presents you with the 'Map' dialog.
Here you choose which state parameters should be mapped to note pitches,
note durations, and note volumes. You can also use the slider bars
to determine how strong the influence of the state parameters is.
After clicking on OK, you watch LMUSe draw a picture from the rules.
This is really just a 'progress indicator' as a list of MIDI messages is
prepared. When done, LMUSe switches to the 'Play' screen and plays the
newly composed piece.

======
FILES:
======
LMUS.EXE
       - the main executable.
LMUS.DAT
       - an attendant data file
HELP.DAT
       - LMUSe help file. Not meant to be read outside
         of the LMUSe program.
CWSDPMI.EXE
       - DPMI for running under DOS
LMUSE.TXT
       - The LMUSe help files concatenated into one
         document
examples/*.L, *.LS, *.LM
       - example L-system transformation rules
examples/*.INI,*.MAP
       - example map files.
src/*.c, *.h, makefile
       - the source code and makefile for compiling.
html/*.htm, *.gif, *.mid
       - documentation in HTML and examples.

A sparse tutorial is in the file `tut.txt'.

===========
SOURCE CODE
===========
To compile LMUSe `straight out of the box' you will need the C
compiler DJGPP, as well as the Allegro v3.0 game library, both
freely available. You are free to use the source code however
you want except for claiming that it was written by anyone other
than me or those credited.

=========================
QUESTIONS, PROBLEMS, etc:
=========================
Please send questions, complaints, requests, etc, to:
        dsharp@interport.net
