summaryrefslogtreecommitdiff
path: root/support/pmx/doc/pmx-install.tex
blob: e49bfd0f8c005269c5bc1fa82dee134e6e544f7a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
\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.8.4}
\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{pmx.tds.zip}}

In this distribution of PMX, most of the files to be installed 
(including macros, documentation, and a processing script) are in 
\myurl{http://mirror.ctan.org/install/support/pmx.tds.zip} at CTAN.
The file \verb|pmx.tds.zip| is a zipped TEXMF
hierarchy; simply download it and unzip in the root folder/directory of whichever TEXMF tree
you decide is most appropriate, likely a ``local'' or ``personal'' one.
This should work with any TDS\footnote{%
\myurl{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds}}
compliant TeX distribution, including MikTeX, TeXlive and teTeX.

After unzipping the archive, 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.

Documentation for PMX is installed under \verb\doc/generic/pmx\
in the TEXMF tree.  

\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} 32 bit or 64~bit sub-directories; 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}