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

Contents of part 2:

5. The Main menu
6. The Songs menu
7. The Configure menu
8. The Add Songs menu
9. Writing your own songs
10. Command line options
11. Explanations of error messages
12a. Changes from 1.0 to 1.1
12b. More! More features!
13. Getting in touch with the author



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.1
                        Add-in Songs for Telemate 3.10
                            (c) 1992 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 30 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 30 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 30 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.  (You may have to press it several times.)  Once
you have selected the song you want, you can press <ESC> to get
out of the song list window.

The 7 songs marked with a  *  may be installed in Telemate in the
Shareware version.  When you register, you can install all 30 of
them in Telemate.

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. The Configure menu

                                Configure Menu


                1  2  3  4  5  6  7  8  9  10  11  12  13  14  15

   <F>oreground color                   [ 10 ]
   <B>ackground color                   [  0 ]
   <H>ighlighted text foreground        [ 15 ]
   h<I>ghlighted text background        [  1 ]

   Directory for <T>elemate             [C:\COMM\                      ]
   <D>irectory for song files           [C:\COMM\TMUSIC\               ]
   Command line for text <E>ditor       [C:\DOS\EDLIN                  ]
   Directory for BASIC <P>LAY programs  [C:\BASIC\                     ]
   <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.

<F>oreground and <B>ackground set the colors for normal text, and
<H>ighlight foreground and h<I>ghlight text background set the
colors for highlighted text.  These are expressed in numbers from
0 to 15 whose color values are shown just below the menu title. 
(0 is black.)

<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
disk 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 text editor, EDLIN, is used.  I strongly
suggest that you procure a better text editor such as EMACS,
QEdit, Boxer, or *something* besides EDLIN.  (In a future version
of TMusic, if there is sufficient demand, I may include an
internal text editor with TMusic.  However I judged that it would
inflate the program size, and delay the release of 1.0, so that
it would be better to use an external editor, -- which would have
(if you use QEdit at least) a much richer set of features than
any editor I might write.)

<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.







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\Q                     ]
         <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.  You can play and test your own songs
without having to register TMusic first.

<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 -- if you are a
registered user.  You must have already selected a song file (see
<S> above).







9. Writing your own songs

To write your own songs to install 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







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.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.

  * An internal song editor (you will still be able to shell to
your own if you prefer) which will be maybe better for
interactive editing.

  * Ability to set the octave, tempo and style for the built-in
songs when playing or installing them (as registered users can do
in Merrie Musicks).








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.  I cannot promise a reply if you aren't a registered
user, but you can hope.  (Or register.)

Or, you can leave a message to JIM HENRY on the ILink Shareware,
SmartNet Shareware, or RIME Shareware conferences, or, in the
Atlanta area, on the Faster-than-Light main board conference:
   (404) 292-8761
I welcome comments (though I welcome registration fees even
more).


revised 10/2/92
[end of file]