home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / games / music2.zip / MUSIC2.DOC < prev    next >
Text File  |  1988-08-27  |  41KB  |  1,032 lines

  1.                                                                       -Page 0-
  2.                          MUSIC2 program documentation
  3.  
  4.  
  5. =================================== MUSIC2 ===================================
  6.  
  7.                                    CONTENTS
  8.  
  9.                        Item                        Page  (new)
  10. Introduction:
  11.   General information------------------------------   1
  12.   Warning!-----------------------------------------   1
  13.   Starting out; some files-------------------------   2  *
  14.   Running the program------------------------------   2
  15. Entering music--the basic functions:
  16.   Entering notes-----------------------------------   3
  17.   Pauses (rests) (space bar)-----------------------   4
  18.   Note length (1,2,4,8,6; !,@,$,*,^)---------------   4
  19.   Dotted notes (period key)------------------------   5
  20.   Tied notes (dash key)----------------------------   5
  21.   When to enter dots, ties, and note lengths-------   5
  22.   Maximum number of notes--------------------------   5
  23. Some additional music settings:
  24.   Tempo (SHIFT/F5)---------------------------------   6
  25.   Note duration (SHIFT/F9)-------------------------   6  *
  26.   Fore/back-ground (SHIFT/F7)----------------------   6  *
  27.   Time (or measure) (M or m)-----------------------
  28.   Repeats:
  29.     Begin definition (open parens)-----------------   7  *
  30.     End definition (close parens)------------------   7  *
  31.     Execute definition (X or x)--------------------   7  *
  32. Non-playable music settings:
  33.   Help panels (question mark key)------------------   8  *
  34.   Playing the tune (F1)----------------------------   8  *
  35.   Playing and drawing the tune (SHIFT/F1)----------   8
  36.   Loading previously saved music (CTRL/Pg Up)------   8
  37.   Saving your music (CTRL/Pg Dn)-------------------   8
  38.   Turning the sound on and off (V or v)------------   9  *
  39.   Getting out of the routine (Esc)-----------------   9  *
  40. Editing functions:
  41.   Moving the cursor:
  42.     Cursor right-----------------------------------  10  *
  43.     Cursor left------------------------------------  10  *
  44.     Go to start of current screen (Home)-----------  10  *
  45.     Go to end of current screen (End)--------------  10  *
  46.     Previous screen (Pg Up)------------------------  11  *
  47.     Next screen (Pg Dn)----------------------------  11  *
  48.     Go to start of music (CTRL/Home)---------------  11  *
  49.     Go to end of music (CTRL/End)------------------  11  *
  50.   Changing notes:
  51.     Overstrike-------------------------------------  11  *
  52.     Delete-----------------------------------------  11  *
  53.     Insert-----------------------------------------  11  *
  54.     Global change (C or c)-------------------------  12  *
  55.   Compiling (SHIFT/F3)-----------------------------  12  *
  56. The MUSIC2 screen display--------------------------  13
  57. How the music is stored----------------------------  14
  58. Changes between original MUSIC package and MUSIC2--  15
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.                                                                       -Page 1-
  69.                          MUSIC2 program documentation
  70.  
  71.  
  72.                                  INTRODUCTION
  73.  
  74. General information:
  75.      MUSIC2 is the  second  revision  of the MUSIC program which appeared on a
  76. Washington, D.C. Capital PC User's Group disk  in August 1982.  Revisions made
  77. since that time are briefly described at the end of this file.
  78.      MUSIC2 is a  BASIC  program which helps you create and play music on your
  79. PC.  The package utilizes the "PLAY" command  in BASIC and allows you to enter
  80. and play one `voice' (note) at a time as if your PC was a piano keyboard.
  81.      You may enter  whole,  half,  quarter,  eighth,  or sixteenth notes.  The
  82. notes may be tied together to create notes of any longer length.  You may also
  83. play  dotted  notes  (notes  which play one-and-a-half times  as  long  as  an
  84. undotted note).  Notes are entered directly from the keyboard  and  flats  and
  85. sharps are shown as flats (A-sharp is shown as B-flat).
  86.      Your piece of  music  may  be  saved  at  any  time.  You  may  also load
  87. previously stored music files at any time for editing or playing.
  88.      In order to  use  the program, you will need at least 64K, if not 96K, of
  89. RAM.  Displays  are  in 40-column low-resolution  graphics  mode.  While  some
  90. displays  show  some  color, this was accidental and a  color  screen  is  not
  91. needed.
  92.  
  93. Warning!
  94.      Due to a peculiarity in compiled BASIC, it's possible to create an
  95. overflow condition in the music buffer.  This results in the program aborting.
  96. Some advice: (a) save your compositions before playing them, and (b) make
  97. music foreground (see SHIFT/F7) the default when you're creating your music
  98. and then, optionally, switch to music background when everything's saved and
  99. ready to rip.
  100. ==============================================================================
  101.      This is yet another one of those free programs which begins by asking you
  102. to send money if you find it useful (or even cute).  The program  took quite a
  103. bit of work and it you want to contribute something  like  $15, I'd be tickled
  104. pink.
  105.      Please mail  money,  comments,  suggestions,  or  pictures of cute single
  106. women to me at:
  107.                                 Bruce Guthrie
  108.                                 113 Sheffield St
  109.                                 Silver Spring, MD 20910
  110. ==============================================================================
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.                                                                       -Page 2-
  136.                          MUSIC2 program documentation
  137.  
  138.  
  139. Starting out; some files:
  140.      The following  input  files  are  provided  with the MUSIC2 package.  The
  141. descriptions are split into three groups (required  files,  documentation, and
  142. sample music) and approximate sizes in bytes are shown.
  143. --filename    size comments --Program       files-- SPACE=50700 bytes
  144. MUSIC2  .EXE 50700 the actual program; compiled in BASIC
  145. --filename    size comments --Documentation  file-- SPACE=40800 bytes
  146. MUSIC2  .DOC 40800 instructions for the program
  147. --filename    size comments --Sample data  files--  SPACE=14800 bytes
  148. COLOUR  .MUS  1300 "Colour My World" by Chicago
  149. DAYLIFE .MUS  3500 "A Day in the Life" by the Beatles
  150. HANDNEWS.MUS  3000 "Second Hand News" by Fleetwood Mac
  151. HOMEWARD.MUS  1800 "Homeward Bound" by Simon and Garfunkle
  152. OVERHEAD.MUS  3000 "Over My Head" by Fleetwood Mac
  153. PAPERBAK.MUS  2200 "Paperback Writer" by the Beatles
  154.      The total approximate  space  is  106,300 bytes; a sizable portion of any
  155. disk.
  156.      It should be pointed out that, of the sample files included, OVERHEAD.MUS
  157. illustrates some of the problems of putting music into  the PC.  More than one
  158. voice is required to make "Over My Head" work on a PC and there's  no  way  to
  159. come close to this song in BASIC.
  160.  
  161. Running the program:
  162.      While in DOS,  type "MUSIC2".  The screen clears, its title (and my name)
  163. are printed, you are told to type a "?" (question mark) if you want to see the
  164. help panels, and then the program reads some graphics definitions.
  165.      The program  asks  you  for  the  title  of  the  composition you will be
  166. creating.  Once entered, the title can only be changed with EDLIN or a similar
  167. editor.  If you will be loading a previously stored  music  file, you need not
  168. fill in a title as the routine will use the title stored  with the file.  Only
  169. the first 32 characters of the title will be displayed.
  170.      Next, the program  will  draw  a  bass  and treble clef for you.  The top
  171. lines of the display will show:
  172.                     Tempo: t120         Note duration: mn
  173.                    Note length:  4     Fore/back-ground: mb
  174.  
  175.                         Default time=4/4   h=middle C
  176. Each of these statements is explained in individual sections below.
  177.      After a moment,  a  flashing  note  sign will appear at the bottom of the
  178. screen and you may begin to enter your music.
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                                                                       -Page 3-
  203.                          MUSIC2 program documentation
  204.  
  205.  
  206.                      ENTERING MUSIC--THE BASIC FUNCTIONS
  207.  
  208.      When you think  of  music,  you  think  of  notes  on  a  piece of paper.
  209. Initially you will want to enter the  notes  themselves before you worry about
  210. things like tempo and whether the music is played staccato  or  not.  The next
  211. section is for you!
  212.  
  213. Entering notes:
  214.      The initial  display  tells you that the "h" key is middle C.  Basically,
  215. the middle row of white keys on your PC are the white keys  on  your PC piano.
  216. "a" is an E, "b" is  an  "F",  "c"  is  a "G", et cetera all the way up to "`"
  217. which is another "B".  By pressing the Alt key when you enter "a" through "l",
  218. you will get notes an octave lower than regular.  By pressing  the  shift key,
  219. you will get notes an octave higher.  By pressing the CTRL key,  you  will get
  220. notes two octaves higher.
  221.      Due to BASIC  limitations,  the  program  ignores any illegal Alt or CTRL
  222. request (for example, forget Alt/;).
  223.      The basic octave  ranges  provided by each of the note combinations (Alt,
  224. regular, shift, and CTRL) is shown in the chart below:
  225.                note key Alt reg shift CTRL
  226.                F                       *
  227.                E                       *
  228.                D                       *
  229.                C                       *
  230.                B                  *    *
  231.                A                  *    *
  232.                G                  *    *
  233.     +--------- F                  *    *
  234.    t|          E                  *    *
  235.    r+--------- D                  *
  236.    e|          C                  *
  237.    b+--------- B             *    *
  238.    l|          A             *    *
  239.    e+--------- G             *    *
  240.     |          F   l         *    *
  241.     +--------- E   k         *    *
  242.                D   j         *
  243.      middle c  C   h         *
  244.                B   g         *
  245.     +--------- A   f         *
  246.    b|          G   d         *
  247.    a+--------- F   s    *    *
  248.    s|          E        *    *
  249.    s+--------- D        *
  250.     |          C        *
  251.     +--------- B        *
  252.     |          A        *
  253.     +--------- G        *
  254.                F        *
  255.                E        *
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.                                                                       -Page 4-
  270.                          MUSIC2 program documentation
  271.  
  272.  
  273.      Flats and sharps  are  obtained from using the row of keys directly above
  274. the  a  to  ~ row.  Flats and sharps are determined by their position  on  the
  275. keyboard.  For example, the "t" key is just above and  to the right of the "f"
  276. key.  It is also above and to the left of the "g" key.  Since  the  "f" key is
  277. an A and the "g" key is a B, "t" is A-sharp or B-flat.  All  sharps  are drawn
  278. as the flatted equivalent (you may want an A-sharp,  but it will be drawn as a
  279. B-flat).
  280.      The sharp and flat keys work in combination with the Alt, shift, and CTRL
  281. keys in a manner consistent with the regular note keys.
  282.      The length of  each note is determined by the default note length setting
  283. (initially 4--quarter  notes)  or,  if  you have specified one, any overridden
  284. note length (if you press the "6" key before entering the note, that note will
  285. be a sixteenth note).  Setting note lengths is described below.
  286.      Once you have  entered  a note, you can change it to something else on an
  287. individual  basis  through  the MUSIC2 editor (described  below)  or  globally
  288. through the global change command ("C" or "c"--also described below).
  289.      WARNING:  If  you  have  Caps  Lock  set,  you will get the equivalent of
  290. shifted letters each time.  This is advantageous sometimes  while  a  pain  at
  291. other  times.  Be  aware of where you have it set in either  case.  Caps  Lock
  292. does not effect non-letters (";", "'", "`", "[", and  "]" keys must be shifted
  293. individually).
  294.  
  295. Pauses (rests):
  296.      If you press  the space bar, a rest of whatever length you've set will be
  297. entered into the music.
  298.      Once entered,  the  rest  may  be  changed  into  something  else  on  an
  299. individual basis through the MUSIC2 editor (described below).
  300.  
  301. Note length:
  302.      The note length  shows  you  the  default  length  for  each note.  A "4"
  303. indicates that, unless overridden for specific notes,  each  note  will  be  a
  304. quarter note.  A "2" indicates a half note, "8" indicates and eighth note, and
  305. "1" and "16" are assigned  accordingly.  You  can change the note length for a
  306. given note by entering either a "1", "2", "4", "8" or  "6"  (for  16th) before
  307. you enter the note.  You may change the default note length to any of these by
  308. pressing the SHIFT key while you enter them (thus "!", "@",  "$", "*", and "^"
  309. set the default note lengths to 1, 2, 4, 8, and 16 respectively).
  310.      Once entered,  you  cannot  automatically  change  all  note  lengths  to
  311. something else (for example, change all quarter notes to eighth  notes).  Note
  312. length  changes can be achieved only by editing each individual  note  through
  313. the MUSIC2 editor described below.
  314.       If more than  one  length  is  given  for a note (for example, you enter
  315. "12h"), the last length  entered  wins  (in  this  example, "2" wins and the C
  316. becomes a half note).
  317.      WARNING:  The  note  lengths  are entered by using the upper row of keys,
  318. not through the numeric keypad.  The numeric keypad is reserved for Editing.
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.                                                                       -Page 5-
  337.                          MUSIC2 program documentation
  338.  
  339.  
  340. Dotted notes:
  341.      In order to  dot  a note (playing it for 3/2 times its specified length),
  342. you must enter a period (".") before entering the note.
  343.      The dotted note  indicator toggles.  If you press it once, the note which
  344. follows will be dotted.  If you change you mind and  press  it  a second time,
  345. the note which follows will be regular.  (Of course if you  press  it, enter a
  346. note, press it again, and enter a note, both notes will be dotted).
  347.  
  348. Tied notes:
  349.      In order to  tie notes together (across measures or to create an smoothly
  350. sliding  or  rising string of notes), enter a dash ("-") before  entering  the
  351. note.  That note will be tied to the one which you enter after it.
  352.      The tied note  indicator  toggles.  If  you press it once, the note which
  353. follows will be tied.  If you change you mind and press  it a second time, the
  354. note which follows will be regular.  (Of course if you press it, enter a note,
  355. press it again, and enter a note, both notes will be tied).
  356.  
  357. When to enter dots, ties, and note lengths:
  358.      You have been  told  that  to tie a note, you have to enter a dash before
  359. entering  the  note.  For  example,  to get a tied C, you  might  enter  "-h".
  360. Dotted notes are similarly indicated  (a  period  and  then  the note), as are
  361. notes with a length different from the default (a sixteenth note is created by
  362. entering the number 6 and then the note).
  363.      If you have  more  than one of these to specify, they can be specified in
  364. any order as long as they all precede the note itself.  For  example, a dotted
  365. sixteenth note C could be ".6h" or "6.h".  Also, a dotted,  tied eighth note C
  366. could be ".6-h" or "-.6h" etc.
  367.  
  368. Maximum number of notes:
  369.      The maximum  number  of  notes  (including  special  notes like measures,
  370. repeats, et cetera) is set as 1,000.
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.                                                                       -Page 6-
  404.                          MUSIC2 program documentation
  405.  
  406.  
  407.                         SOME ADDITIONAL MUSIC SETTINGS
  408.  
  409.      The following  MUSIC2 functions have a direct effect on how your music is
  410. displayed or played.  These functions can usually be  ignored by initial users
  411. of the program but will be necessary to make your music come out anything like
  412. you want it to.
  413.  
  414. Tempo:
  415.      The tempo can  be  set to any value between 32 and 255 using the temp set
  416. key  (SHIFT/F5).  The  higher  the  number,  the faster the  notes  play.  The
  417. initial display panel tells you that the tempo setting defaults to 120.
  418.      The tempo setting  is  stored  and  displayed  as  a special note in your
  419. music.  It can be changed at any time by choosing a new  tempo setting or else
  420. by modifying the special note through the MUSIC2 editor described below.
  421.  
  422. Note duration:
  423.      The initial  display  panel  tells  you that the default note duration is
  424. "mn".  The  note duration  is  different  from  note  lengths.  Note  duration
  425. settings  are set by using the toggle staccato/normal/legato  key  (SHIFT/F9).
  426. "mn" is music normal;  each  note  plays for 7/8 of the time specified for its
  427. length (simulating the normal movement between keys).  "ml"  is  music legato;
  428. each note plays for the entire time specified by its  length.  Music legato is
  429. used automatically to tie notes.  "ms" is music staccato; each  note plays for
  430. 3/4 of the time specified for its length.
  431.      The duration  of  each note is stored with each note.  In order to change
  432. these  durations,  you can either manually edit each note through  the  MUSIC2
  433. editor described below or you may globally change all notes with one type of a
  434. setting  to something else (e.g. all music staccato notes to  music  normals).
  435. The latter is the global change function ("C"  or "c") which is described with
  436. the MUSIC2 editor.
  437.  
  438. Fore/back-ground:
  439.      The initial  display  panel  tells  you that the default fore/back-ground
  440. setting in "mb".
  441.      The fore/back-ground  setting  indicates whether the music will be played
  442. in the foreground ("mf"--playing and drawing each note  simultaneously)  or in
  443. the  background ("mb"--putting notes to be played in a buffer  when  possible,
  444. allowing  a  more  even  flow  of audible music but probably  resulting  in  a
  445. different note being displayed than that being played).  You  may  change  the
  446. ground setting by pressing the fore/back-ground key (SHIFT/F7).
  447.      The fore/back-ground setting is stored and displayed as a special note in
  448. your music.  It can be changed at any time by choosing a new  fore/back-ground
  449. setting  or  else  by  modifying  the special note through the  MUSIC2  editor
  450. described below.
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.                                                                       -Page 7-
  471.                          MUSIC2 program documentation
  472.  
  473.  
  474. Time (or measure):
  475.      The initial  display  panel tells you that the default time is 4/4.  This
  476. means that four quarter notes will make up each measure.  You can override the
  477. time  by pressing the change measure ("M" or "m") key.  What  you  enter  here
  478. will not effect how the music is played (there is no cut-time indicator), just
  479. where measure breaks are drawn.
  480.      The time setting is stored and displayed as a special note in your music.
  481. It can be changed at any time by choosing  a  new setting or else by modifying
  482. the special note through the MUSIC2 editor described below.
  483.  
  484. Repeats:
  485.      Repeats are  generated by specifying the music portion to be repeated and
  486. then  by  saying  the play (execute) that portion of music.  This  process  is
  487. described below.
  488.    * Begin definition:  In  order  to specify where the repeated music begins,
  489. use  the  "("  (open  parens) key.  The routine will assign a number  to  this
  490. particular "sub-definition" of your music.  The numbering  begins with 0.  The
  491. maximum  number  is  10 (allowing 11 sub-definitions).  Numbers  are  assigned
  492. sequentially.  Any number of sub-definitions (up to 11) can be open at a time.
  493.    * End definition:  In  order  to specify where the repeated music ends, use
  494. the  ")"  (close parens) key.  The routine will close the most-recently-opened
  495. sub-definition.  (If 0 and 1 are open, 1 will be closed when you press ")".)
  496.    *  Execute  definition:  In   order   to  play  a  previously-defined  sub-
  497. definition, enter "X" or "x".  The routine will ask  you for the number of the
  498. sub-definition you want to play here.
  499.      Note that sub-definitions are ignored when measures are calculated.
  500.      The repeat keys  generate  special notes and are drawn on the screen like
  501. any normal note.  They may be revised or deleted  like  any  note  through the
  502. MUSIC2 editor (see below).
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.                                                                       -Page 8-
  538.                          MUSIC2 program documentation
  539.  
  540.  
  541.                          NON-PLAYABLE MUSIC SETTINGS
  542.  
  543.      The following  MUSIC2 functions will not actually effect the music you're
  544. trying to create.  They are still pretty vital though.
  545.  
  546. Help panels:
  547.      The contents  of  the dataset MUSIC2.HLP will be displayed on your screen
  548. if you use the help request key ("?"--a question mark).
  549.  
  550. Playing the tune:
  551.      Once you've entered any portion of the music, you can have it played back
  552. for you without displaying it by press the play tune  key  (F1).  You  may not
  553. play the tune while in Insert mode.
  554.      This function  is  not  effected  by  whether  you have turned the volume
  555. (sound) on or off through  the  "v"  function  (see  below).  There is a pause
  556. before the tune is played as the PC consolidates its memory.
  557.  
  558. Playing and drawing the tune:
  559.      Once you've entered any portion of the music, you can have it played back
  560. and  displayed  by  pressing  the  play and draw key (SHIFT/F1).  This  option
  561. cancels you out of Edit mode if necessary.  You may  not  select  this  option
  562. while you're in Insert mode.
  563.      If you have  opted  to  turn  the  sound  off  (though  the  "v" function
  564. described below), the music will be drawn only.  There  is  a pause before the
  565. tune is played as the PC consolidates its memory.
  566.  
  567. Loading previously-saved music:
  568.      If you want  to  load  some previously stored music, press the load-from-
  569. disk key (CTRL/Pg Up).  You will be prompted for the name of the file to load.
  570. If  it  is on a non-default disk drive,  specify  that  with  the  name  (e.g.
  571. "b:test").
  572.      Once the music  is loaded, it is compiled. During this time, the music is
  573. condensed  where  possible  and  a  table of repeat calls  is  generated.  For
  574. information on this process, see the discussion of compiling music (below).
  575.      After compilation,  you  are  dumped  at the end of the piece.  Note that
  576. settings  like  tempo,  note  duration,  and time are not set until  the  code
  577. containing  these settings is played.  If you set non-  default  settings  for
  578. these, you should ask to play the music from the beginning  in  order  to have
  579. them activated.
  580.  
  581. Saving your music:
  582.      In order to  save  a  file  of music, press the save-to-disk key (CTRL/Pg
  583. Dn).  You will be prompted for the  name  of the file to save it as.  If it is
  584. to  be  saved on a non-default disk drive, specify that with  the  name  (e.g.
  585. "b:test").
  586.      You should save  your  music  periodically  during  its creation.  If you
  587. suddenly run out of space, the PC will wipe out anything saved only in memory.
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.                                                                       -Page 9-
  605.                          MUSIC2 program documentation
  606.  
  607.  
  608. Turning the sound on and off:
  609.      It is often  desirable  to not have each note played when displayed.  For
  610. example, in edit mode, playing each note can delay you greatly.
  611.      The playing  of  each  note  can  be  turned on or off through the volume
  612. on/off key ("V" or "v").  When pressed, a line appears at  the  bottom  of the
  613. screen saying whether the sound is on or off.  This switch  toggles;  pressing
  614. it again sets it back to normal.
  615.      Sound defaults to on.  It is automatically reset to on after compilation.
  616.  
  617. Getting out of the routine:
  618.      The normal way  to  leave the routine (as opposed to Break-ing out) is to
  619. press the Esc key.  You will be prompted to enter a character  if  you  really
  620. want out.  Otherwise, you will be returned to where you were.
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.                                                                      -Page 10-
  672.                          MUSIC2 program documentation
  673.  
  674.  
  675.                               EDITING FUNCTIONS
  676.  
  677.      Once you have  entered  some (or all) of your music, you may want to edit
  678. portions of it.  The MUSIC2 editor should fulfill most of  the  changes you'll
  679. want to make.  Since the stored music from this routine is kept  in  an  ASCII
  680. format, you can also edit it through EDLIN or whatever  as  long as you do not
  681. change the total number of notes stored in the file.
  682.      The MUSIC2 editor  functions  are  described  below.  If  you  select  to
  683. play/draw your music (SHIFT/F1) while you're in the Editor,  the  routine will
  684. dump you out of Edit.
  685.      When you're in the MUSIC2 editor, the word EDIT will appear at the bottom
  686. of the screen.
  687.  
  688. Moving the cursor:
  689.      A colored bar  always appears on the screen.  When you enter a note, that
  690. note is drawn over this bar and the bar moves to the right  so  you  can enter
  691. another note.  The bar will henceforth referred to as the "pointer".
  692.      In order to  revise  your  music,  it  is  necessary to move the pointer.
  693. Several functions are provided to do this.  Some  move  the  pointer one note,
  694. others move it to the beginning or end of the current screen,  others  move it
  695. to the prior or next screen, and finally others move it to  the  start  or the
  696. end of your music.  All of these functions are found  either  on  the  numeric
  697. keypad or else by using the CTRL key and then a numeric  keypad  key.  None of
  698. these functions can be called while you're in Insert mode (described below).
  699.      NOTE:  The "screen" here refers to one display of music.  Each screen can
  700. hold up to 20 notes or any combination of 20 notes, fore/back-ground, measure,
  701. etc settings.
  702.      NOTE:  If any  of these functions moves the pointer to a new screen, that
  703. screen will be drawn.  If volume (sound) is set on, that screen  will  also be
  704. audibly played for you.  Any music sub-definitions  on the screen will also be
  705. played out.  If you have long sub-definitions being played on the next screen,
  706. you might be advised to set the sound off.
  707.      WARNING:  If  you  have  Num  Lock set, you will not be able to use these
  708. functions.  Num Lock must be off.
  709.      WARNING:  Whenever  a  previous  screen is drawn, the hapless little beat
  710. counter which has been diligently trying to draw in measures where appropriate
  711. is  wiped  out.  To  reset  the  counter,  you  can either use  the  play/draw
  712. (SHIFT/F1)  or  go-to-start-of-music  (CTRL/Home)  functions.  Otherwise,  the
  713. measures will usually be incorrect whenever you enter Edit mode.
  714.    * Cursor right  key.  This key moves the pointer one note to the right.  If
  715. necessary, a new screen will be drawn to accommodate this.
  716.    * Cursor left  key.  This  key  moves the pointer one note to the left.  If
  717. necessary, a new screen will be drawn to accommodate this.  NOTE:  Do  not use
  718. the backspace key to do this.  A backspace is the same as a  CTRL/H  and  will
  719. result in the playing of a very high C note.
  720.    * Home.  This key moves the pointer to the beginning of the current screen.
  721.    * End.  This key moves the pointer to the end of the current screen.
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.                                                                      -Page 11-
  739.                          MUSIC2 program documentation
  740.  
  741.  
  742.    * Pg Up.  This key moves the pointer to the end of the screen just prior to
  743. the current one.  The new screen is displayed for you.
  744.    * Pg Dn.  This  key  moves  the  pointer  to  the  beginning  of the screen
  745. immediately following the current one.  The new screen is displayed for you.
  746.    * CTRL/Home.  This  key combination moves the pointer to the very beginning
  747. of the music.  A new screen is displayed for you.
  748.    * CTRL/End.  This  key combination moves the pointer to the very end of the
  749. music.  A  new screen is displayed for you.  If sound was  turned  off  before
  750. ("V" or "v"), it is restored.
  751.  
  752. Changing notes:
  753.      Once the pointer  has  been moved to the desired location, you can change
  754. the note at the pointer or insert notes before it.  Note that  the term "note"
  755. here includes special notes like tempo indicators, measure settings, and music
  756. fore/back-ground designations.  It also includes repeat indicators.
  757.      The note-changing functions are described individually below.
  758.      NOTE:  With  the  exception  of  the global change command, each of these
  759. note-change  functions  wipe  out  the  little  beat  counter which  has  been
  760. diligently  trying  to  draw  in  measures  where appropriate.  To  reset  the
  761. counter, you can either use the play/draw (SHIFT/F1)  or  go-to-start-of-music
  762. (CTRL/Home) functions.  Otherwise,  the  measures  will  usually  be incorrect
  763. whenever you enter Edit mode.
  764.      WARNING:  If  you  modify  a  repeat, delete the execution of that delete
  765. (x##) before deleting  the  repeat  begin [(##] or end [)] or the program will
  766. crash  when  it is asked to play the sub-definition.  If  you  re-compile  the
  767. music (SHIFT/F3) before trying to play it, the routine  automatically  deletes
  768. any )## or x## calls lacking correct (## definitions  as  well as deleting any
  769. x## call without both a proper (## and )## string.
  770.  
  771.    * Overstrike.  You can simply enter a note over an existing one and the new
  772. note will replace the existing one.  Once this is done,  the pointer will move
  773. one note to the left.  This will result in two notes being  displayed  on  the
  774. screen.  Only the newest note is retained.  To see the screen  cleaned up, you
  775. could do something like Pg Up and then Pg Dn.
  776.  
  777.    * Delete.  You  can  delete the character under the pointer by pressing the
  778. delete ("Del") key.  The character will be blotted  out  and  the pointer will
  779. move one note to the left. When you draw this note again, it will be displayed
  780. as an empty space until the music is compiled again  (see  below).  The  empty
  781. space is treated like a special note by the routine and can be overstruck with
  782. another character if desired.
  783.  
  784.    * Insert.  Insert  ("Ins")  allows  you  to  enter any number of characters
  785. which will be placed immediately before the note originally under the pointer.
  786. When activated, the word "INSERT" will be printed at the bottom of the screen.
  787. Initially,  inserted  characters  will  appear   to  overstrike  the  existing
  788. characters  until  the  pointer has to move to the next  screen.  To  see  the
  789. screen cleaned up, you will have to leave Insert mode and do something like Pg
  790. Up and then Pg Dn.
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.                                                                      -Page 12-
  806.                          MUSIC2 program documentation
  807.  
  808.  
  809.      While in Insert  mode,  you  cannot  do other editing functions, save the
  810. music, load other music, play and/or draw the music, or compile the music.
  811.      Insert mode  toggles.  Pressing  it  once  puts  you  into  Insert  mode.
  812. Pressing it again takes you out of Insert mode.
  813.      NOTE:  When you insert, the routine keeps track of what's where by adding
  814. 6 pointers in the array which  contains  your music.  These take up memory and
  815. slow down the execution of the program.  In order to clear up the music array,
  816. you have to compile your music (see below).  If you try to insert notes around
  817. an  area  in  which  you  previously inserted other notes,  the  routine  will
  818. automatically re-compile the music before it lets you insert anything.
  819.      WARNING:  Sometimes,  entering  Insert  mode  will  cause  the routine to
  820. forget where it is in your music.  If you find that  the  regular Pg Up and Pg
  821. Dn functions fail to work as expected, try CTRL/Pg Up or CTRL/Pg Dn.
  822.  
  823.    * Global changes. The most powerful and potentially dangerous MUSIC2 editor
  824. function is the global change command.  It allows you  to change all instances
  825. of a given note (such as a C) into something else (such  as  a  B-).  It  also
  826. allows  you  to  change  all  instances of one note duration  (such  as  music
  827. staccato) into another (such as music legato).
  828.      To begin the  global change command, enter "C" or "c".  You will be asked
  829. for  the note or setting your want to change from.  You  may  enter  something
  830. like "C", "B-", "ms", or "mn" here.  You will then be asked what to change the
  831. note or setting to.  You can change it to a similar type  of  character (notes
  832. can change into other notes, one note duration can change into another).  Then
  833. the  routine  changes all instances of that note or setting in  the  file  and
  834. tells you how many notes it actually changed.
  835.      WARNING:  Just in case you do something wrong, you should always (re)save
  836. your music before trying a global change.
  837.  
  838. Compiling:
  839.      It has already  been  stated  that  when  you  delete  a  note, the space
  840. originally reserved for that note remains.  Also, when you  insert one or more
  841. notes,  6  special indexing notes are created.  Thus whenever  you  insert  or
  842. delete in this routine, wasted space is created and the routine has to take up
  843. time dealing with the deleted notes and branching.  To clean up the space, you
  844. must compile the music.
  845.      In order to compile the music, enter SHIFT/F3.  A line on the screen will
  846. show   you   how  many  elements  there  were  in  the  music  array  (roughly
  847. corresponding to the number of notes) before compilation  and then you will be
  848. told how many elements there are after.
  849.      After compilation, you will be moved to the end of your
  850. music (a CTRL/End is performed) and, if previously turned  off,  sound ("V" or
  851. "v") is restored.
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.                                                                      -Page 13-
  873.                          MUSIC2 program documentation
  874.  
  875.  
  876.                           THE MUSIC2 SCREEN DISPLAY
  877.  
  878.      Except for some  special  menus, the MUSIC2 screen display remains fairly
  879. constant.  The screen consists of a maximum of 12  lines  of text, 12 lines of
  880. music,  and 1 blank line.  A fully utilized screen is shown  below.  You  will
  881. never see a screen exactly like this one but it gives you  an  idea  of what's
  882. possible.
  883.    ---rule--- 12345678 1 2345678 2 2345678 3 2345678 4 ---rule---
  884.      lines:                                              lines:
  885.        1      Tempo: t120        Note duration: mn          1
  886.        2      Note length:  4    Fore/back-ground: mb       2
  887.        3                                                    3
  888.        4                                                    4
  889.        5      t120                                          5
  890.        6         mb                                         6
  891.        7-18              (bass and treble clefs)            7-18
  892.        19                                                   19
  893.        20            (0    0)      (1    1)                 20
  894.        21                     x0             x0x1           21
  895.        22       INSERT Compiling Space=23456    EDIT        22
  896.        23     121^140  Elements (notes):1003 Sound off      23
  897.        24     TITLE:
  898.                       Homeward Bound' by Paul Simon         24
  899.        25                        *                          25
  900.    ---rule--- 12345678 1 2345678 2 2345678 3 2345678 4 ---rule---
  901.      The first four  lines of the display will sometimes offer prompts or give
  902. error  messages.  More  normally,  they  will  show the  default  tempo,  note
  903. duration, note length, and fore/back-ground.
  904.      Line 5 shows  that  the  tempo was set.  This line appears only where the
  905. tempo is initially set or when it is changed.
  906.      Line 6 shows  that the music fore/back-ground was set,  This line appears
  907. only when ground is initially set or when it is changed.
  908.      Line 20 shows the beginning and end of each musical sub-definition.
  909.      Line 21 shows when a sub-definition is called for.
  910.      Line 22 gives  an  often-changing  status  line.  "INSERT"  appears  when
  911. you're  in  Insert  mode.  "EDIT"  appears  when  you're  in the Editor  mode.
  912. "Compiling"  indicates   that  the  music  is  being  compiled.  The  "Space="
  913. reference appears when the routine is trying to consolidate  internal-PC space
  914. (through the FRE("a") command).
  915.      Line 23 shows  what portion of the music array is currently being viewed.
  916. This notice is given only when you're in the  Editor  mode  and have chosen to
  917. move the pointer to a prior screen.  The "Elements (notes)"  reference appears
  918. during  compiling  and  should  appear  twice, the second  time  showing  some
  919. reduction in the number of notes.  "Sound on" or "Sound off"  appears when you
  920. pick the sound on/off option and disappears whenever you pick another screen.
  921.      Line 24 gives the title of the composition you're working on.
  922.      Line 25 has  a  flashing  note  sign  which indicates that the routine is
  923. patiently waiting for you to do something.
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.                                                                      -Page 14-
  941.                          MUSIC2 program documentation
  942.  
  943.  
  944.                            HOW THE MUSIC IS STORED
  945.  
  946.      In case you need to change the stored music files, data is stored in this
  947. program in the following manner:
  948.   *  The first record  has  the variables DATE$,TIME$,TITLE$,CUREND, MAXNOTES,
  949. and  MAXSUBDEF  where  CUREND=how  many notes are in  music,  MAXNOTES=maximum
  950. number of notes allowed (1000), and MAXSUBDEF= maximum number  of  repeats  in
  951. the piece (10).
  952.   *  The second and  the  next  CUREND records contain strings which determine
  953. what's played.
  954.      For normal notes  or  rests  (pauses), each string begins with the letter
  955. "m".  Their format is as follows:
  956. --123456789--cols
  957.   mno3B-. 4
  958. where columns:
  959. 1-2 : "mn" (music normal), "ml" (music legato), or "ms" (music staccato)
  960. 3-4 : octave (o0-o6--only o1-o5 exist in routine)
  961.   5 : note ("A"-"G" or "P" [pause])
  962.   6 : "-" if flat note, blank otherwise
  963.   7 : "." if dotted note, blank otherwise
  964. 8-9 : length of the note (" 1", " 2", " 4", " 8", "16")
  965.      This format  is  pretty  much standard for the PLAY command so any string
  966. which begins with "m" can be played directly.
  967.      Non-note/rest  strings  are  called  "special  notes" and begin with "x".
  968. None can be played directly although the  x-m and x-t strings can be played by
  969. specifying MID$(P$(i),3).  The format for special notes is as follows:
  970.       x-b#/#  set time (e.g. 4/4 or 2/4) (default=4/4)
  971.       x-mb    play music in background (default, vs. x-mf)
  972.       x-mf    play music in foreground
  973.       x-t###  set music tempo as ### (default=t120)
  974.       x-(##   begin repeat ## (routine figures which one)
  975.       x-)##   end repeat ## (routine figures which one)
  976.       x-x##   play repeat segment numbered ##
  977.       x-*#### goto string element ####,
  978.               element referred to has corresponding x-*#### back here
  979.       (null)  deleted note
  980. When the music is compiled (SHIFT/F3), null  strings  are  deleted,  all  goto
  981. references (x-*####) are eliminated as the array is reconstructed,  and all x-
  982. (##, x-)##, and x-x## strings are re-computed.
  983.      The x-(##, x-)##,  and  x-x##  commands  were used instead of the PLAY "X
  984. string" commands in order to allow unlimited lengths for the  repeats,  and to
  985. allow easier definitions of the strings to be repeated.
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.                                                                      -Page 15-
  1008.                          MUSIC2 program documentation
  1009.  
  1010.  
  1011.               CHANGES BETWEEN ORIGINAL MUSIC PACKAGE AND MUSIC2
  1012.  
  1013.      * All of the  features  marked  with an asterisk in the table of contents
  1014. are new to MUSIC2.  Most of the other functions are  now  invoked by different
  1015. keystrokes.
  1016.      * Music is now  entered  as  if  the  PC  has  a (somewhat limited) piano
  1017. keyboard.  Before, you had to move the cursor up and down the clefs.
  1018.      * You can no  longer designate keys.  Before, you could fill in flats and
  1019. sharps  in the margins and all notes would become flatted or  sharped  as  per
  1020. your  instructions.  Since you enter sharps and flats directly,  that  feature
  1021. became unnecessary.
  1022.      * The range of playable notes has increased by several octaves.
  1023.      * Measures are  drawn  as  guides  now.  Previously,  measures  had to be
  1024. obeyed (you couldn't fit a quarter note in a measure that had room for only an
  1025. eighth note).
  1026.      * Default note lengths can be specified.
  1027.      * The routine, now compiled, is much quicker to run.
  1028.      * Error recovery has been improved.
  1029.      * Instructions and documentation have been vastly expanded.
  1030.      * The files are stored differently now so you won't be able to use a data
  1031. file created by the old version of the package.
  1032.