DOCUMENTATION FOR THE S2ED PROGRAM
           

                     November 21, 1994
         With additions from  11-23-94 and 01-10-95
                      Updated 04/29/09

     The purpose of the s2ed.z program is to facilitate stage2
data entry.  While the program has many features, it is not
a complete stage2 editor.  For those actions which the program
cannot handle, the Dmuse page editor is still the best way to
edit stage2 files.

     In the beginning, stage2 files are generated from stage1
files by the begin.z program.  How well this program handles
such things as beaming depends on the parameters given to it
at run time.  For music with complicated beaming, it is worth
looking at the output (initial stage2) to see how accurately
the beaming was handled.  When the beaming is not done correctly,
it is sometimes best to run the begin.z program again with different
parameters, rather than trying to correct the beaming in the
stage2 file.

     Before running the s2ed.z program, there are several things
which need to be done to the stage2 files that come from begin.z.
Think of these tasks as "preprocessing" before running s2ed.z.
All files for a particular movement should be processed before
running s2ed.z.

1. The source should be verified.  Sometimes the source for
   stage2 is not the same as the source for stage1.

2. The group memberships, score and sound, need to added.
   The group data may be eliminated or retained.

3. If there is pickup, extra rests in measure 0 need to be
   deleted.

4. If there are any double (mheavy) bars, any first (or second)
   endings, any clef changes, key changes, time changes, these
   need to be added using the Dmuse editor.  The s2ed.z program
   cannot handle these things.

5. If measure numbers are off, the best way to correct this
   is to use the qwd program; do a search for the string
   "measure"; highlight the measure numbers and shift them;
   then type <Enter> for all altered lines and restore the
   file.  Be careful that you don't have another version of
   the file in another window.

6. Any extra rests at the end should be deleted.

7. In some cases it is easier to correct beams using the
   Dmuse editor.  This will be true when the same type
   of change needs to be made several times.  Also, the
   Dmuse editor may be the best way to add tuple designators,

                      *
   since the pattern:   can be stored in the
                      !

   box buffer and then reproduced many times.  The s2ed.z program
   can alter beams and can add tuples, but it must do this
   on a case by case basis.

8. When preprocessing is done, it is highly recommended that
   you DO NOT leave any of the stage2 files in the Dmuse windows.
   The reason is that the s2ed.z program will be modifying these
   files, and if you are not careful, you could end up restoring
   one of the windows and OVERWRITING the results of your s2ed.z
   edit session.  (I have actually done this more than once!)


     It is intended that the s2ed.z program be somewhat self-
documenting.  However, this feature does not work perfectly,
so some explanation is required here.

     The program operates in a set of "states," and the
results of the keystrokes you make depend on which state you
are in.  At the moment, the states are not explicitly labeled;
but are somewhat implicit.  This is a weakness in the program.

     To begin with, the state you are in depends on (1) what
kind of object the blue cursor is pointing at, and (2) which
line in the source file is highlighted in RED.  For example,
if the blue cursor points at a measure line, and the
highlighted source line is a measure type record, there are
no valid editing keystrokes.  The only keystrokes which will
do anything are those that move the cursor or change the
RED highlight.  (Actually, the 'g' keystroke also does
something; namely, add a grace note before the measure line.)

     The unmodified cursor keys are used to move the blue
cursor and change the RED highlight in the source.  UP and
DOWN cursor will change the RED highlight, and LEFT and
RIGHT cursor will move the blue cursor (i.e., move up and
down in the i-file, the current record of which is displayed
in the middle right-hand part of the screen).

     LEFT and RIGHT movement can be by object (mode j) or
by i-file line (mode x).  Mode x is seldom used.  When
pointing to a note, shift-UP and shift-DOWN can be used
to make the blue cursor point to sub-objects of the note
which are the result of codes in columns 32 to 40.  The
principal use of this is to get the blue cursor to point
to a letter dynamic, in the case where the user desires to
move this letter up or down.

     The self-documenting "help" menus appear in the lower
right part of the screen.  Sometimes these menus disappear
without warning.  Don't be alarmed, but try to remember what
your options are anyway.  Moving the cursor will usually bring
the help menu back.

     If your blue cursor is pointing at a note, and you type
a code for columns 32 to 40, this will put you in a special
state for entering this kind of data.  You will remain in
this state until you move the cursor, type <F2>, or type
<Enter>.  Likewise, if you type "b" to enter the beam and
stem editing state, you will remain in this state until
you type one of the actions above.  The point is that there
are certain sub-states to note entry, for which, once you
enter them, only certain strokes can get you out of them.
This may seem confusing at first, especially when you type
things and nothing happens, but you will get used to remembering
the state you are in.

     When you enter a wedge, a set of dashes, or some other
musical direction such as "cresc.", this is almost always
drawn at the wrong height, and you will probably want to move
it.  The way to do this is to get the source line in question
to be highlighted in RED and then to use the alt-UP, alt-DOWN,
shift-alt-UP, or shift-alt-DOWN keystrokes.  In the case
where there are two types of musical directions specified
in one source line (i.e., both columns 17 and 18 are used),
you will first need to specify which column you want to
affect.  If you want to effect both, the program allows you
to do this.

     One of the things you need to be able to do with an
editor is to "undo" mistakes.  This editor does not have a
general undo command.  You may, however, undo certain actions
in the following ways:

1. To undo a code in columns 32 to 40, type that code
   again.  You may have to type the letter "a" first in
   order to get access to all the codes in that mode.

2. In the case of letter dynamics, the technique described
   above does not work.  Why?  Because if you type a "p"
   for "piano" and then you type "p" again, you get a
   "pp" for "pianissimo".  To eliminate letter dynamic
   codes from columns 32 to 40, type "<".  This will
   elminimate all instances of the letters p,f,m,Z and R.
   You can then begin entering letter dynamics again.

3. To erase a slur that has been completed, simply type
   the relevant "slur-start" character in the same source
   line where the slur occurs.  To eliminate a slur that
   has not been completed, just end the slur in the same
   record in which it was started.

4. To get rid of all added records beyond the location
   of the RED highlight, simply type <F4>.  Be careful; this
   feature has a draw-back.  It will not only eliminate
   "*" records, print suggestions and grace notes, but it
   will also eliminate records resulting from split notes
   and split rests.   This brings up a major point:

   There are certain actions which cannot be undone.  You
   will simply have to write down where the errors are and
   correct them in the file after you have finished with the
   S2ED session.

5. You may, if you wish, type <esc> to exit s2ed.z.  You will
   be given the option of saving the editing you have done
   up to this point.  After fixing some mistake, you may
   then restart the program.  The <F3> button allows you to
   skip forward to any measure in the file, so you can
   resume your work where you left off.  Sometimes a mistake
   has been made which makes this procedure mandatory.

6. There are commands for splitting and combining notes.  If
   you split a note accidentally, you can probably combine
   the two parts into one again, without any loss of data.

7. At any time, it is possible to change the pitch of a note,
   to move a musical direction, to move a rest, to add or
   delete beams, or to add or delete ties.  It is not possible,
   however, to edit directly the contents of a source line.
   You must do this indirectly through the commands available
   in s2ed.z.


     The <F2> key plays an important role in s2ed.z.  Pressing
this key causes the music display to be redrawn.  Normally
input keystrokes do not result in redrawing the display
because of the extra time this requires.  You need to keep
mental track of what you have entered, and occasionally press
<F2> to see the results of what you have done.  I often wait
until I have finished inputting the data for an entire measure
before pressing <F2>.  There are, however, certain times when
it is a good idea to press <F2> to make sure you like what
you have done:

1. After entering grace notes (and before beaming them).

2. After rebeaming a set of notes

3. After entering a musical direction

4. After splitting or combining notes

     Special care needs to be taken in pressing <F2> after
the beaming of notes has been changed.  If you beam notes
together which have different stem directions, you might
cause the display portion of the program to fail.  This will
lead to a general failure.  In the case of a general failure,
you are given the chance to save what you have done, but it
is a nuisance to have to restart s2ed.z.  This brings up an
inportant point, namely:

   The s2ed program is a combination of three programs,
   autoset, mskpage, and dskpage.  It is easily possible
   to create a situation which would cause any one of
   these programs to fail (such as the stem up/down
   problem described above).  You need to be aware that
   you can cause such a failure and to be on the lookout
   to avoid it.  In particular, don't press <F2> if
   you see a situation in the source file that looks
   incorrect; try to fix the source first.

     If you are worried that s2ed.z might fail, or if you are
simply nervous about losing the results of your work at any
point in time, simply press shift-<F2>.  This will save
the current state of your editing in a file called s2save.

     You may move backward in a file by typing <BACKSPACE>.
<ENTER> moves you forward in the file.  If a super-object
is started, but not terminated when you press <F2> or
<ENTER>, a new measure will be displayed but the old measure
will still be there.  In general, you should complete all
outstanding super-objects before doing other editing.  It
is possible, if you edit beyond a super-object, that when
you press <F2>, measures will disappear and your blue
curror may even point beyond the new display.  In this
case, it is a good idea to move the cursor backward to
a point where it is inside the display again.

Certain available keystrokes:

<HOME>        = move blue cursor to left end of display
<END>         = move blue cursor to right end of display
<PAGE UP>     = move blue cursor 10 units to the left
<PAGE DOWN>   = move blue cursor 10 units to the right
shift-<UP>    = move cursor up sub-object list (col. 32-40 codes only)
shift-<DOWN>  = move cursor down sub-object list (col. 32-40 codes only)
alt-<UP>       \
shift-alt-<UP> / move object up; raise pitch.
alt-<DOWN>       \
shift-alt-<DOWN> / move object down; lower pitch.

   alt-UP/DOWN moves pitches one accidental at a time
   shift-alt-UP/DOWN move pitches one letter name at a time.

g = add a grace note.  You must specify a type.
      4 = 32nd, 5 = 16th, etc. 0 = slash 8th.
      If you bump "g" by mistake, enter a number
      and then type <esc> to undo the whole thing.

/ = split a note or rest
| = combine note or rest
% = toggle between note and rest

<F2>        = redraw display
shift-<F2>  = save current state of editing (no other action)
<F3>        = jump ahead to measure number X (jump back also works)
<F4>        = delete all added records below current RED highlight
                in source file


     If you want to enter a wedge, there are normally several
key strokes required.  For example, to start an opening wedge,
you would normally have to type to the following keystrokes:

      8 = add a "*" type record
      e = start wedge      (i.e., put "E" in column 17)
<space> = no second letter (i.e., column 18 is empty)
<space> = no division offset (i.e., columns 6-8 are empty)
      0 = this end of the wedge is a point
<space> = terminates entry

To end this wedge you would have to type:

      8 = add a "*" type record
      f = stop wedge       (i.e., put "F" in column 17)
<space> = no second letter (i.e., column 18 is empty)
<space> = no division offset (i.e., columns 6-8 are empty)
      1 = \(together)
      5 = /this end of the wedge is has spread of 1.5 staff space
<space> = terminates entry

This is a total of 15 keystrokes.  We have devised a short
cut for this situation.  To start an opening wedge, type

      8 = add a "*" type record
      e = start wedge      (i.e., put "E" in column 17)
      < = This is an opening wedge.

To end an opening wedge, type

      8 = add a "*" type record
      f = stop wedge      (i.e., put "F" in column 17)
      < = This is an opening wedge.

This is a total of 6 key strokes.  The same shortcut
can be used for closing wedges; simply substitute the
">" character for the "<" character.  This trick can be
used even if one end of the wedge has a direction attached
to it.  In the following case:

            <opening wedge> ff

You can start the wedge by typing "8e<", but you must
close the wedge by typing "8gf 15 ff<Enter>"

    All letter dynamics attached to notes will result in
a print suggestion being added.  Most of the time, this
will put the dynamic in a proper position.  You are free,
however, to edit this position up or down.  Simply move
the blue cursor to note and use the shift-<DOWN> to move
the blue cursor to the letter dynamic.  Then use alt-UP,
shift-alt-UP, alt-DOWN, or shift-alt-DOWN to change the
suggestion.  You will have to press <F2> to see the
results of your work.  Eventually you will develop a
sense for how changes in the print suggestion will change
the position of the letter.  The shift-alt combination moves
things up or down by 5 units.

Other facts:

1. Beams can extend over rests, but not over measure lines

2. S2ED can be used to add octave transpositions.  "V" moves
   printed notes down (i.e., creates an 8va up transposition);
   "U" move notes up (i.e., creates an 8va down transposition).

3. Care should be taken when adding tuples using "!" and "*".
   There is no safety provision in the program to make sure a
   tuple has been properly started or terminated.  Pushing
   <F2> without terminating a tuple could cause a general failure
   in the program.

4. In stem up situations, we recommend that slurs and staccato
   marks be added before letter dynamics.  This will help s2ed.z
   do a better job in locating the letters.

5. Don't worry about whether s2ed.z prints sf, sfz, or fz for
   the Z-sforzando.  This can be changed by a flag that can be
   set in autoset at the time music is compiled for printing.

6. In some cases, s2ed.z does not display "long" or "high"
   slurs.  Don't worry about this; the slurs are still there
   and will appear when dskpage or pskpage is run.

7. Grace notes are added at the pitch of the nearest "real"
   note.  You can alter the pitch either at entry time or
   later using the (shift)-alt-UP/DOWN keys.  To position
   grace notes at the end of a measure, make the blue cursor
   point to the measure line.

8. There is no way to change the tuple numbers with S2ED.  If
   you want 3's changed to 6's, you must use the Dmuse editor.
   This should be done as part of the preprocessing.

9. s2ed.z provides the facility of splitting and combining
   notes and rests, and the facility for toggling a record
   between note and rest.  In some cases, this will result
   in the loss of information.  You may have to restore
   this information in a "post-editing session" with the
   TenX ASCII editor.

10. To place a staccato properly (above or below) on a chord,
    you need to put the dot "." on the record for the nearest
    note.  In some cases, this means putting the dot on a
    "secondary" note of a chord.  You must use the UP/DOWN
    keystrokes to move the RED highlight to the correct record
    in the source file.  Letter dynamics, on the other hand,
    must be attached to the "primary" note of the chord.

11. You can change the orientation of a slur or tie by adding
    a print suggestion below the record where the tie/slur
    begins.  You will need to know the column number, which
    is not given explicitly.  It is helpful to know that
    slur and tie characters may be found in columns 32 to 40,
    whereas all other notation characters will appear only in
    columns 33 to 40.

More Facts:     11-23-94

1.  You can scroll the music display right or left using
    ctrl-LEFT and ctrl-RIGHT.

2.  To enter a "Z" (sforzando), use the unshifted "z".  This
    will save time.

3.  To enter a "+" in column 33..40 (cautionary accidental),
    you may type either "+" or "="(unshifted +).  To enter
    the legato-dot (which is the "=" character in stage2 code),
    you must type "D".  This code does not occur very often,
    whereas the "+" is quite common.

4.  You may create up to 8 macros "on-the-fly".  These will be
    stored under the eight keystrokes F5..F12.  Macros are entered
    "on-the-fly".  This means you can create them only as part of
    the editing process.  Here is how it is done:

    First, observe that a series of upcoming keystrokes may
    have to be repeated several times.  Before starting these
    keystrokes, push shift-<Fx> function key (x = 5 to 12).
    This will "silently" load each successive keystroke into a
    macro buffer for the designated function key (5 to 12).
    Normal editing will also occur during this process (hence
    the adverb "silently").  After you have typed the last
    keystroke that you want in the buffer, push ctrl-<Fx>
    (x = 5 to 12).  This will stop the loading of the buffer.
    If you forget to push ctrl-<Fx> for a buffer that is
    loading, it will eventually exceed the maximum size
    (100 keystrokes) and will be cleared entirely.  If you push
    ctrl-<Fx> (x = 5 to 12) for a macro buffer that is not
    currently loading, the buffer in question will be cleared.

    To retrieve the set of strokes in a particular macro
    buffer, simply press the appropriate function key (F5..F12).

    Caution must be used with this feature.  The program makes
    no attempt to validate the appropriateness of the keystrokes
    contain in a macro.


     Finally, be prepared for surprises.  s2ed.z is a very large
and complicated program, and certainly has many undiscovered
bugs.  But I find it a joy to use.  It seems to be reasonably
efficient, and certainly produces results which are more accurate
and more pleasing to look at than the old stage2 entry process
using the Dmuse editor only.  Hopefully, over time, the bugs can
be eliminated and more "short-cuts" can be found to further speed
up the entry process.


More Facts:     01-10-95

1.  I have added the capability to enter figures.  Figures may be
    added to any regular note (not to rests).  To start entering
    figures, type "f".  Note, this means that "f" will no longer
    give you a forte.   To get a forte, you must first type "a"
    and then "f".

    To enter a figure over a rest, you must either enter the figure
    with the note before and use the offset field to put it over
    the rest, or you must enter it by hand using the TenX editor.

    There is no way to cancel a figure after you have entered it,
    but you can use the <F4> key to remove ALL new records after
    the position of the cursor.  This works fine, but caution
    is advised.

    The figure "#" can be entered either with a "#" or an "s".
    The "s" saves you the trouble of using the shift key.

    Multiple figures in a record MUST be separated by a space,
    i.e., the SPACE bar.  If you don't do this, e.g., you type
    "65" instead of "6 5", and then push <F2> to see the figure,
    the program will fail.  You will be given a chance to save
    your work, but restarting the program is a nuisance.

    The position of figures can be moved up or down after they
    have been displayed.  Put the cursor on the figure record
    and use the alt-UP/DOWN keys or shift-alt-UP/DOWN keys.
    One exception, however, is that figures with offsets
    cannot be moved.  This is not a problem with the Stage 2
    representation, but rather a logical problem in the
    autoset program (I think this is fixed now [06-28-95]).

    A reminder about offsets: If there is more than one group
    of figures (horizontally) under a note, the first group
    will appear under the note, and each successive group will
    appear offset horizontally by the amount of the offset field
    (columns 6-8) OF THE PREVIOUS FIGURE.  Put another way, the
    offset field specifies how much the figure-division-counter
    is advanced AFTER the figure is printed.  The reason this
    might confuse a person at first is that the s2ed.z program
    requires that the offset be entered before the figures in
    a group.  This means that you need to be thinking about
    how far to offset the SECOND group of figures before you
    actually enter the FIRST group of figures, etc.

2.  In a earlier version of the program, a $ record in the middle
    or at the end of a measure caused the s2ed.z program to skip
    (not display) all notes in the measure before the $ record.
    This meant that you could neither see nor edit these notes.
    I have fixed this problem somewhat, but occasionally you
    may notice things left out of the display.  Don't worry about
    it; just enter what you can.

    If a $ record causes a clef change in the middle of a
    measure, and you use <F2> to redisplay notes, you may see
    the notes before the clef change displayed in the wrong
    clef.  If this bothers you, just back up a few measures
    push <F2> and then move forward again.  Caution: If
    displaying in the wrong clef causes notes to appear too
    high or too low (as in the case of treble cues for a bass
    part) the s2ed.z program could fail.  Be alert!


3.  A version of s2ed.z has been created that can run on
    640 x 480 screens (portables).  I have given this program
    the name ss2ed.z.