
	***  PMX - 1.3.7 (Unix/C version)  ***

This is the Unix/C version of PMX-1.3.7 . It was generated from the
fortran source code with Netlib's F2C. This package includes the special
library routines required to compile the resulting C source.
(please read the file "permission" in the present directory, which
lists conditions for the use of Netlib's library code)
Most of the original PMX distribution is contained in the pmx-orig/
subdirectory. Be sure to read the PMX manual there (pmx134.ps). It is
probably useful to print the quick reference card (ref134.ps).



  System Requirements
  ===================


* any current mainstream Unix flavour
* standard C compiler (as always, GCC is the safest bet)
* TeX/LaTeX (a recent version, as required by musixtex)
* MusiXTeX T.86 or newer



  Quick Installation
  ==================


If you're lucky enough to have a common household computer (i.e. a
single-user Linux-PC with teTeX installed) this version of PMX should
compile and install easily. Enter the following commands:

	make
	su root		(you will be prompted for the root password)
	make install
	./install.pmx
	exit

This should be enough to get PMX up and running.



  Installation
  ============


First, edit the Makefile to adjust it to your platform. The Makefile
contained in this package should work on most modern Unix platforms.
If you do not have an up-to-date version of GCC, change the first line
of the Makefile to "CC = cc", which will use your computer's native C
compiler. I recommend changing the second line to "CFLAGS = " in this
case, thus turning off optimisation.  (The IBM RS/6000 C compiler
crashed while trying to optimise pmxb.c, i.e. I killed it after it
hadn't budged for some ten minutes.) [1]


If you want to automatically install the executables you must also set
BINDIR to a directory which is in your search path and where you have
write permission. The preset directory /usr/local/bin should be OK on
most single user machines (you'll have to log in as root, of
course). If you're installing PMX just for yourself, you can also try
~/bin (i.e. a subdir bin/ in your home directory) which might already
be in your search path.


Now, type 

	make clean
	make

This will compile the programs "pmxa", "pmxb", and "scor2prt". Type

	cd examples
	make all

to run PMX on some example input files.  This should create several
.dvi files that you can view with "xdvi" or print with "dvips". If
they look okay type

	make clean
	cd ..

to remove all the junk files and return to the source directory. You
may type

	make install

now to install the PMX binaries to the chosen location. This will also
install the shell-script "pmx" which automatically runs pmxa, pmxb,
and both passes of musixtex for you.


Finally, you need to include the file "pmx.tex" in your musixtex
installation. You will have to log in as root to do so. 

If you've got the teTeX distribution installed, you can use the shell
script "install.pmx" to automatically install "pmx.tex" in an
appropriate place. Simply type

	./install.pmx

I've taken care to make this script as safe as possible. If it can't
figure out where to put "pmx.tex" it will terminate with an error
message. If there is no error message, you're done and can start
enjoying PMX. Otherwise, you need to install the file manually. The
following procedure should work on most systems:


1) Find the TeX directory tree. It should contain a texmf/
   subdirectory. "cd" to the tree's root.

2) If possible, do
 
	cd texmf/tex

   If you get an error message, just stay in the tree's root dir.

3a) Check if there's already an old version of "pmx.tex" installed:

	find . -follow -name pmx.tex

   This shouldn't find more than one instance of "pmx.tex". If there
   is a match, overwrite that file with the new version of "pmx.tex".
   Be sure to use GNU "find". Some Unix systems may ship with other
   versions of find that have a different input syntax. Be sure to
   check "find --version".

3b) If 3a) didn't find "pmx.tex", look for the musixtex files:

	find . -follow -name musixtex.tex

   If this fails, you're either in the wrong directory, or you need to
   install musixtex first. Now copy "pmx.tex" to the directory 
   containing "musixtex.tex".

4) Finally, you'll probably have to update the file hashing database.
   You may try to "cd" back to the TeX tree root directory and type

	texhash

   If this doesn't work, please refer to the documentation supplied
with your LaTeX distribution.


If you do not have root authority, copy "pmx.tex" to a directory of
your choice. You will then have to set the TeX input path in your PMX
source files accordingly. The Unix default (as used in the example
files) is to set the input path to "./" and copy "pmx.tex" to the
directory you're working in. However, you'll always have to remember
to copy the most recent version of "pmx.tex" to your PMX working
directory, or you'll run into trouble.




  Using PMX
  =========


First of all, you need to read the PMX manual (pmx-orig/pmx134.ps).
You must have a current version of MusiXTeX installed to use PMX.
In addition to the "pmxa" and "pmxb" executables, this Unix/C 
distribution contains a script named "pmx" which does automatically
run both passes of PMX and all passes of MusiXTeX for you.

Say, you've got PMX source file named "ditty.pmx" which you want to
turn into a DVI file. The command 

	pmx ditty
or 
	pmx ditty.pmx

will automatically create "ditty.dvi".

If you can't figure out how to install PMX, there's another easy way 
to run PMX: Make sure you've got MusiXTeX installed, and compile PMX.
Then copy "ditty.pmx" to the examples/ directory of this distribution,
cd there, and type "make ditty.dvi". This should work as well,
although "pmx" does a much better job of cleaning up junk files.




If you can't compile "pmxa" and "pmxb", or if you discover a bug in
those programs, send e-mail to HomeBrew Software at

	evert@ims.uni-stuttgart.de

Comments, suggestions, or any other remarks are also welcome.

Ported by HomeBrew Software.
[http://www.mathematik.uni-stuttgart.de/~evert]



Footnotes:

[1]
xlc's optimisation is next to useless anyway; set it to -O3 and it
will generate super-fast code (168 MFLOPS on an RS/6000 250 (66Mhz))
by generously removing parts of your source code that are REALLY
important, such as the iteration loop in a Julia set generator :-(
