\documentstyle[11pt,twoside,refman]{article}
\def\version{~1.1}
\def\musictex{Music\TeX{}~}
\def\miditex{MIDI2\TeX{}~}
\pagestyle{myheadings}
\markboth{\miditex \version}{\miditex \version}

\def\whole{\setlength{\unitlength}{1em}
           \begin{picture}(1,1.5)
             \put(0,0){\mus \symbol{35}}
           \end{picture}
          }
\def\half{\setlength{\unitlength}{1em}
           \begin{picture}(1,1.5)
             \put(0,0){\mus \symbol{34}}
             \put(0.5,0){\line(0,1){1}}
           \end{picture}
          }
\def\quart{\setlength{\unitlength}{1em}
           \begin{picture}(1,1.5)
             \put(0,0){\mus \symbol{33}}
             \put(0.5,0){\line(0,1){1}}
           \end{picture}
          }
\def\eighth{\setlength{\unitlength}{1em}
           \begin{picture}(1,1.5)
             \put(0,0){\mus \symbol{33}}
             \put(0.5,0){\line(0,1){1}}
             \put(0.5,0){\mus \symbol{40}}
           \end{picture}
          }
\def\sixteenth{\setlength{\unitlength}{1em}
           \begin{picture}(1,1.5)
             \put(0,0){\mus \symbol{33}}
             \put(0.5,0){\line(0,1){1}}
             \put(0.5,0){\mus \symbol{41}}
           \end{picture}
          }
\def\thirdysecondth{\setlength{\unitlength}{1em}
           \begin{picture}(1,1.5)
             \put(0,0){\mus \symbol{33}}
             \put(0.5,0){\line(0,1){1}}
             \put(0.5,0){\mus \symbol{42}}
           \end{picture}
          }
\def\sixtyfourth{\setlength{\unitlength}{1em}
           \begin{picture}(1,1.5)
             \put(0,0){\mus \symbol{33}}
             \put(0.5,0){\line(0,1){1}}
             \put(0.5,0){\mus \symbol{43}}
           \end{picture}
          }

\begin{document}
\bibliographystyle{plain}
\newfont{\mus}{musicn20\magstep1}
\begin{titlepage}
   \begin{maxipage}
   \vspace*{30mm}
       \begin{center}
       \Huge
       \bf
       \miditex\\ %[2\baselineskip]
        Version \version\\[2\baselineskip]
       \large
       a MIDI to \musictex translation program\\
       %\vspace{5mm}
       \normalsize by\\[2\baselineskip]
       \Large
       H.J.P. Kuykens\\
       %\vspace{5mm}
       \normalsize
       20-7-'92\\
       \vspace*{50mm}
       \input midi2tex.pic
       \vspace*{30mm}
       \end{center}
   \end{maxipage}
\end{titlepage}

\newpage
\tableofcontents
\newpage

\section{Introduction}
\label{introduction}
\musictex{}  is an extension of \TeX{} for typesetting polyphonic
music written by Daniel Taupin.
I was surprised by the excellent result of the
output.  However, the coding of a music piece with \musictex{} is quite
laborious and difficult.
The first thing which came to my mind was that certainly there
must  be people out there who developed software which could translate
MIDI files into \musictex{} code. I placed requests on the international NEWS
system. However, I did not get any response. That made me decide to
develop such software myself.  \miditex{} is the result.  I hope that it
can  be useful for other people who,  just like me, are involved
in MIDI but do not have a good
music type setting system and know how to get on with \TeX.

If you are not familiar with \TeX{} at all I would recommend to
find another software package to do musical typesetting. Setting up \TeX{} and
\musictex{} on your machine and mastering it is an awesome job  which gobbles up
a lot of your time and disk space. But, once you master it....

\section{How to read this manual}
\label{howtoread}
If you are a regular user of \miditex then I suggest to switch immediately
to section \ref{versions} to see what changes have been made since the last
release and where to find more info about it.

If you are familiar with \musictex but not with \miditex I suggest to
read the complete manual. If you want a quick start than switch to
section \ref{description} which describes all the command line options.

In this manual two types of attention marks can be found in the left margin.\\
The one shown left \attention of this sentence asks your attention because
there is some important information in that sentence.\\
The other one, \seealso{section \ref{howtoread}} shown left of this sentence,
refers to another section in this
manual which contains information related to the subject in that sentence.

\section{What it does do}
\label{whatdo}
\miditex{}  inputs  a  type  1  MIDI file
%\footnote{See section \ref{bugs} for info about type 0 files}
\seealso{section \ref{bugs}}
and translates this into source code for  \musictex.
Several features of the program are listed below:
\begin{itemize}
\item Maximum of 16 tracks translated
\item Vertical alignment of notes in staffs
\item Generation of beams and slurs
\item Text in MIDI file supported
\item Changes in signature supported
\item Quantizing
\item Insertion of rests
\item Skipping of tracks
\item Combine several tracks into one instrument
\item Selection of either violin, bass or alto clef for any track
\item Reordering of tracks
\item Changing vertical alignment
\item Changing size of the music document
\item Generate flats and sharps while taking into account the general signature
\end{itemize}
 
Most importantly, \miditex{} will do the massive job of coding note events 
in the MIDI file into  \musictex{} notes. It speeds up the lay-out
process of your sheet music tremendously.
 After the translation process you
can manually  adapt  the  \musictex{} source code to meet the 
desired lay out. 

\section{What it does not do}
\label{whatnotdo}

\miditex{} is not yet a very smart program. The vertical alignment of
notes is not optimal.  Complicated chord pieces
are translated poorly.
In general, additional editing of the \musictex{} code after
the translation process is required to refine the output.

\section{What is needed?}
\label{needed}
Software versions are available for the Atari ST and IBM PC
compatibles. Both versions are functionally identical. 
The Atari ST version
includes a separate GEM based shell. The program itself
needs approximately 90 kB and 10 kB for each track in the MIDI file to run
properly.

Of course you need \musictex. \musictex{} consists of several \TeX{}
macro files and meta font files with music font definitions.
The complete package is available on several bulletin boards and
FTP sites. Recently I downloaded version 4.57 from rsovax.ups.circe.fr
(in the directory {\tt /TeX/musictex}).
You need to acquire some knowledge about \musictex{} if you want
to edit the source code after the translation process. 

Further you need \TeX. At the moment several good public domain
packages  are available. For the PC EM\TeX{} is a good one. 
On the Atari ST
I use \TeX{} 3.1 by Christoph Strunk which I find pleasant to work
with. These packages are also available at FTP sites, 
PD services or bulletin boards.

Last but not least use of this program is only of any use if you
are working with MIDI files. A MIDI file contains musical information
and is a standardized file format which enables to exchange music pieces
between  different software packages.
Although many MIDI sequencer software packages have
their own file format, most of them also support standard MIDI
files.

This manual assumes that you have some knowledge of \TeX{} and
\musictex. If you are puzzled by any of the explanations in this manual
see if reading the manuals of these packages can help you out.

\section{Installation of the software}
The PC version of the package comes in a self extracting ZIP file.
Copy MIDI2TEX.EXE to a target directory and enter the name on the 
DOS prompt.  
The ST version comes in ARC'ed format ( V. 3.5). 
Copy the file MIDI2TEX.ARC
to your (hard) disk and de-ARC it using any de-arc program.
The example archive included in the distribution kit is ARC'ed
and can be retrieved as described above.

\section{The need of neat MIDI files}
\label{neatfiles}
MIDI files are usually created by recording keyboard (or  other
MIDI instrument) events in a
sequencer. As a consequence, the timing of notes can be 'offbeat'.
\miditex{} needs much more 'clean' files to enable correct translation. 
Therefore, it is necessary to first clean up the notes in a MIDI 
file to be processed.
Many sequencers have a {\em quantize} function to align the
start time of notes to a specific timing. That is a good start. If you have
done that listen to the piece again to certify that all notes start at the
correct  position. The other thing you may want to do is to quantize the
{\em length} of notes. Many notes which are played
(usually short notes) do not fill the complete time they are
supposed to be played. Usually the key is released earlier. If this is not
corrected before starting \miditex{} the result is that after such notes a
rest is placed. According to the program no note is sounding there!
Some sequencers can quantize the length of notes
too. If not, you can either edit them manually if your
sequencer permits or you must do a lot of editing after processing 
of the file by \miditex.
So, try to get your input MIDI files as neat as possible.

\section{Description of command structure and options}
\label{description}
A general call to \musictex{} looks like this:

\begin{center}
\tt
midi2tex inputfile [outputfile] [-option1 [-option2 [...]]]
\end{center}
The options are:
\begin{tabbing}
  {\tt -?xxxxxxxxxxx} \=    \kill
  {\tt -?}          \> A help screen\\
  {\tt -s\#,\#,...} \> Skip tracks (default none)\\
  {\tt -i\#,\#,...} \> Combine tracks into one instrument (default none)\\
  {\tt -b\#,\#,...} \> Code staffs with bass clef (default violin)\\
  {\tt -a1\#,\#,...}\> Code staffs with alto 1 clef \\
  {\tt -a2\#,\#,...}\> Code staffs with alto 2 clef \\
  {\tt -a3\#,\#,...}\> Code staffs with alto 3 clef \\
  {\tt -a4\#,\#,...}\> Code staffs with alto 4 clef \\
  {\tt -o\#,\#,...} \> Order the tracks (default original order)\\
  {\tt -q\#}        \> Quantize (default off)\\
  {\tt -p\#,\#,...} \> Vertical part times (default type 4, quarter note)\\
  {\tt -f\#,\#,...} \> Force beams to zero slope\\
  {\tt -h\#}        \> Set horizontal size of music document\\
  {\tt -v\#}        \> Set vertical size of music document\\
  {\tt -m\#}        \> Set musicsize\\
  {\tt -e\#}        \> Set Elemskip size\\
  {\tt -k\#}        \> Set key sign\\
  {\tt -x}          \> Enable batch processing (ST version only)\\
  {\tt -dTYPE}      \> Generate debug information (default none)
\end{tabbing}

The input file name is any valid DOS name. If the extension is omitted
the default {\tt .MID} is assumed. The output file name
is optional. If omitted the input file name is used
with extension {\tt .TEX}.
The options are described in more detail below.

\begin{description}
\item[\bf -?, help screen] The program displays information on how
to enter a correct command line and a listing of available options.

\item[\bf -s, skip tracks] Occasionally you might want to skip
a track because you don't want any output from it to appear
on your scores. You can suppress output from a track by including
the {\bf -s} option in your command line. The numbers of the
tracks(s) you want to skip immediately follow the option. 
For instance if you want to skip a drumtrack  on track 4 your 
command line should include: {\tt -s4}.

The meta events in a skipped track {\em ARE} processed as they may 
contain information about timing or key signature.

The first track in a type 1 midi file is usually 
only used to store information about timing, key signature, etc.
Therefore {\em this track is skipped by default}. 
If for any reason you want to prevent skipping of this track then 
include {\tt -s1} in the command line.

\item[\bf -i, instruments] In \musictex{} it is possible to assign
two or more staffs to one instrument. For example they can be the left and
right hand of a piano piece. This option can be used to assign two or more
tracks to one instrument.
The tracks are entered as numbers directly after {\tt -i},
separated by comma's.
For instance if a piece contains 6 tracks and you want to assign
track 2 and 4 to one instrument your command line must contain the option:
{\tt -i2,4}.

\item[\bf -b, bass clef] \musictex{} enables coding of music using
different clefs. Most used are the violin and bass clef. \miditex{} enables
the assignment of the bass clef to one or more tracks.
If omitted, the default violin clef is used. For instance, to
assign the bass clef to track 2 of a MIDI file include {\tt -b2} in the
command line.

\item[\bf -a1..a4, alto clefs] Assign an alto clef to any of the
tracks. For instance, to
assign the alto 1 clef to track 3 of a MIDI file include {\tt -a13} in the
command line.

\item[\bf -o, order track] The ordering of tracks in your MIDI
file may not comply with the order you want the tracks to appear on the
output. With this option you can redefine this order. Here is an example:
consider a MIDI file containing 3 tracks. Normally the order of
the tracks on your output will be 1, 2, 3. If you want to alter this order
into 2, 3, 1 you must include the option {\tt -o2,3,1} in the command line.
It is important that you include \underline{ALL TRACKS} \attention in this
option. If there are 5 tracks
in the MIDI file there must be 5 numbers in the option string. Don't forget
to include the first track in the string. By default it is skipped in the
output but you {\em must} include it in this command.
If you forget one \miditex{} will exit with an error. So, before using this
command you must be sure how many tracks are included in the MIDI file.
The best way to use this option is to first translate the MIDI file without
this option.
Examine the output and determine the order of the tracks that you want.
Than retranslate the MIDI file with the {\tt -o} option included.

\item[\bf -q, quantize] Quantizing involves the rounding of start
times of notes. As stated in section \ref{neatfiles} quantizing is a good
tool for cleaning up the notes in your MIDI file. If you do not have this
opportunity on your sequencer and your output comes out ugly with lots of
rests inserted everywhere, try to use this option. The quantize option does
two things:
\begin{itemize}
\item quantize the start time of notes
\item quantize the length of notes
\end{itemize}
The number after the {\tt -q} option determines the quantization
time. Use table \ref{quanttimes} to determine the quantization time:
\begin{table}[hbtp]
\label{quanttimes}
\begin{center}
\begin{tabular}{|c|c|}
\hline
quant. note & number \\ \hline
\whole  & 1 \\ \hline
\half   & 2 \\ \hline
\quart  & 4 \\ \hline
\eighth & 8 \\ \hline
\sixteenth & 16\\ \hline
\thirdysecondth & 32\\ \hline
\sixtyfourth & 64 \\ \hline
\end{tabular}
\caption{The quantization numbers}
\end{center}
\end{table}

\item[\bf -p, part time] \musictex{} is designed to code notes in
a vertical way.
The notes at different tracks that start
at the same time should be aligned to each other. Therefore in \musictex{}
you can split up a measure into separate parts. The starts of such
parts are aligned above each other.

\miditex{} follows this philosophy. By default it separates the
measure into parts with a length of the denominator of the signature. 
If you want to change
this part time use this option. Use table \ref{quanttimes} to
determine what number you should enter after the option. For instance if
you want the separation time to be the length of an eighth note instead
of a quarter note include {\tt -p8} in your command line.

\item[\bf -f, force zero slope] This option forces the slopes of the 
generated beams to be zero. The beams will be oriented horizontally.

\item[\bf -h, horizontal size] With this option a horizontal size can be
set other than the default defined in \musictex{} (160 mm). 
\attention The parameter should be in 0.1mm.  This option
will output the proper sizing command in the source code. More important
is that this command is used to append line and page breaking commands
at the proper positions in the source file.

\item[\bf -v, vertical size] With this option a vertical size can be
set other than the default defined in \musictex{} (240 mm). See {\tt -h}
option for further details.

\item[\bf -m, musicsize] With this option a choice can be made between
20pt and 16pt. The parameter must be either 16 or 20.\\[0.3\baselineskip]
As an example we might want to produce a music document with
width 100 mm, height 200mm and  16 pt musicsize. The option string should
than include: {\tt -h1000 -v2000 -m16}.

\item[\bf -e. elemskip] Notes in \musictex are spaced by the (\musictex)
variable \verb@\elemskip@. Default values are set during initialization of
\musictex. In previous versions of \miditex \verb@\autolines@ was used
to alter the spacing of notes. Instead of using this macro in this version
\verb@\elemskip@ is now altered directly. This only happens when the size
of the document is changed in any way (-m,-v,-h,-e). If you're not satisfied
with the spacing of the notes you may use this option to directly alter
the value of \verb@\elemskip@. The value should be in pt. Changing the
value of \verb@\elemskip@ in this way does not corrupt line and page breaking.
An example: When using musicsize 20 the elemskip is 10 by default. 
If you want to reduce the space between the notes you must include 
the option {\tt -e8} in your command string.



\item[\bf -k, key sign] This option sets the keysign of the total music piece.
Presently \miditex does not allow to set a key sign for individual tracks. 
The parameter
following the option denotes the number of flats (negative sign) or sharps
(positive sign). For instance to code a piece with four flats the command
line should include: {\tt -k-4}

\item[\bf -x, batch proc.] This option is only available on the ST version.
It skips the message: {\tt hit key to exit} which appears after processing
of a file. Including this option on the command line in a batch file which
contains calls to \miditex enables continuous execution. 


\item[\bf -d, debug info] This option generates debug information. 
There are three ways to output this info: screen,
file or printer.This is the way to select the debug type:
\begin{tabbing}
  {\tt to printer}xxx \= -dPRINTER\kill
  {\tt to screen}  \> -dSCREEN\\
  {\tt to file}    \> -dFILE\\
  {\tt to printer} \> -dPRINTER
\end{tabbing}
File output is written to a file with the name of the input file and 
extension {\tt .MLG}.
I do not believe that this option is of any use to anyone who is
not familiar with the internal structure of the program. However, if for any reason
the program should crash at least you know at what point this happened. In
section \ref{bugs} \seealso{section \ref{bugs}} 
further suggestions for its use are given.\\
{\bf Warning:} \attention this option creates a {\em huge} amount of ASCII data.
A single page of typeset music will generate about 65kB of debugging info
depending on the number of notes in each measure.
\end{description}

\section{During processing}
During run time the program displays the measure it currently processes
on the screen between square brackets. This is the sign that the program
is actually doing something useful.

In some cases you may want to decide to abort the processing.
You can do so by pressing the 'q' on the keyboard.
The \musictex{} file and the log file are closed and the program exits.
See section \ref{bugs} for additional info. The code generated until
the {\bf q} key was  hit can be translated normally. Code is appended
which correctly closes the music document.

After completion of the translation
process the program displays the number of pages it has coded.

\section{Key signature and transposition}
Accidental note processing can be performed either by \musictex{} 
or by \miditex. You may choose the method you prefer.

\subsection{Key signature by \musictex{}}
From version 4.5 (and maybe earlier versions too)
it is possible to let \musictex{} figure out when flats
or sharps should be inserted. To do this, translate the MIDI file {\em without}
specifying any key signature. After the translation proces edit the resulting
\musictex{} file. In the preamble you will find the command
\verb+%\relativeaccidentals+. Uncomment it by removing the \% sign. Now
edit the {\verb+\generalsignature+} command to the required number of flats
(negative sign) or sharps (positive sign). During processing \musictex{} will now
figure out where to put flat and sharp signs.

\subsection{Key signature by \miditex{}}
\miditex{} contains a facility to generate sharps and flats taken
into account the general key sign.
To use this method translate the MIDI file with the
option {\tt -k}. The parameter of the -k option should be the number of
flats or sharps of the key sign. Now after the translation process the
file is ready for processing by \musictex. 
 
\subsection{Transposition}
Currently \miditex{} does not have the ability to transpose parts because
\musictex itself is quite capable of doing that. Including the  
\musictex \verb@\transpose=@ command in the preamble
allows up or down tranposition of tracks. See section 2.11 of the 
\musictex manual \cite{Taupin} \seealso{reference \cite{Taupin}} for
further details.
 
 \section{Line and page breaking}
 
\miditex keeps track of the space that is occupied by the typesetted
music and inserts \verb@\alaligne@ and \verb@\alapage@ at the 
proper moments. It uses an \verb@\elemskip@  of 10pt for musicsize=20
and 8pt for musicsize=16. Inclusion of \verb@\autolines@ is not
required anymore. \verb@\elemskip@ can be directly altered with 
the {\tt -e} option.
 
When translating a file into a document with musicsize 16 you may 
end up in a {\tt \TeX~~capacity exceeded~} error. 
During processing all measures are stored in memory until an 
\verb@\alapage@ is encountered. 
When selecting musicsize 16 there are so many notes on a single
page that occasionally \TeX~~may run out of storage space.
There are two ways out: use B\TeX~~ or translate the
MIDI file with musicsize 20. 


\section{The shell program (ST version only)}
The main program \miditex{} can be controlled by the previously described
options. The
current operating system of the Atari-ST can only handle a 
command string of limited length. I wrote a small GEM based shell
which avoids this problem. 

The shell can be started by double clicking on the program name 
({\tt M2TSHELL.PRG}).
A screen-wide form appears. This form contains edit fields for the
different options. To edit a box first click on it with the mouse.
The cursor appears in the box and you can use the keyboard to 
edit the string. You should {\em not} \attention include the option
identifier in the string. 
Only the parameters should be entered. For instance, if you 
want to skip tracks 2 and 3 just put {\em 2,3} in the box and {\bf not}
{\em -s2,3}.

 One exception is the  '{\em other} box'. Here you can enter
other valid \miditex options. As this box is not tied to a specific 
option the option identifiers {\em must} be included if this box is used.
Currently there are no boxes to allow selection of the alto clefs.
The only way to select them using the shell is by inserting proper 
option strings in the '{\em other} box'.

A file can either be selected by editing the file selection box or
by using the file selector by clicking on the button above the 
file selection box.

\section{An example of using \miditex{}}
Included in the package is an example MIDI file. This
file will be used to demonstrate how to use \miditex. 
The example file was generated
by Cubase. Track 1 contains Cubase mastertrack information (time
signature, clef etc.) and no notes. \miditex skip this track by default.
Translation of the file is now initiated by entering
\begin{verbatim}
            MIDI2TEX EXAMPLE -dFILE
\end{verbatim}
The screen will show some program info and start executing.
After termination of the program two files are generated. One is
called EXAMPLE.TEX and the other EXAMPLE.MLG. Use any editor to inspect
the content of the files. EXAMPLE.TEX will look like:
{\small
\begin{verbatim}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%    TEX translation of MIDI File :
%          example.MID
% 
%        Written by Hans Kuykens
%  this translation of date : 9-6-1992
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\input musicnft
\input musictex
\input musicadd
\input musictrp
\normal
\def\nbinstruments{3}
\generalsignature{0}\relax
%\centerline{\enorme PUT A NAME HERE and remove %}
\medskip\centerline{\moyen example.TEX}
\rightline{translation by MIDI2TeX}
\rightline{by H.J.P. Kuykens}
\generalmeter{\meterfrac{4}{4}}%
%\raggedlinestrue % uncomment for ragged right lines 
%\relativeaccidentals
\debutmorceau
%measure 1
\NOtes\uptext{Track 3} \hl q&\uptext{Track 2}
    \soupir &\uptext{Track 1} \qu J\enotes\relax
\temps\NOtes&\zq j\zq {^k}\qu g&\soupir \enotes\relax
\NOtes\ibl0o{0}\qb0p\qb0q&\soupir &\qu G\enotes\relax
\NOtes\qb0p\tbl0\qb0o&\zq k\zq j\ql g&\soupir \enotes\relax
%measure 2
\barre
\NOtes\cl n\ds &\soupir &\qu J\enotes\relax
\NOtes\hlp l&\zq {^k}\zq j\ibl1g{-1}\qb1g\zq j\zq k\tbl1\qb1g&
    \qu G\enotes\relax
\temps\NOtes&\soupir &\qu {_I}\enotes\relax
\temps\NOtes&\zq g\zq {_i}\qu {=k}&\qu {=I}\enotes\relax
%measure 3
\alaligne
\NOtes\ibl0k{0}\qb0k\qb0l&\soupir &\qu J\enotes\relax
\NOtes\qb0n\qb0k&\zq j\zq {^k}\ql g&\soupir \enotes\relax
\NOtes\qb0l\qb0o&\soupir &\qu G\enotes\relax
\NOtes\qb0n\tbl0\qb0l&\zq k\zq j\qu g&\soupir \enotes\relax
%measure 4
\barre
\NOtes\ccl k\pt g\ds &\soupir &\qu J\enotes\relax
\temps\NOtes\hl j&\zq j\zq {^k}\ql g&\qu I\enotes\relax
\temps\NOtes&\zh {_i}\zh g\hu {=k}&\qu J\enotes\relax
\finmorceau
\bye
\end{verbatim}
}
Now you can process EXAMPLE.TEX directly with \TeX. Be sure not
to use \LaTeX{} because \TeX{} cannot hold that many macro definitions.
After processing the above example you will find out that the score comes
out pretty ugly. The bass notes on the first score line are way beyond and
the melody line is on score 3. Now rerun MIDI2TeX with the following
command:
\begin{verbatim}
            MIDI2TEX EXAMPLE -o1,4,3,2 -b2
\end{verbatim}
This command now reorders the tracks and assigns the bass clef to the
second track. The resulting score will now look much better.\\

In addition to the example file mentioned above I also included some
MIDI files which I received from Volkmar Zitz which were a great help
for tracking down the errors in previous versions. Theses files
are ARC'ed into EXAMPLES.ARC. There is also a batch file included
which starts the translation processing of these files. This is of
course only for DOS users. ST users will have to do it manually unless
they are using a shell.


\section{Notes to versions}
\label{versions}
\begin{description}
\item[test version 1] This is the first external release of the
  software. It is distributed for evaluation purpose to persons who
  previously have shown interest in the program.

\item[test version 2] This is the second test release of the software. 
Shortly after the release of the first test release I discovered some 
disturbing bugs. I wanted to get rid off these before sending it to other
people who have shown their interest after a message on NEWS.
New features in the second test version are:
\begin{itemize}
\item Processing can now be stopped by pressing the 'q' on the keyboard.
\item The program now recognizes slur notes and generates source code
      for it.           
\item Bug during insertion of rests removed
\end{itemize}

\item[test version 3] A lot of bugs were found in the
previous version and solved. Most important ones are listed below:
\begin{itemize}
\item Reading of Key sign corrected (this caused crashes)
 
\item Running status events in the MIDI file now supported (also
  crashed the program)
\item MIDI files outside current directory in M2TSHELL.PRG now selectable
\item Problems in {\em 'Chordfinder'} solved (caused run time errors)
\item The slope of the beam is now calculated from the number of notes in the
      beam and the minimum and maximum note value within that beam
\item Chaining of beams to higher/lower order corrected. Also, single flag
      beam notes are now supported.
\item Clearing of beam and chord arrays forgotten which resulted in recognition
      of notes from previous measures.
\item The timing of the measure parts is now determined by the numerator
      of the signature.
\item Occurrence of accidental notes now only produce one flat/sharp sign.
\end{itemize}


{\bf New features} in the third test version are:
\begin{itemize}
\item Line and page breaking of the scores by insertion of \verb+\alaligne+ and
      \verb+\alapage+ commands. This is done by keeping track of the
      number of notes written.
\item Occurrence of meta events in track 1 are now handled properly at the
      right measure
\item Size of score and document may now be adjusted
\item \verb+\temps+ inserted before measure parts with no beams open
\item \verb+-h+ option from previous versions changed into -?
\item \verb+-k+ option added to set general key signature
\end{itemize}

\item[version 1.0]
\begin{itemize}
\item Correction in the generation of \verb@\alaligne@ and \verb@\alapage@
      commands. Removed \verb@\autolines@.      
\item Track 1 skipped by default. 
\item Batch processing option included (ST only).
\item Slur bows better due to enhanced filling of line.
\item Changed log file name extension from .LOG to .MLG to prevent
      overwriting by \TeX.
\item Added option -a1..-a5 to allow the use of alto clefs
\item Added option -e to allow changing the elemskip value
\end{itemize}

\item[version 1.1]
\begin{itemize}
\item A small bug during unskipping track 1 removed
\end{itemize}

\item[future plans]
\begin{itemize}
\item Shifting of notes occuring in a chord
\item Selection of only part of the MIDI file to be translated.
\item Automatic transposition of measures that contain notes exceeding
the \musictex note value limits.
\item Development of a more portable C-version of the program for other
platforms.
\end{itemize}
\end{description}


\section{Bugs \& problems}
\label{bugs}
I encourage everybody to report bugs or problems
that you encounter back to me so that these can be omitted in a next
release. Also, I am open for suggestions for enhancement of both
the program and the manual.

Piet van Oostrum suggested that this same program should also be 
able to translate type 0 MIDI files. I have adjusted the source code
such that type 0 files now do not induce an error exit. 
I tested a few of such files without succes. Nevertheless, I decided
to allow processing of such files for those of you who wish to experiment. 
When a type 0 file is encountered a warning is displayed
on the screen that the result may be unpredictable. I would be pleased
if anybody would share his experience with translating type 0 MIDI files
with me. 

Bugs may appear in two different forms: run-time errors and 
infinite loops. The first one generates an error-exit: the open files 
are closed and the program terminates. The second type of bug can be
recognized by the fact that the displaying of processed measures stops.
Just hit the 'q' and the program terminates. Error messages and warnings
are listed in the appendix. 

If you find any problems I suggest to run the program in debug mode,
%\footnote{see warning in description of debug option}
\seealso{section \ref{description}, -d option}
preferably in FILE mode. Then, send the MIDI file and a small note 
explaining the problem to me. I'll try to collect
the problems and avoid them in a next version. Please send compressed
(ARC, ZOO, LZH, ZIP), uuencoded files to:\\

\begin{center}\tt kuykens@amc.uva.nl \end{center}

or send by mail to:

\begin{center}
Hans Kuykens\\
Spaarndammerplts. 7b\\
1013 XP Amsterdam\\
The Netherlands\\
\end{center}
~\\

The following problems are known to me:
\begin{enumerate}

\item Notes which have a MIDI value larger or smaller than the notes accepted 
by \musictex{} are coded as question marks (?). This causes \TeX{} to stop 
processing. One way to solve this problem is to octivate the measure. 
Automatic octivation is {\em not} (yet) implemented in \musictex.

\item Flat and sharp signs may disappear under a preceding note in
score lines with very close spacing. This is a \musictex problem.

\item Notes in a chord are not shifted in any way. 

\item Closing of double sounding notes may corrupt the beaming business.

\item The program fails to run on the Atari TT.
\end{enumerate}

\section{License}
\begin{center}
\large
Copyright (c) 1992 by H.J.P. Kuykens.  All Rights Reserved.
\end{center}

You are free to use, copy and distribute  \miditex{} for non-commercial
purpose provided that :
\begin{itemize}
\item the name of the author is not removed from the manual nor
from the program itself
\item the program is not modified in any way
\end{itemize}

For commercial purpose \miditex is shareware. That is, if \miditex is used
to generate sheet music with the intention to distribute it for
commercial purpose a fee of \$~25,- is required.

The software comes without any warranty. 
The responsibility for it's use is completely for the user.
The author is not responsible for any damage arising from use of this 
program whether caused by negligence or other fault on the part of 
the author or by any other cause.


\section{Acknowledgement}
Although I wrote the code myself several people have made valuable
suggestions to me.
In particular I would like to mention Angelo Melis with whom
I exchanged a lot of ideas. Also, Noel (?) attributed to the ideas
for this program.

After sending off test versions I received bug reports
from: Volkmar Zitz, David Channing, Vincenzo de Florio, John Richards,
Piet van Oostrum, Mark Torrance, Michal Tomczak-Jaegermann. 
I would like to thank them for their valuable help and
suggestions. These bug reports are a tremendous help in finding and 
solving bugs in the software. Also Daniel Taupin and Dale (Gold?)
helped me out when I needed some specific 'inside \musictex' information.


\nocite{defuria,Taupin}
\bibliography{midi2tex}

\newpage
\appendix
\label{appendix}
\section{Error and warning messages}
\begin{enumerate}
\item No input file specified, or file does not exist
\item MidiFile track {\#} is not ok      
\item Found a NoteOff without a NoteOn      
\item Can only translate MIDI files of type 1, sorry$\ldots$
\item Nil pointer detected in NoteOff search
\item No\null. of order indices does not correspond with No\null. of
  tracks in file
\item Staffindex out of range, you tried to change a staff attribute 
      which I cannot handle
\item Heap exhausted during initializing memory
\item The noteheap appeared to be empty during a note request to the noteheap
\item A note value exceeded 127, probably a program bug
\item Invalid PartTime entered, only one of 1, 2, 4, 8, 16, 32 allowed
\item Invalid quantization time entered, use switch -? to get proper range
\item Can only define one multi-staff instrument in this version
\item Definition of an instrument of one track is useless
\item The Slur-array is exhausted, too many slurs (9) for MusicTeX
\item Process terminated by user 
\item The Beam-array is exhausted, too many beams (9) for MusicTeX
\item -h and -v option can only take one parameter
\item -m option parameter must be either 20 or 16
\item Unknown error, probably a bug$\ldots$
\end{enumerate}

\section{Package contents list}
The following files are included in the \miditex{} software
package:\\

{\Large PC version\\}
\begin{tabbing}
    {\tt MIDI2TEX.EXE:}xxxxxx \= the executable\kill
    {\tt MIDI2TEX.EXE:} \> the executable\\
    {\tt EXAMPLE.MID:}  \> an example MIDI file\\
    {\tt EXAMPLES.EXE:} \> additional example MIDI files\\
    {\tt MANUAL.TEX:}   \> the \TeX{} manual you are reading right now\\
    {\tt MIDI2TEX.BBL:} \> the bibliography file\\
    {\tt MIDI2TEX.PIC:} \> the frontpage logo
\end{tabbing}
~\\
{\Large ST version\\}
\begin{tabbing}
    {\tt MIDI2TEX.EXE:}xxxxxx \= the executable\kill
    {\tt MIDI2TEX.TTP:} \> the executable\\
    {\tt M2TSHELL.PRG:} \> the GEM shell to call {\tt MIDI2TEX.TTP}\\
    {\tt EXAMPLES.ARC:} \> additional example MIDI files\\
    {\tt M2TSHELL.RSC:} \> the resource file for the shell\\
    {\tt EXAMPLE.MID:}  \> an example MIDI file\\
    {\tt MANUAL.TEX:}   \> the \TeX{} manual you are reading right now\\
    {\tt MIDI2TEX.BBL:} \> the bibliography file\\
    {\tt MIDI2TEX.PIC:} \> the frontpage logo
\end{tabbing}


\end{document}

