\documentclass[11pt]{article}
\usepackage[textwidth=6.5in,textheight=8.5in]{geometry}
\usepackage[osf]{mathpazo}
\PassOptionsToPackage{urlcolor=black,colorlinks}{hyperref}
\RequirePackage{hyperref}
\usepackage{xcolor}
\newcommand{\myurl}[1]{\textcolor{blue}{\underline{\textcolor{black}{\url{#1}}}}}
\newcommand{\pmxVersion}{2.9.8}
\begin{document}
\title{Installation of the CTAN PMX Distribution}
\author{Bob Tennent\\
\small\url{rdt@cs.queensu.ca}}
\date{\today}
\maketitle 
\thispagestyle{empty}

\section{Introduction}
We assume that you have already installed a MusiXTeX distribution.
Before trying to install PMX from CTAN, check whether your TeX distribution
provides a package for PMX; this will be easier than doing it yourself.
But if your TeX distribution
doesn't have PMX (or doesn't have the most recent version), this distribution
of PMX is very easy to install, though
you may need to read the material on 
installation of (La)TeX files in the 
TeX FAQ\footnote{%
\myurl{http://www.tex.ac.uk/cgi-bin/texfaq2html}},
particularly
the pages on 
which tree to use\footnote{%
\myurl{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS}}
and installing files\footnote{%
\myurl{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=inst-wlcf}}.

\section{Installing \texttt{texmf} Files}

Copy \verb|tex/pmx.tex| to \verb|/tex/generic/pmx| in a personal or local
TEXMF tree.
Copy files in \verb|doc| to \verb|/tex/doc/generic/pmx| in the TEXMF tree.

Update the filename database as necessary,
for example, by executing \verb\texhash ~/texmf\ or 
clicking the button labelled ``Refresh FNDB" in the MikTeX settings program.

\section{Installing \texttt{pmxab} and \texttt{scor2prt}}

The next step in the installation is to install
the two essential files that can't be installed in a TEXMF tree: the \texttt{pmxab} preprocessor 
and \texttt{scor2prt}, an executable used to produce single-player parts from multi-player scores.

\subsection{Pre-Compiled Executables}

On Windows
systems, one can install \texttt{pmxab.exe} and
\texttt{scor2prt.exe} in the \texttt{Windows} sub-directory; these are pre-compiled
executables and should be copied to any
folder on the PATH of executables. 
This might entail creating a suitable folder and adding that folder
to the PATH as follows: 
in ``My Computer''
click on 
\begin{center}
View System Information\quad$\rightarrow$\quad Advanced\quad$\rightarrow$\quad Environment Variables
\end{center}
scroll
down to ``path'', select it, click edit, and add the path 
to the folder after a semi-colon.


On the MAC OS-X platform (version 10.2 or better), one can install \texttt{pmxab} and \texttt{scor2prt} that are in the 
\texttt{OSX} sub-directory.

\subsection{Compilation from Source}

If you have conventional GNU development tools (\texttt{tar}, \texttt{gunzip}, \texttt{make})
and \texttt{gcc}\footnote{%
\myurl{http://gcc.gnu.org/gcc/}}
on your platform, 
you should be able to build \texttt{pmxab} and \texttt{scor2prt} executables.


To build \texttt{pmxab} and \texttt{scor2prt} for your platform: 
\begin{enumerate}
\item Unpack the \texttt{pmx-\pmxVersion.tar.gz} archive:
\begin{list}{}{}
\item \texttt{tar zxvf pmx-\pmxVersion.tar.gz}
\end{list}
and move to the resulting \texttt{pmx-\pmxVersion} directory.
\item Configure:
\begin{list}{}{}
\item \verb\./configure\
\end{list}
or, if you want the executables to be installed in your own path,
\begin{list}{}{}
\item \verb\./configure --prefix=$HOME\
\end{list}
\item Install:
\begin{list}{}{}
\item \verb\make install\
\end{list}
as root (admin) to install to the system path, or just
\begin{list}{}{}
\item \verb\make install\
\end{list}
to install in your own path.
\end{enumerate}
You should now have executables \verb\pmxab\ and 
\verb\scor2prt\ available for use.

\section{The \texttt{musixtex.lua} Processing Script}

The Lua script \verb\musixtex.lua\ 
is simply a convenient wrapper that,
on files with extension \verb\.pmx\, by default runs the 
following processes in order (and then deletes intermediate files):
\begin{itemize}\topsep=0pt\itemsep=0pt
\item \verb\pmxab\ (pre-processing pass)
\item \verb\etex\  (1st pass)
\item \verb\musixflx\ (2nd pass)
\item \verb\etex\ (3rd pass)
\item \verb\dvips\ (to convert \verb\dvi\ output to Postscript)
\item \verb\ps2pdf\ (to convert \verb\ps\ output to Portable Document Format)
\end{itemize}%
There are many options to vary the default behaviour.
If the \verb|musixtex| has been properly installed on your system, you should
be able to just enter the command \verb\musixtex myfile\.

\section{Discussion}



Other pre-processor packages, additional documentation, additional
add-on packages, and many examples of PMX and MusiXTeX typesetting may be found
at the Werner Icking Music Archive\footnote{%
\myurl{http://icking-music-archive.org}}.
Support for users of MusiXTeX and related software may be obtained via
the MusiXTeX mail list\footnote{%
\myurl{http://tug.org/mailman/listinfo/tex-music}}.
PMX may be freely copied, duplicated and used in conformance to the
GNU General Public License (Version 3, 29 June, 2007, see included file \verb\gpl.txt\).

\end{document}
