%
%  mxinsuse.tex
%
%   This file is part of MusiXTeX
%
%   MusiXTeX is free software; you can redistribute it and/or modify
%   it under the terms of the GNU General Public License as published by
%   the Free Software Foundation; either version 2, or (at your option)
%   any later version.
%
%   MusiXTeX is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%   GNU General Public License for more details.
%
%   You should have received a copy of the GNU General Public License
%   along with MusiXTeX; see the file COPYING.  If not, write to
%   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA.
%

\documentclass[11pt,a4paper]{article}
\usepackage{multicol}
\usepackage[dvips,bookmarks=true,bookmarksnumbered=true,bookmarksopen=true,colorlinks=true,pdfborder={0
  0 0}]{hyperref}
\usepackage{url}
\usepackage{indentfirst}
\usepackage[ansinew]{inputenc}

\makeindex

\def\ixem#1{#1\index{#1}}
\def\musixtex{MusiX\TeX}
\def\Bslash{{\tt\char'134}}
\def\|{{\tt\char'174}}
\textheight= 9.5in \voffset-.8in%
\textwidth= 6.5in \hoffset-1.0in

\hoffset-54pt

\begin{document}
\begin{center}\section*{\LARGE\bf Installing and Running \musixtex~in MS Windows }\end{center}
\begin{center}{\large Andre Van Ryckeghem, Don Simons}\end{center}
\tableofcontents \setcounter{secnumdepth}4

\section{Introduction}

This document explains in detail how to install and run \musixtex\ under MS 
Windows XP or Vista\footnote{Most of this information can be applied to other 
Windows versions or operating systems with little or no modification. With
more volunteer effort, specifics for other OS's could be added}. Along the 
way it includes information about locations of the various file types, which may be 
useful for any future incremental \musixtex\ upgrades. Sections 2-4 provide
this setup information in detail.
The \musixtex\ language, and installation and use of the preprocessors 
\textbf{PMX} and \textbf{M-Tx}, are all covered elsewhere.

In order to use \musixtex\ you must have installed other supporting
software, including a \TeX\ system, text editor, and a postscript viewer. This
document assumes the \TeX\ system MiK\TeX\ 2.8 is already installed, 
but should apply at least to versions 2.6 and 2.7 as well. 
The recommended postscript viewer is GSview (the executable is gsview32.exe). 
It can also serve to produce PDF 
files from postscript. Some of the batch files in this distribution assume
GSview is present.

MiK\TeX\ 2.8 comes with a development environment called
\TeX Works. In principle it can be made to run all the necessary codes in
sequence, but setting it up is very demanding, so it will not be discussed
here. Instead, Section 5 details all the individual steps needed to produce a 
PDF file of a music score, and describes various batch files that can help 
automate the process.

MiK\TeX\ itself comes with a version of \musixtex. This will usually be out of date.
It is suggested to leave these files alone. By installing the latest version 
of \musixtex\ according to the guidelines given here, you will supersede the 
version supplied with MiK\TeX. It is also suggested that if MiK\TeX\ ever offers
to update your \musixtex\ installation or provide a missing file, you 
politely decline, find the missing file yourself on the Icking archive, and 
position it in your own \musixtex\ installation.


\section{Getting Started - Naming Directories}

To begin installing \musixtex, 
create a DOWNLOAD folder of your choosing and unzip the \musixtex\ distribution
into it, being sure to select "use folder names" when unzipping.

Next, you have to decide what directories various categories of files will 
permanently reside in. The names are entirely at your discretion. It
is possible but probably best not to put them in the same folders
with the corresponding MiKTeX files. The reason is that if MiKTeX is 
upgraded to a newer version, the \musixtex\ files will disappear. Some suggested
names are given in the table below: 

\begin{center}\begin{tabular}{|l|l|l|l|}\hline
Category & Description & Short Names & Windows Conventional\\\hline
DOWNLOAD & Unzip \verb|musixtex.zip| here & \verb|c:\musix| & $<$userdocs$>$\verb|\mtunzip|\\ 
TOOLS & executables & \verb|c:\tools|& $<$userprogs$>$\verb|\MusiXTeX|\\ 
ROOT & other \musixtex\ files & \verb|c:\musixtexmf|& $<$userdata$>$\verb|\MusiXTeX|\\
WORK & working files & \verb|c:\musix\mymp| & $<$userdocs$>$\verb|\MusiXTeX|\\\hline
\end{tabular}\end{center}

\noindent The suggested ``Windows Conventional'' names are different in XP or Vista, as
given in the table below. Non-English versions of Windows may use different names for
the pre-existing folders; you'll have to make appropriate adjustments.

\begin{center}\begin{tabular}{|l|l|}\hline
Windows XP & \\
$<$userdocs$>$ & \verb|c:\Documents and Settings\|$<$owner$>$\verb|\My Documents| \\
$<$userprogs$>$ & \verb|c:\Program Files| \\ 
$<$userdata$>$ & \verb|c:\Documents and Settings\|$<$owner$>$\verb|\Application Data| \\\hline
Vista & \\
$<$userdocs$>$ & \verb|c:\users\|$<$owner$>$\verb|\My Documents|\\
$<$userprogs$>$ & \verb|c:\users\|$<$owner$>$\verb|\My Programs|\\ 
$<$userdata$>$ & \verb|c:\users\|$<$owner$>$\verb|\Application Data|\\\hline
\end{tabular}\end{center}

As mentioned once already, the choice of folder names is entirely at your discretion.
One of the authors of this guide advocates the ``Short Names'' (because they are so
much simpler), while the other prefers ``Windows Conventional'' (because they conform
with windows standard locations for executables and data files). 
Users of certain non-English versions of Windows who
choose the ``Windows Conventional'' route will have to make some adjustments to 
account for the fact that standard folder names such as ``My Documents'' are
different.  

The remainder of this section provides further detail about the directories.

The TOOLS directory will hold executables and must be placed in the Windows 
path. One way to do this that always 
works in XP or Vista is to right click on the ``My Computer'' desktop icon, left click on 
Properties\|Advanced\|Environment Variables, in the ``System Variables'' section
scroll down to ``path'', select it, click edit, and append the full path name you
have selected for the TOOLS directory. Note that if there are any command windows 
open at the time you do this, the path change will not affect them; it will only 
affect newly opened command windows.
It may be tempting to avoid this path-setting exercise by using the directory 
that MiK\TeX\ already established for its executables and placed in the path, viz., 
\verb|c:\Program Files\MiKTeX 2.8\miktex\bin|; however as noted above, this is
not recommended because this directory will be overwritten every time MiK\TeX\ is 
updated. 

The ROOT directory will house all of the \musixtex\ files except the 
executables and your personal working files. MiK\TeX\ needs to know where these
files are. To
accomplish that, you must run the MiK\TeX\ ``Settings'' program, which is found 
under Start$|$Programs$|$MiKTeX 2.8$|$Maintenance. After starting
the program, select the``Roots'' tab, click the ``Add'' button, and enter the
full path name for your \musixtex\ ROOT directory.

A final directory, WORK, houses user-created \musixtex\ source files. It need
not ever be formally specified, and can change at will. It is simply the place
you keep your current working files. 

\section{Installing \musixtex\ Files}

\subsection{Option A: Using a batch file}

For adventurous and trusting souls, there is a batch file \verb|INSTMUS.bat| in 
\hfil\break
DOWNLOAD\verb|\InstallMusiXTeX\installWindows| that will copy all files to the 
proper locations and do 
the necessary editing, but before running it you must edit it with your selected directory
path names. The first SET command in the file defines the DOWNLOAD directory; the second, 
TOOLS; the third, ROOT, and the fourth, the MiK\TeX\ root directory. Caution: any 
path name that contains spaces must be surrounded by double quotes when entered in the 
the batch file. If you are uncertain what to enter for the MiK\TeX\ root, you 
should run MiK\TeX\ Settings as explained above, select the
``Roots'' tab, and check the ``Show MiKTeX-maintained root directories'' box if it 
is not checked. The path you want is labeled either ``CommonInstall'' or ``Install''. 
If you find both then check to see which one houses MiK\TeX.

The reason you need the MiK\TeX\ root directory is that some files from there 
need to be copied, edited, and the edited version placed in your ROOT directory. 
The batch file does all of this.

Once you have carefully edited \verb|INSTMUS.bat|, run it either from the command line
or by double-clicking it in Windows Explorer.

\subsection{Option B: Manually transferring files}

Instead of using the batch file, you could perform all the steps manually. All
the necessary steps are enumerated below. 

\begin{enumerate}

\item Copy all the files DOWNLOAD\verb|\fonts\mf\*.mf| into the folder\\
ROOT\verb|\fonts\source\public\musixtex|

\item Copy all the files DOWNLOAD\verb|\fonts\tfm\*.tfm| into the folder\\
ROOT\verb|\fonts\tfm\public\musixtex|

\item Copy all the files DOWNLOAD\verb|\tex\*.*| into the folder\\
ROOT\verb|\tex\generic\musixtex|

\item Copy all the files DOWNLOAD\verb|\musixtexadd\*.tex| into the folder\\
ROOT\verb|\tex\generic\musixtex|

\item Copy all the files DOWNLOAD\verb|\bin\*.*| into the TOOLS directory.

\item Copy all the files DOWNLOAD\verb|\fonts\type1\*.pfb| into the folder\\ 
ROOT\verb|\fonts\type1\public\musixps\type1|

\item Copy the pdf configuration file 
\verb|c:\Program Files\MiKTeX 2.8\dvipdfm\config\config|  to
ROOT\verb|\dvipdfm\config\config|. Edit the copied file 
by adding the line \\
\texttt{f musix.map}

\item Copy the file DOWNLOAD\verb|\MUSIXTEXdistribution\dvipdfm\musix.map| 
to \\
ROOT\verb|\dvipdfm\config\musix.map|. Edit the copied file 
by adding the line \\
\texttt{f musix.map}

\item Copy the postscript configuration file\\
\verb|c:\Program Files\MiKTeX 2.8\dvips\config\config.ps|  to \\
ROOT\verb|\dvips\config\config.ps|. Edit the copied file by adding the line \\
\texttt{p +musix.map}

\item Copy the file DOWNLOAD\verb|\MUSIXTEXdistribution\dvips\musix.map| to \\
ROOT\verb|\dvips\config\musix.map|

\item Copy the file DOWNLOAD\verb|\MUSIXTEXdistribution\dvips\psslurs.pro| to \\
ROOT\verb|\dvips\base\psslurs.pro|

\item Copy the file \verb|c:\Program Files\MiKTeX 2.8\dvips\tetex\config.pdf|  to\\
ROOT\verb|dvips\tetex\config.pdf|. Edit the copied file by adding the line \\
\texttt{p +musix.map}

\end{enumerate}

\section{Refresh the File Name Database}

Whether you have transferred and edited files manually or using the batch file,
one final chore is to inform MiK\TeX\ where the 
\musixtex\ files are located. Do this by running the MiK\TeX\ ``settings'' program
from the ``start'' menu and clicking the button labelled ``Refresh FNDB'' (File Name DataBase).

ALWAYS REMEMBER TO REFRESH THE FILE NAME DATABASE whenever you add a file to
\musixtex.

\section{At Last, Running \musixtex and Viewing a Score}

To test your setup, copy the sample file DOWNLOAD\verb|\TestTeXInputs\test1.tex| 
to your working directory. \musixtex\ operates from the command line. 
The most straightforward way to run it 
in Windows XP or Vista is from a command window, which is opened by clicking
from start\verb$|$run, then entering ``cmd''. In the command window, 
navigate to your working directory. 
\musixtex\ is a 3-pass system. For the first pass, enter \verb|tex test1|. This
should produce \verb|test1.mx1|. Next, enter \verb|musixflx test1|. This should
produce \verb|test1.mx2|. Finally, enter \verb|tex test1|. This should produce
\verb|test1.dvi|. The basic processing is now complete. 

The files \verb|test1.mx1| and \verb|test1.mx2| are intermediate working files 
produced by \TeX\ (on its first pass) and \verb|musixflx| respectively. Once the 3-step
process is complete, they will never be needed again and should be deleted; 
in fact, if you have made any changes to your \musixtex\ file, you \textit{must} 
delete \verb|test1.mx1| before repeating the 3-step process. A great deal more 
information about the process is included in the \musixtex\ manual in\\
DOWNLOAD\verb|\MusiXTeXDistribution\doc\musixtex\manual\musixdoc.pdf|.

To view the result, you should create a postscript file by typing
\verb|dvips test1|. This should produce \verb|test1.ps|, which can be 
viewed by running GSview from the Windows GUI. Note that all \TeX\ 
systems include a ``DVI 
viewer'' such as YAP. These will not display Type K postscript slurs, and 
so are generally not recommended. 

As with file copying and editing, the above steps can be accomplished with
batch files. The initial 3-step process \texttt{tex $\Rightarrow$ musixflx
$\Rightarrow$ tex}\ is accomplished with the batch file \verb|musixtex.bat|,
which should have been copied into your TOOLS directory, and should work 
on any Windows system without modification, provided the TOOLS directory is in 
the path. The batch file needs a single argument, the base name of your
typesetting project. This batch file checks for the \verb|.mx1| and \verb|.mx2| files and
deletes them if they are present.

The file \verb|mups.bat| does everything \verb|musixtex.bat| does, and then
produces a postscript file from the \verb|.dvi| by running \verb|dvips|.
You may wish to edit the file to (a) produce letter size output 
rather than A4, which is accomplished by changing the \verb|dvips| option ``-t a4''
to ``-t letter'', and (b)~adjust the page image offsets. For example, PMX-generated 
\musixtex\ files with default sizing will be properly centered on letter paper
if you add the \verb|dvips| option ``-O0.25in,-0.22in''.

We recommend using GSview to view the resulting postscript. It runs from the 
Windows GUI. When iteratively editing a \musixtex\ file, it is very convenient 
to simply leave GSview running, because once a particular postscript file 
is loaded, whenever the file changes, GSview will \textit{automagically} 
renew it. And when you finish your masterpiece, if you wish to distribute it, 
you can use GSview to produce a PDF file. This is done from File\verb&|&Convert,
then select ``pdfwrite'', click ``OK'', and provide a file name. 

Finally, once \musixtex\ is set up, if you would like to avoid the command window,
there is a way that you can operate entirely from the Windows GUI. But to do so, 
you'll probably want to keep every individual typesetting project in a separate working 
folder, and that folder will have to contain a copy of \verb|mupsall.bat|. You 
may then run the batch file by double-clicking on it from Windows Explorer. The reason 
for having a separate folder for each project is that to avoid having a command
line argument, \verb|mupsall.bat| simply runs \verb|mups.bat| on every 
\verb|.tex| file in the folder.

Users of preprocessors M-Tx and/or PMX may wish to create their own batch files, 
starting with \verb|mudvi.bat|. Drawing on examples already in the 
file, simply add commands to run the desired preprocessor(s) and perform the 
necessary error checks. This is discussed a little more in the \musixtex\ manual. 

For advanced users, the two other batch files in the TOOLS directory, 
\verb|lapsview.bat| and
\verb|lapdfview.bat|, may be used to process La\TeX\ files that contain 
\musixtex. They will produce postscript and PDF files respectively. 
Combining \musixtex\ and La\TeX\ is not for the beginner, so these 
files will not be discussed further here. 

\end{document}
