AMPLE application version 0.30, June 2002
=========================================

Original conception of AMPLE by Hybrid Technology Ltd

Implemented under RISC OS by Robin Terry

Copyright notice and disclaimer
-------------------------------

The files contained in this distribution are (C) Robin Terry 2000. They may
be distributed free, as long as:

a. The files are not altered in any way
b. All files, including this copyright notice, are supplied

AMPLE is distributed "as is"; I cannot be held responsible for any bugs,
problems or losses incurred while using this program, even if I have been
advised of the possibility of such loss.

This program may not be sold, even as part of a collection of
software, without the express permission of the author.

1. Introduction
---------------

AMPLE is a programming language designed to allow the playback of music
compositions. The music is created as an AMPLE program text file and is
dragged into the AMPLE application, which then compiles it. If the program is
syntactically correct, it is then possible to execute the program, which then
performs the composition.

2. To start AMPLE
-----------------

Double click on the !AMPLE application icon on a Filer window to start the
program. It installs its icon on the icon bar and also loads a relocatable
module called AMPLESupport (but see section 15, below).

Clicking once on the AMPLE icon on the icon bar displays the AMPLE window.

3. Resetting the AMPLESupport module
------------------------------------

It is not possible to run more than one copy of AMPLE at a time, so if a copy
of AMPLE is already running, then an error will be raised.

If AMPLE has crashed (for example) and when you try to run AMPLE again an
error is raised saying that AMPLE is already running, it is possible to reset
the AMPLESupport module by pressing F12 to go to the * prompt, then typing
the command

AMPLE_Reset<return>

Do not do this during normal operation!

4. Using AMPLE
--------------

AMPLE programs are created using any text editor. When the program is
complete, the file icon can either be dragged to the AMPLE icon or into the
AMPLE window. This causes the text file to be loaded in and compiled. Any
syntax errors in the program will be displayed in the Display area of the
AMPLE window.

Status messages are displayed in the AMPLE status bar, which is immediately
below the Display area in the AMPLE window.

5. Running AMPLE programs
-------------------------

If the program has compiled successfully, the AMPLE status bar will display

AMPLE file "<file>" compiled

If the Start button is now clicked once, an "Execute word" dialogue box will
open. Type in the name of the AMPLE word that you wish to execute (this will
usually be RUN) and click the Execute button once. The program will start
running, and the status bar will show

Executing "<word>"

When the program has completed, the status bar will show

Program completed

If a run-time error occurs, the status bar will show

Program aborted:error encountered

and the Display area will give more details. All voices are silenced.

If you have inserted rehearsal marks into the program and wish to start
running from one, then type in the rehearsal mark number into the field in
the Execute dialogue box. Normally, this will be left blank.

6. Stopping an AMPLE program
----------------------------

To stop an AMPLE program running, click once on the Stop button. All voices
are silenced.

7. Pausing an AMPLE program
---------------------------

To pause an AMPLE program while it is running, click once on the Pause
button. Note that voices are NOT silenced if this is done, so some notes may
remain on. Clicking again on the Pause button (which will be relabelled
"Restart" if paused) will restart the program.

8. Winding on an AMPLE program
------------------------------

To wind on an AMPLE program as fast as possible, click once on the Wind
button. To stop wind-on, click again on the Wind button (which will be
relabelled "Stop wind").

Note that the wind-on speed depends on how many other applications are
running alongside AMPLE, and may not be as fast as increasing the Tempo
slider value (see later).

9. Changing the overall volume
--------------------------------

To increase the overall volume of a composition while it is playing, drag the
Volume slider to the right. To decrease, drag left.

The Volume button (immediately above the slider) resets the slider to its
central position, which means "no change in volume".

10. Changing the overall tempo
------------------------------

To increase the overall tempo of a composition while it is playing, drag the
Tempo slider to the right. To decrease, drag left.

The Tempo button (immediately above the slider) resets the slider to its
central position, which means "no change in tempo".

11. AMPLE syntax
----------------

See the Docs.LangDesc text file for an explanation of the syntax of the RISC OS AMPLE dialect.

12. AMPLE word list
-------------------

See the Docs.Glossary text file for a full list of all RISC OS AMPLE system words.

13. AMPLE errors
----------------

See the Docs.Errors text file for a full list of RISC OS AMPLE errors.

14. MIDI file export
--------------------

AMPLE can be instructed to create a MIDI file of the music output instead of
playing it through a MIDI interface. This is done from the Execute dialogue
box by setting the "MIDI file export" tick box to ON, then clicking on the
Execute button. AMPLE will create a MIDI file, then will present a Save As
window from which you drag the MIDI file icon to a directory viewer.

See the Docs.Export text file for guidance on exporting AMPLE programs as
MIDI files.

15. Running AMPLE without AMPLESupport (AMPLE 0.25 and later)
-------------------------------------------------------------

It is possible to run AMPLE without the AMPLESupport module being in memory.
In this case, the only output mode available to you is MIDI file export.

To do this, modify the !Run file within the !AMPLE application directory to
set the system variable AMPLE$Module to zero (it defaults to one).

Note that if the AMPLESupport module is already in memory, AMPLE will always
use it, even if AMPLE$Module is set to zero.

This feature has been added to allow AMPLE to be run from the Archie
RISC OS emulator running under Windows. If you don't need to use this
feature, then don't use it.

Contact
-------

If you find any bugs or have any suggestions for improvement, please contact me at:

mailto:webmaster@aquitaine.demon.co.uk

detailing the problem and, if possible, including the AMPLE source file.
