\documentstyle{article}
\parskip2mm
\title{PP - An APL workspace transfer package}
\author{Johann Mitl\"ohner\\ Vienna University of Economics\\
  Augasse 2-6, A-1090 Vienna, Austria}
\date{April 9, 1992}

\begin{document}
\maketitle

This is version 3 of the APL workspace transfer package PP.  The
package helps to transfer APL applications accross different APL
dialects. It uses a translation of the APL characters into the
ASCII character set. The transfer file produced from APL objects 
is a human readable plain text file.
Some of the new features of this version are:

\begin{itemize}
\item The text file has a header with information on the system of origin
\item System variables are included 
\item Sam Sirlin's APL to ASCII translation is used
\item Lines in the text files are not longer than 73 characters
\item There is a pp version for APL*PLUS/PC
\item LaTeX printing support has been included
\end{itemize}

{\it 
\begin{center}\underline{Disclaimer}\end{center}
You can use, modify and distribute this software for
non-commercial and educational purpose without charge and at your own
risk.  I do not take any responsibility for damage or loss caused by
the use of this product.}


\section*{Files in this Package}

There are several versions of PP for various APL environments:

\begin{description}
\item[PP3DYWS]       Dyalog APL (HP-UX) workspace.
\item[PP3MACTF]      APL.68000 Level II (Macintosh) transfer form;
  ftp binary to your Mac's root directory,
  start APL.68000 II, type ')IN PP3MACTF'. 
\item[PP3MACWS]      APL.68000 Level II (Macintosh) workspace.
\item[pp3.apl]       APL2/PC (MS-DOS) workspace; ftp binary and )LOAD.
\item[pp3.atf]       APL2/PC (MS-DOS) transfer form; ftp binary and type )IN
\item[pp3.aplwsv2]   APL2/370 (VM-CMS) workspace
\item[pp3ibm.apltf]  APL2/370 (VM-CMS) transfer form
\item[pp3ibm.pduue]  APL2/370 (VM-CMS) uuencoded transfer form;
  it is added in this package since there might be problems
  with binary file transfer to VM hosts. Ftp in ASCII mode and
  uudecode on your VM host, then start APL2 and type ')IN PP3'.
\item[pp3.aws]       APL*PLUS/PC (MS-DOS) workspace; ftp binary and )LOAD
\item[pp3.pp]        PP3 in ASCII form; this is an example for
  PP's ASCII encoding. It contains the functions of PP itself. 
\end{description}


Have fun and let me know your
comments, critics, suggestions and bug reports 

Johann Mitl\"ohner\\
mitloehn@uxq.wu-wien.ac.at


\section*{Using PP to Transfer an APL Application}

PP is an APL workspace which can be used to transfer APL applications
accross different APL dialects. On the environment of origin, a text file
is produced from the objects of the workspace to be transfered. This file
is human readable and can be edited. The file is transfered to the
target environment, and the PP version there is used to read the objects
from the file and establish them in the active workspace, which
can then be )SAVEd.

Files written with earlier PP versions may not be read in correctly.
Otherwise, the use of PP has not changed.  If you want to transfer the
workspace MYWS from interpreter A to interpreter B, start APL
interpreter A and enter

\begin{verbatim}
 )LOAD MYWS
 )COPY PP3
 PPWRITE 'MYWS.PP'   
 )OFF
\end{verbatim}

PPWRITE has produced a text file 'myws.pp'.
Port that file to the computer system of interpreter B (ftp, mail, disk).
There, start interpreter B and enter

\begin{verbatim}
 )LOAD PP3
 PPREAD 'MYWS.PP'
 PPERPP            
 )WSID MYWS
 )SAVE
\end{verbatim}

PPERPP erases the PP objects in the active workspace.  The commands
PPWRITE and PPREAD take object names as additional arguments.  E.g.,
if you want to write function NUB and variable M to the file (and
nothing else), then enter:

\begin{verbatim}
 PPWRITE 'MYWS.PP NUB M'
\end{verbatim}

In the same fashion, if you want to read specific objects from the file,
add their names after the file name:

\begin{verbatim}
 PPREAD 'MYWS.PP NUB M'
\end{verbatim}

Note that when you do not give object names, PPWRITE will write all
objects of the active workspace to the text file, excluding PP's objects
(which you do not normally wish to transfer).

\section*{The Format of the Transfer File}

The file is a plain ASCII text file, which should travel well over various
telecommunications connections. The APL characters have been substituted for
by sequences starting with the escape character (dot), followed by the
(abbriviated) name of the character. The sequence is ended by a blank.
Dot is represented by ``{\tt. }'' (read: dot blank).
Therefore, the idiom ``unique'' is in this translation:

R .is ((X .io X)= .io .ro X)/X

Read: ``R is ((X iota X) equal iota rho X)/X''

APL functions and variables are represented in the file by the translation
to ASCII of the code lines. Variables are represented by the ASCII translation
of their ISO transfer form. An object's representation is started with a line
of the form

.begin $<$object type$>$ $<$object name$>$

One or more lines follow; the last line is

.end $<$object type$>$

You can add text at the begin, end or between an ``.end''-line and
the following ``.begin''-line, e.g. to add comments or descriptions
of what the code does. Such text will not be ignored by PPREAD.

If you do not like the default escape character (dot), you can change
it by adding a line to the text file which has the form

.escape $<$escape character$>$

E.g., to change to escape character to ``@'', you add the line

\begin{verbatim}
.escape @
\end{verbatim}

After that line, you can insert code which uses the new escape character.
If you want PP to use that escape character when it writes text files,
edit the function PPMESC which returns the escape character. 

The text file starts with information on the APL environment of origin.
That information is processed by PPREAD. If you want to update your
information when writing text file with PPWRITE, edit the function
PPSYS, which returns the information line.


\section*{Possible Problems}

Two problems are common, the first of them being {\it much} harder than
the second: semantics and character sets differ among APL dialects.


\subsection*{Different Semantics of APL Dialects}

PP only reconstructs the code of the interpreter of origin, which
might not run correctly in the new APL dialect when there are
differences in APL semantics.  Use a portable programming style and
interface functions if you want to minimize the costs of porting your
application.


\subsection*{Different Character Sets of APL Dialects}

PPREAD will sometimes say 'Unknown symbol, not translated'.
This means that the APL dialect does not have this character. 
You can 

	\begin{enumerate}
	\item Modify the original application and substitute something else
	for the offending character
	\item edit the text file and change the ASCII representation
	of the character into that of another one
	\item wait for PPREAD to finish and edit the established function 
	(operator). You will find the ASCII representation of the unknown
	character amidst the rest of the code (this alternate does not
	apply to variables, which will be established incorrectly when
	unknown characters are encountered).
	\end{enumerate}


\subsection*{Large Variables}

Large variables can cause a 'Workspace full' error.  There is a
solution if you do not really need that variable to be read in:
delete the lines in the text file that represent the variable and try
PPREAD again.


\section*{Printing APL Code}

You can use the function PPTEX to produce a TeX file suitable for
typesetting APL code. PPTEX takes as left argument the file name and
as right argument the function (or operator) name. To typeset all
Functions in the active workspace, use PPTEXALL. Note that this will
generate file names from APL functions names by appending '.TEX'. 
Make sure that it will not inadvertantly delete files. PPTEXALL
will create a TeX main document which includes the other files.
The name of this file is ``allfuncs.tex''.

To run the files through \LaTeX, you need the file apl.sty which
contains the macro definitions for the APL characters.  You can get
this file from watserv1.\-waterloo.edu, directory
/languages/\-apl/workspaces.  The typesetting provided by PP is not
sophisticated.  It was added to the system during development and left
in it because I found it usefull to have around.  You might want to
delete the functions used for TeX from your PP version.  They are:
PPTEX, PPTEXALL, PPMTX, PPTEXL, PPTEXW.

\end{document}