%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% install_run_pmx271.tex 28 Dec 2015
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[11pt]{article}
\usepackage[dvips,colorlinks=true,linkcolor=blue]{hyperref}
\usepackage[dvips]{graphicx}
\def\MusiXTeX{MusiX\TeX}
\def\bs{{\tt\char'134}}
\newcommand\PMXX{\textbf{PMX}}
\newcommand\PMX{\PMXX~}
%
% Use \bfx for program names only.  Use \bf for single embedded letters 
%
\font\bfx=cmb10 scaled\magstephalf
\font\bbfx=cmb10 scaled1800
\setcounter{secnumdepth}3
\def\Bslash{\tt\char'134}
\textheight= 9.5in \voffset-.8in%
\textwidth= 6.5in \hoffset-1.0in
\hoffset-54pt
\begin{document}

\raggedright
\parindent24pt

\title{
  \bbfx
  Installing and Running the WIMA PMX Distribution
  \null\vskip10pt
  \Large\sl
  Version 2.71~--~December 2015 
  \null\vskip-5pt
  \author{\Large\rm Don \sc Simons\\
  \includegraphics[scale=0.4]{file600.eps}}}
\date{}
\maketitle

\setcounter{page}1
\pagestyle{headings}

\section{Introduction}

       This document explains in detail how to install and run \PMX in 
a Windows operating system, using the distribution 
\href{http://icking-music-archive.org/software/pmx/pmx271.zip}
{\underline{\tt pmx271.zip}}, which resides in the 
\href{http://icking-music-arihive.org}
{\underline{Werner Icking Music Archive}} (WIMA). 
That is the basic distribution assembled 
by the code's author. The executable 
files in it will only run under Windows. For other operating systems, 
other options include
either compiling the FORTRAN source files in {\tt pmx271.zip} and then following or
adapting the 
remainder of the guidance provided here, or (for Windows as well) using other 
distributions which will be derived in due course from {\tt pmx271.zip}, archived in
various \TeX\ repositories, and supplied with their own installation guides. 
Links to those other repositories can be found in the 
\href{http://www.icking-music-archive.org/software/htdocs/Getting_Started_Four_Scenar.html}
{\underline{software section}} of the Werner Icking Music Archive (WIMA). 

It is assumed
here that \TeX\ and \MusiXTeX\ version 1.21 or later are already present. If not, WIMA also 
provides instructions and links for acquiring and installing those programs from the same 
repositories. 

\section{Setup from scratch}

	Assuming \TeX\ and version 1.21 or later of \MusiXTeX\ have already been installed, 
decompress {\tt pmx271.zip} to any temporary folder.
It will contain the 
FORTRAN source files {\tt pmxab.for} and {\tt scor2prt.for},  
Windows executables {\tt pmxab.exe} and {\tt scor2prt.exe}, several sample 
{\tt .pmx} files,
%{\tt pmx.tex}, {\tt ref270.tex} (\TeX\ source for a command summary),
%{\tt pmx270.tex }(\TeX\ source for this file), 
the full manual {\tt pmx271.pdf}, a very condensed summary of all \PMX commands 
{\tt ref271.pdf}, {\tt pmx25-271.html} showing 
changes from version 2.50 to 2.71, and this installation manual 
{\tt install\_run\_PMX271.pdf}. If necessary, compile the FORTRAN programs.
I have tried to keep the source code as generic as possible, but minor 
modifications may be needed for FORTRAN-to-C translation and/or other
compilers.  

	Once you have assembled a full set of files, put the executables 
somewhere in your search path or in your working directory, {\tt pmx.tex} somewhere 
where \TeX\ can find it (which may or may not be part of a 
TDS-compliant file structure), and the sample {\tt *.pmx} files in your working 
directory (the one from which you will run \PMXX). The rest of the files can reside
wherever is convenient. Refresh the \TeX\ file name database. 

\section{Updating an existing \PMX installation}

If you already have an older version of \PMX installed, then after unzipping the distribution 
to a temporary folder, simply replace the old copies of
{\tt pmxab.exe}, {\tt scor2prt.exe}, and {pmx.tex}. Nothing more needs to be done, 
except to ensure that you have version 1.21 or later of \MusiXTeX\ installed.

\section{Running \PMX}

Running \PMX will be demonstrated by example, with the file {\tt barsant.pmx}. 
The first thing you need to do is specify where the generated \TeX\ file is to be 
placed. The path to that location is part of the setup data in the 
\PMX source file, in this case the 15th line of {\tt barsant.pmx}. It is set 
to {\tt ./} which represents the current folder, the one from which you will
run \PMX and the one where {\tt barsant.pmx} resides. If for some reason you 
want the \TeX\ file
to go somewhere else, then replace {\tt ./} with a path---either relative 
or absolute---to the desired folder. 

If you haven't done so, open a command window and navigate to the 
folder containing {\tt barsant.pmx}. Execute \PMX by typing 
{\tt pmxab barsant} . Alternatively, you may 
just type {\tt pmxab <return>} and you will be prompted
for a jobname, which in this case is just {\tt barsant} .  
{\bfx pmxab} will generate two files in the working 
directory: {\tt barsant.pml}
is a log file, and {\tt pmxaerr.dat} contains a single integer, 0 if 
the run was successful, otherwise the line number in the {\tt .pmx} file of the 
fatal error (useful for batch processing).   Also, on successful completion, 
{\tt barsant.tex} will be placed in the path specified in the setup.  

Now you are right where you would be after 
entering, debugging, and rough-editing the {\tt .tex} file manually.  To see 
the results, process {\tt barsant.tex} just as you would for any \MusiXTeX{} 
file. You must first run {\tt etex}, then {\tt musixflx}, and then {\tt etex}
again. You may view the {\tt .dvi} file so produced with a program like {\bfx yap}, 
or go on and run 
{\tt dvips} to create a postscript file and view that with a postscript viewer
such as {\bf GSview}. If you have used postscript slurs, dvi viewers have the disadvantage 
that they will not
display them. 

To make 
separate parts, run {\bfx scor2prt} by typing {\tt scor2prt barsant}.
The program will create a new {\tt .pmx} file for each instrument, in this
case {\tt barsant1.pmx} and {\tt barsant2.pmx}.
You may then process these 
files like you did the original one to create separate parts.

\section{Using scripts to ease processing}
Rather than having to manually run five programs every time you want to 
process and view a {\tt .pmx} file, you may use a batch script. Such 
scripts are generally platform-dependent.

For Windows, the following is a possible batch script which produces a 
postscript file:

\begin{verbatim}
pmxab %1
echo off
echo errorlevel
echo %errorlevel%
if not errorlevel 1 goto continue
echo stopping
goto :end
:continue
del *.mx?
etex %1
musixflx %1
etex %1
dvips -O0.25in,-0.22in %1
:end
\end{verbatim}

To use it, copy the script into a text file, save it with a name like
{\tt gopmx.bat}, and execute it by typing {\tt gopmx barsant}.

At the {\tt dvips} stage, this script uses offsets appropriate to the 
default output of \PMX with letter-size paper, assuming that the \PMX option
{\tt Acl} has {\it not} been invoked. 
 
If you wish to go on and produce a PDF file, most \TeX\ systems come with 
a program {\tt ps2pdf}. You could run this manually or include it in the main batch 
script. It may require that the file name provided to it include the extension {\tt .ps}.

If you have installed \PMX from one of the distribution sites, either under Windows or some 
other OS, there will probably be an included script {\tt pmx2pdf}. You should be able
to produce a PDF file directly from {\tt barsant.pmx} by simply typing {\tt pmx2pdf barsant}.   

\end{document}
