Introduction to Music Typesetting
         --------------------------------------

The purpose of this file is to provide an overview of the
documentation files in this directory.

If you are reading this documentation for the first time, I
recommend that you start by reading the high level description
of how our data entry works, how things are stored, and how
musical editions are made.  This information is captured in
the file edmake.dm.  At first, it may seem that you are
encountering more detail than you really need, but if you
stay with the idea that you are getting an overview, you will
find that the information given there forms the basis for
all of the other documentation in this directory.

Don't underestimate the value of edmake.dm.  Even if you have
read it several times, you may have forgotten some important
fact that is explained there and nowhere else.  In my experience,
it is the simple facts that are often overlooked and omitted
from documentation.  Why?  Because to the writer these facts
are already so self-evident that he/she forgets to include them.

Once a set of stage2 files is created, the process of typesetting
music consists of running the program sequece autoset.z -->
mskpage.z --> dskpage.z  multiple times:  first to check the data
and correct errors, and later to make editions.  Each of these
programs has its own documentation file in this directory:
run-auto.dm, run-mskp.dm, and run-dksp.dm.  In addition,
there is a file run-pskp.dm which explains how to print music
from page specific i-files.

There are two programs for edited music on the screen.  The
first, s2ed.z, is used only for editing stage2 files.  It is
a complicated program to run, but if used properly, it can
save a lot of time both with primary data entry of things
like slurs, articulations, dynamics, figured harmonies, and
with editing the placement of these things (i.e., adding
print suggestions).  The second program, eskpage.z, is used
in the final editing process when producing production quality
scores and parts.  This program allows the user to re-position
almost all elements of music on a staff line, as well as to
re-position staff lines and staff systems.  The program cannot
as yet move music between staff lines.  Running eskpage.z is
an essential step in creating high quality musical output,
but it does have the drawback that the finished product is
"orphaned" from the original data.  For this reason, eskpage.z
should only be used as a final "clean-up" step.

Documention for these two programs are contained in the
files s2ed.dm and eskpage.dm.

When it comes time to make a musical edition from the files in the
output directory, you will need to know how to run the vspace.z
program and how to build the scform file that it depends on to do
its work.  This documentation is contained in the file
run-vspc.dm.  Developing the formatting instructions for the
scform file would be a daunting task without the assistance of the
program vskpage.z.  This documentation is contained in the file
run-vskp.dm.

It is possible to convert page specific i-file data to SCORE .pmx
data, on one extra condition.  SCORE .pmx files require some
information that IS in our stage2 representation but IS NOT
passed on in our normal autoset.z --> mskpage.z --> dskpage.z
sequence.  In order to pass on this extra information, you must
use instead the sequence autoscr.z --> spaging.z --> scorecon.z.
The output of this process is a set of .pmx files in the same
pages sub_directory that contains the i-files.  Furthermove,
autoscr.z will only operate on the group scrcon, and only in
notesize 14, so you would need to add this group to each of the
stage2 files you are converting.  SCORE conversion is beyond the
scope of this documentation, but you should at least know that it
can be done.

This documentation has mentioned at least 10 different programs,
but there are actually fewer than that.  dskpage.z and pskpage.z
actually have the same zbex source code (with minor varients
being controlled by conditional compile statements).  The
mprogs.dm explains the relationship among all of the music
typesetting programs mentioned here, as well as some not
mentioned.