[TMUSIC2.TXT
TMusic Documentation -- continued from TMUSIC1.TXT]

Contents of part 2:

5. The Main menu
6. The Songs menu
7. Configuring TMusic. -- The Configure menu; color selection;
        directories; how TMusic finds its files.
8. The Add Songs menu -- Directories, editor command line,
        playing songs, editing songs, importing BASIC programs,
        installing songs.
9. Writing your own songs. -- Command set; Hints.
10. Command line options. -- Monochrome mode; Load song file;
        Install random song.
11. Explanations of error messages
12a. Changes by version
12b. More! More features!
13. Getting in touch with the author. -- Address; echoed message
        conferences, bulletin boards.



5. The Main menu

When you start TMusic by typing TMUSIC and pressing ENTER at the
DOS prompt, the first thing to appear will be the Main Menu:


                                  TMusic 1.2
                    Add-in Songs for Telemate 3.x and 4.0
                        (c) 1992, 1993 Jim Henry III

                        REGISTERED TO: * Unregistered *



                             <S>ongs Menu
                             <C>onfigure TMusic
                             <A>dd your own songs
                             <P>rint Order Form
                             <F1> Help
                             e<X>it to DOS


Press the letter key that matches the menu selection you want; to
select from the 34 built-in songs, press S; to configure, press
C; to add new songs, press A; to exit, press X, etc.

Pressing F1 will get on-screen help at most any point in the
program.  To use the online help, just use the up and down arrow
keys to scroll through it and read it, and use <ESC> to exit Help
and return to the program.







6. The Songs menu

The Songs menu is where you select and listen to the 34 built-in
songs and install them into Telemate.


                                  Songs Menu


                   <T>est Songs   [ON ]
                   <I>nstall Selected Song
                   <S>elect Song  [Amazing Grace                             ]
                   <F1> Help
                   e<X>it to DOS
                   <Q>uit to Main Menu


Pressing <T> toggles whether to test (listen to) songs when you
select them.  If Test songs is ON, the song you select will be
played for you when you press ENTER on it.

Pressing <S> brings up the song list window.  You can scroll up
and down through the 34 songs with the up and down arrow keys,
and jump to the beginning or end of the list with Home or End. 
Pressing ENTER on a song selects it (and if Test Songs is on,
plays it).  While a song is being played, you can press any key
to stop playing.  Once you have selected the song you want, you
can press <ESC> to get out of the song list window.

Pressing <I> installs the selected song in the Telemate TM.CFG
file.  If you get an error message when you try to install a
song, you may not have specified the directory in which to find
Telemate.  Exit the Songs menu (press <Q>) and go to the
Configure menu to set the directory for Telemate.







7. Configuring TMusic


                                Configure Menu





   Set <N>ormal text color
   Set <H>ighlighted text color



   Directory for <T>elemate             [C:\COMM\                      ]
   <D>irectory for song Files           [D:\QB\MUSIC\                  ]
   Command line for text <E>ditor       [C:\MISC\Q                     ]
   Directory for BASIC <P>LAY programs  [D:\QB\MUSIC\                  ]
   <M>ake backup of TM.CFG              [Yes]
   <S>ave configuration

   <F1> Help
   e<X>it to DOS
   <Q>uit to Main Menu


The Configure menu sets the screen colors, the directories to
find Telemate, song files, BASIC programs, and your text editor
in, and whether to make a backup of Telemate's TM.CFG file.

<N> and <H> set the Normal and Highlighted text colors.  When you
select either of these, you will see a grid of colors, background
colors horizonal and foreground colors vertical.  Use the arrow
keys to select the color combination you want and press <Enter>. 
If you don't want to change the colors, press <Esc>.


         Normal text

          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x                 <Enter> Select these colors
          x  x  x  x  x  x  x  x                 <Esc> Return to previous colors
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x
          x  x  x  x  x  x  x  x

(All those x's will be different colors.)

<T> sets the directory in which to look for TM.CFG, Telemate's
configuration file.  If this is not set correctly, the Songs menu
will be unable to Install songs without error messages.  Press
<D> and type the name of the directory where you keep Telemate,
e.g.  C:\COMM\    or   D:\TELEMATE\   or   C:\TM\
You don't need to set this if you have TMusic in the same
directory as Telemate.  If you have it in a subdirectory
immediately below Telemate (e.g. Telemate is in C:\COMM\ and
TMusic is in C:\COMM\TMUSIC\ ) then you can specify the Telemate
directory as  ..\  (two periods), that is, the directory above
the current one.  The drive is optional if TMusic is on the same
drive as Telemate (i.e. \TELEMATE\ is as good as C:\TELEMATE\ ).

<D> sets the directory in which to find your user-written song
files.  The same remarks apply to it as to the Telemate
directory.

<E> sets the drive, path and filename of your text editor.  In
the above menu, the DOS 5.0 text editor, EDIT, is used.  If you
have an older version of DOS, you may have to use EDLIN.  I
strongly suggest you get a better text editor.

<P> sets the directory in which to find BASIC programs for
importing them into TMusic song file format.  The same remarks
apply to it as to the other directory names.

<M>ake backup or not?  If this option is Yes, then before it
installs a song, TMusic will make a copy of TM.CFG as
TM-CFG.OLD.  (If TM-CFG.OLD already exists it will not be
created.)  This is so that if because of some unknown bug (e.g.
an incompatibility with earlier versions of Telemate) the Install
Song routine messes up your TM.CFG file, you will have an earlier
version from before you used TMusic.  To restore the backup, go
to your Telemate directory and type
    copy  tm-cfg.old  tm.cfg
and ENTER.

When you have set all the options as you want them, you can press
<S> to save the options in the TMUSIC.CFG file.

                    How TMusic finds its files

TMusic will look for its files (SONGS.DAT, TMUSIC.HLP, and
TMUSIC.CFG) in any of several places.  First, it checks to see
whether you have told it to look for them in a particular
directory, by using an environment variable.  If you have placed
a command in your AUTOEXEC.BAT

SET TMUSIC=C:\TM\TMUSIC\

or whatever directory TMusic's files are to be found in, it will
look there.  Otherwise, it looks through all the directories of
your DOS PATH to see if it can find SONGS.DAT in any of them. 
Finally, it will look in the present directory.  If you don't
want to place TMusic's directory in an environment variable or
your DOS path, you should start it from the same directory in
which its files are.






8.  The Add Songs menu

                                Add Songs Menu

                          Thank you for registering!

         Directory for song <F>iles         [C:\QBASIC\MUSIC\              ]
         <T>ext editor command line         [C:\MISC\EDIT                  ]
         <D>irectory for BASIC programs     [C:\QBASIC\MUSIC\              ]
         <S>elect song file                 [C:\QBASIC\MUSIC\CAMPTOWN.SNG  ]
         <E>dit selected song file
         <P>lay selected song file
         Import <B>ASIC program
         <U>se comments in conversion       [Yes]
         <I>nstall song in Telemate

         <F1> Help
         e<X>it to DOS
         <Q>uit to Main Menu


<F> selects the directory in which to find your user-written song
files.  It works the same way as the option on the Configure
menu.

The <T>ext editor command line and <D>irectory for BASIC programs
are explained more fully under the Configure menu.

<S> selects the user-written song file to edit.  This is an ASCII
text file containing music commands.  For information on how to
use the music commands, see the next section, "Writing your own
songs."  When you press S the cursor will appear in the song file
[     ] brackets.  You can type the name of the file to edit here
(you must do so if this is a new file and doesn't yet exist), or
you can press <TAB> to load the song files directory.

The directory window will appear and the first file in the
directory will be highlighted.  You can use the up and down arrow
keys, PageUp and PageDown, Home and End to scroll through the
directory listing.  Pressing a letter key will jump to the next
file or directory whose name begins with that letter.  Pressing
<ENTER> on a file will select that as the song file to edit, play
or install; pressing <ENTER> on a directory (marked as <DIR>)
will load that directory to view.  To change drives, you can
press <TAB> again and the cursor will appear in the top part of
the directory window for you to type the drive and/or directory
name there.

To get out of the directory window, you can press <ESC> or press
<ENTER> with the highlight bar on the file you want to select.

<E> shells out of TMusic to your text editor to edit the selected
song file.  You must have already specified both the text editor
command line and the song file.

<P> plays and tests the selected song file.  If any errors are
found in the song file, a message will say so and the bad command
will remain highlighted.

<B> imports from a BASIC program containing PLAY statements and
writes the music commands to the selected song file.  You must
first have selected a song file to edit.  This option loads the
directory and you can scroll through the directory window and
select the program you want to import.  For details on using the
directory window, see above under the <S>elect song option.

<U>se comments in conversion?  If this option is Yes, when a
BASIC program is imported to a song file, all REM, ', and PRINT
statements will be sent to the song file as comments ( ' ).  If
it is No, only the PLAY statements in the BASIC program will be
processed.  Only PRINT commands followed by literals (PRINT
"strings in quotes") will be sent as comments; those followed by
variables (PRINT VARIABLE$) or formulas (PRINT MID$(VARIABLE$, 3,
5)) will not be processed.

<I> installs the selected song file into Telemate.  You must have
already selected a song file (see <S> above).







9. Writing your own songs

To write your own songs to install them in Telemate, you will
need to create and edit an ASCII text file containing music
commands.  It can also contain comments.  The music commands are,
with a few exceptions, those used by the BASIC PLAY command and
the ANSI music standard.


C, D, E, F, G, A, and B -- Play a note.

# or + -- coming after a note command, e.g. C+ or C#, plays the
note sharp.  E and B *cannot* be played sharp.

- -- coming after a note command, e.g. E- , plays the note flat. 
C and F *cannot* be played flat.

. -- coming after a note command, e.g. C. , plays the note for
half-again as long as otherwise.

N -- followed by a number 0 to 84, plays a numbered note on a
chromatic (12-tone) scale, where 25 is middle C, 26 is C sharp,
27 is D, and so on.  1 is the lowest note, 84 the highest; 0 is a
rest (pause).  N commands can be followed with . but not #, + or
-.  O commands do not affect N commands.

O -- followed by a number 0 to 6, specifies in what Octave to
play the following notes.  The octave with middle C is 3.

> -- goes up one octave.
< -- goes down one octave.

L -- followed by a number 1, 2, 4, 8, 16, 32 or 64, tells what
Length to play the following notes.  L8 says to play eighth
notes, L2 to play half notes, L1 whole notes, etc.  A single note
command can also be followed with any of those numbers, e.g.  C4
plays a fourth-note C.  In   "L4 CC F2", the two C's would be
played as fourth notes, the F as a half note.

P -- followed by a number 1, 2, 4, 8, 16, 32 or 64, pauses for
that fraction of a second, e.g. P1 pauses for 1 second, P8 for an
eighth of a second, etc.

T -- followed by a number 32 to 255, sets the Tempo (speed).  32
is slowest and 255 fastest.  For most songs the appropriate tempo
is around 100-120.

ML -- Plays the following notes Legato, i.e., all run together
with no slightest pause between notes.

MS -- Plays the following notes Staccato, i.e., with longer
pauses between each note so each one is heard more distinctly.

MN -- Plays following notes Normal, with a shorter pause between
notes than Staccato.

The following commands valid in BASIC PLAY statements are *not*
allowed in TMusic or Telemate:

MF and MB (which specify foreground or background in BASIC).

X (which plays notes in a string variable in BASIC).

The comment command is unique to TMusic:

' -- comment.  Anything following a ' in a TMusic song file will
be ignored by TMusic when it plays or installs the song.  Use
this to include the words to the song for your own reference, and
to begin the song file with the name of the song.



                     Putting it all together


Here is some useful advice about writing songs for TMusic.

Begin the file with a comment saying what song it is, then a
setup line, then the notes of the song:

          
           ' HERO'S QUEST I theme music
          
          T110 MN O3 L8  ' setup
          
          C.DEF.G.A.G. P8
          G.FEF.C.D. P8
          <G.>C.DEF.G.A.G. P8
          G.FEF.EDC.
          
The setup line sets the tempo, the style (legato, staccato, or
normal), the octave to begin with, and the default note length.

It is generally a good idea to have only one O command to set the
octave at the beginning, and then use < and > to go up or down
octaves.  This way, when you want to play the entire song in a
higher octave, you can change the one O command at the beginning
and then the <'s and >'s will adjust automatically.

When I add a new song, I work from the sheet music if I can get
it, or play it by ear on the piano keyboard; translate the notes
into PLAY notation, and then try them out. -- Usually I get the
sequence of notes right the first time; the timing (length of
each note, and placement and length of pauses) takes a lot of
tinkering to get right.

If you put together some good song files, you might send them to
me.  If they are good enough that want to I include them as
samples in the next release of TMusic, I'll give you $4 off any
registration or upgrade on TMusic or any other of my programs
(Yggdrasil, Merrie Musicks, and TConv).  (If you send me a disk,
be sure to clearly mark the envelope as MAGNETIC MEDIA.)






10. Command Line Options

If you have a monochrome monitor, starting TMusic with

  TMUSIC /M

will set the colours to grey for normal and bright white for
hilight.

You can tell TMusic which song file to work with by starting it
with, for example,

  TMUSIC /S:HERO.SNG

To install a randomly selected song, use the /RND switch.  This
switch has several options.  Before you can use the /RND switch,
you must already have told TMusic where to find Telemate, where
to find song files, and where to find its own TMUSIC.CFG and
SONGS.DAT files.  See above, under "Configuring TMusic."

/RND!               Install any of the 34 built-in songs.
/RND;1;4;9;16;25    Install one of the numbered songs listed on
                    the command line.  For an example of how to
                    use this option, see PATRIOT.BAT.
/RND?               List the 34 built-in songs by number.
/RND+filename.lst   Install one of the song listed in 
                    filename.lst.  Each line of this file is
                    either a song number prefixed by a ; or the
                    filename of a user-created song file.  For
                    examples of how to use this option, see
                    HYMN.BAT and HYMN.LST, ALLSONGS.BAT and
                    ALLSONGS.LST.

You may wish to try using TMUSIC with one of these options in
your Telemate batch file, so that every time you run Telemate you
will have a different song playing on connects and file
transfers.  For example,

rem --------
@echo off
c:
cd\telemate\tmusic
tmusic /rnd;15;17;27
cd\telemate
tm
cd\
rem --------

If you wish to use one of the included batch files (PATRIOT.BAT,
HYMN.BAT, ALLSONGS.BAT), use the CALL batch command, thus:

rem ------
cd\telemate
call allsongs.bat
tm
cd\
rem ------


Otherwise, the Telemate batch file will go to the TMusic batch
file and NOT return and go on.


11.  Error messages

These error messages should be pretty obvious:  
  
You must specify the song filename.
File not found 
File already exists 
Disk full
Disk is write protected 
Disk not ready
Unformatted or possible non-DOS disk 
Directory not found
Printer not ready 

These might require a bit of explanation:

Invalid file name -- You used illegal characters in the filename
        or directory name, such as +<>/\*? and some others.  Try
        again with a different filename.

Possible read-only file -- Use the DOS ATTRIB command or the
        Norton Utilities FA command (see the respective manuals
        for details) to check if it is read-only.  If it isn't, I
        don't know what the problem is; read-only files are only
        one of the problems that can cause this error code, which
        is actually called a "Path/File Access error."

You must specify a text editor to use. -- To specify the editor,
        use the <T> command on the Add Songs menu or the <E>
        command on the Configure menu.  Be sure to <S>ave the
        configuration after you type the editor name, etc.

FILENAME exists; <O>verwrite, write to <E>nd, <C>ancel? -- Used
        when importing a BASIC program to a song file, and the
        specified song file already exists.  Unless you are quite
        sure you want to erase what is already in the song file,
        type E or C.

Bad music command: -- Followed by a line of music commands, with
        the bad one hilighted.  This can be caused by: a T, O, L
        or N command with no number after it; an invalid command
        such as X, R, J, etc. or &, ^, etc.; a number out of
        place, e.g. at the beginning of a line or after a > or
        <.  Go back and edit the song file to remove or correct
        the offending command, and try again.

Error # nn -- Oops!  This means a bug I didn't catch before I
        released TMusic.  Please write or send me e-mail to let
        me know what error number you got, and under what
        circumstances.  (See below under "Getting in touch with
        the author".)







12a. 

Changes from 1.1 to 1.2

Four new songs:
   Turkey in the Hay
   Jesu, Joy of Man's Desiring
   She'll be Coming 'Round the Mountain
   Oh! Susanna

Unregistered users can now install all 34 built-in songs into
Telemate, as well as their own song files.

An opening screen with "Press <random function key> to continue"
for unregistered users.

The /RND switches were added.  See section 10, "Command Line
Options".

Sample batch files to demonstrate use of /RND switches were
added: ALLSONGS.BAT, HYMN.BAT, and PATRIOT.BAT.

The color selection interface was much improved.  See section 7,
"Configuring TMusic".

Error messages now prompt you to press <F1> for help.

TMusic will look through the DOS path and for a TMUSIC=
environment variable for its data files.

A bug in the directory window (<F1> Help did not work there) was
fixed.

A bug which messed up the screen when installing a user-written
song has been fixed.


Changes from 1.0 to 1.1

There was need of a MAJOR bug fix, to wit, in 1.0 unregistered
users could not install ANY songs.  This has been fixed.

Also, there was an incompatibility with DOS 5.0.  It now works
under DOS 5 as well as 3.3.  It has not been tested under other
versions of DOS.

The interactive debugging of user-written songs was improved so
that each note is hilighted as it is played.

In the directory window, pressing a letter key now jumps to the
next file whose name begins with that letter.





12b.  More!  More features!

Here are some of the features I hope to add in future versions of
TMusic:

  * Ability to import ANSI music textfiles just as it now imports
BASIC programs.







13. Getting in touch with the author

Send land mail to:

          Jim Henry III
          405 Gardner Road
          Stockbridge, GA  30281-1515

Please send a self-addressed stamped envelope and/or international
reply coupons.

Send email to JIM HENRY on any of these echoed message
conferences:

          RIME Shareware or RIME/Fido Telemate
          ILink Shareware
          Smartnet Shareware or Smartnet Telemate 

Or, in the Atlanta area, on the Faster-than-Light main board
conference:

          (404) 292-8761

or OASis main board conference,
          
          (404) 627-2662 

I welcome comments (though I welcome registration fees even
more).



revised 2/8/93 -- end of file]