\documentstyle{article} %This is LaTeX
% Don't be wondering if you get lots of errors from plain tex.
%  I (J\"org) do only know how to use LaTeX.

\title{ARexx Support for PasTeX\\
\medskip
--Preliminary version--}

\author{Georg He\ss mann\\ hessmann@unipas.fmi.uni-passau.de\medskip\\
J\"org H\"ohle\\ hoehle@cs.uni-sb.de\\Joerg\_Hoehle@saarag.zer}

\begin{document}
\maketitle
\begin{abstract}

ARexx is a powerful means of communication between processes on the
Amiga Computer. ShowDVI features a very good ARexx interface, and a
few ARexx macros have been written that support the communication
between ShowDVI, the TeX compiler, {\tt METAFONT}, the Shell and
optionally the editors CygnusEd\footnote{CygnusEd is a product of
ASDG\@.} and Micro(GNU)Emacs (MG)\footnote{The latest release of MG,
MG3$\beta$4 can be found on AmigaLibDisk352 of the Fred Fish
collection}. This paper tries to describe the installation and the use
of these macros. 

\end{abstract}

\newpage
\tableofcontents
\newpage

\section{Copyright}

All the macros have been put into the public domain by Georg He\ss{}mann
and J\"org H\"ohle.

We hope that users of PasTeX and ARexx will write macros for
other editors and add new features to the existing ones. Bugs and
suggestions are welcome!

\section{Installation}

Follows a short overview of the files that are part of the
distribution:

\begin{itemize}

\item {\tt doc/TeXRexx.tex} This document.

\item {\tt rexx/namestruc} This ARexx macro contains a function that
returns the 3 main components of a filename, which are the device or
volume name, any subdirectory, and the name withtout any extension.
{\bf This file {\em must} be placed in your {\tt Rexx:} directory!}

\item {\tt rexx/TeX-Server.rexx} This is the main program that creates an
ARexx port named {\tt Start\_TeX}, waits for an order to compile a file,
then calls virtex to compile it.

\item {\tt rexx/TeXedit.rexx} This macro may be called by virtex or initex
directly, or by the TeX-server in case of an unsuccessful compilation.

\item {\tt rexx/Start\_TeX.\#?} These are macros used to call the
TeX-server. Currently available macros permit calls from within the
CLI, ShowDVI, CED and MG\@. 

\item {\tt rexx/Quit\_TeX\#?} These are macros used to terminate the
TeX-server. The generic macro {\tt rexx/Quit\_TeX} may be called from
any program. Specific macros are {\tt rexx/Quit\_TeX.ced} for the CED
editor, and {\tt rexx/Quit\_TeX.sd} for ShowDVI. 

\item {\tt rexx/\#?ToFront} These are macros that may be used to bring
some screen or window to the frontmost position, be it the CED,
TeX-server or ShowDVI window or screen.

\item {\tt rexx/StartDVIprint.\#?} These are simple macros that ask for
which pages are to be printed and then calls DVIprint. The correct
printer must already be defined in {\tt ENV:DVIPRINT} (see the
documentation on DVIprint), or the default preferences printer will
be used.

\item {\tt rexx/NextTeXError.\#?} These are very simple macros that
may be helpfull when jumping from one error to the next one. 

\end{itemize}

There are two ways to install all these macros correctly. An easy one,
and one which does not require you to add lots of files to your single
{\tt rexx:} directory. 

%PSTF ???
\subsection{Easy installation}

This method is not recommended. Move all the files in the {\tt rexx/}
directory into your REXX: directory.

\subsection{Better installation}

This other installation does not require you to put a dozen of files
into your already overfull {\tt rexx:} directory. {\em Only} the file
{\tt namestruc} need to be there. All the other files can reside in any
directory, {\tt TeX:rexx/} preferred. For this setup to work, you have
to use full path names when calling the macros.

\begin{itemize}

\item TeX-server: Set the environment variable {\tt ENV:TEXREXXEDIT}
to the full path and name of the server macros, e.g.\ {\tt
"TeX:rexx/TeXedit.rexx \%s \%d"}. 

\item ShowDVI: Edit your {\tt ShowDVI.config} file {\em before} you
run ShowDVI, and change the line

{\tt arexx-start-script	rx TeX-server.rexx}\quad into

{\tt arexx-start-script	rx TeX:rexx/TeX-Server.rexx}

Change the entries for the function keys too, use full path names:
{\small \begin{verbatim}
f1			TeX:rexx/Start_TeX.sd
f2			TeX:rexx/Start_TeX.sd ?
f3			TeX:rexx/Quit_TeX
f10			TeX:rexx/WBtoFront
F2			TeX:rexx/Start_TeX.sd
\end{verbatim}}

\item CLI: Either use {\tt rx TeX:rexx/Start\_TeX}, or add {\tt
TeX:rexx/} to your search path if you use csh or OS 2.0 and use {\tt
Start\_TeX}

\item CED: Install the commands with full pathes, like
`TeX:rexx/Start\_TeX.ced' and 'TeX:rexx/Start\_TeX.ced ?'

\item MG: Install the commands with full pathes, like in the following
example:

{\small\begin{verbatim}
; Add some ESC-x functions
; this one will use the format in ENV:TEXFORMAT or ask for one
fset tex-compile	"\exrexx\nTeX:rexx/Start_TeX.mg\n"
; this one will ask for a format to be specified
fset tex-compile-queryf "\exrexx\nTeX:rexx/Start_TeX.mg ?\n"
;fset tex-compile-latex "\exrexx\nTeX:rexx/Start_TeX.mg latexgde\n"

; demo other possibilities
fset tex-view-to-front	"\exrexx\nTeX:rexx/SDVItoFront.mg\n"
fset tex-quit		"\exrexx\nTeX:rexx/Quit_TeX\n"
\end{verbatim}}

\end{itemize}

That's all there is to do!

\section{How to Use}

Once you have correctly installed all the files, you sure would like to
try them out. I'll explain it.

\subsection{The TeX-server}

First, you have to start the TeX-server. With OS2.0 you may use
ShowDVI's {\tt Shell commands $->$ ARexx TeX Shell} menu option.
Otherwise open a new CLI window that will be reserved for interaction
with the server. Under 1.3 don't use ShowDVI's menu for this, because
ShowDVI is always waiting for this CLI to finish before responding to
any other commands.
%make sure that your path includes the directory where
%virtex stays ("{\tt path TeX:bin}"),
then start the TeX-server ("{\tt
rx TeX:rexx/TeX-server}") in this CLI.

You will be prompted if you want to call the editor as soon as virtex
encounters the first error. If you answer yes, virtex will call an
editor through the {\tt TeXedit.rexx} script as soon as the first
error is found. Otherwise, you will be able to enter commands in virtex
in the usual manner (you may still use the 'e' command to call the
editor).

Then you will be prompted if you want to be asked for a format name
whenever an application wants to compile a file using the default
format. You are now going to ask "But what is this default format?".
Here is the explanation: virtex and/or the TeX-server use the
environment variable ENV:TEXFORMAT to store the name of the default
format. Thus, if you call virtex from CLI without specifying a format,
e.g.\ "virtex TeXRexx", then virtex will not use the plain format, as
it always did before, but will use the format of name specified in
ENV:TEXFORMAT\@. 

When you call the TeX-server via some Start\_TeX macro, you can
specify a format name, or you can give no format name, or you can
specify a format name of '?', in which case you will be prompted for
the format to be used. If you called some Start\_TeX macro without
specifying a format name, and you started the TeX-server and answered
"yes" to this second question, you will be prompted for a format name.
If you answered "no", the default in {\tt ENV:TEXFORMAT} will be used.
If {\tt ENV:TEXFORMAT} is not yet defined, you will be prompted too.
Sounds complicated? Try it out!

\subsection{ShowDVI}

You have to edit {\tt TeX:config/ShowDVI.config} (or the first {\tt
ShowDVI.config} in your {\tt ENV:TEXCONFIG} path) manually, {\em
before} you run ShowDVI. This is because once ShowDVI is run, it never
re-reads its configuration file.  This is an example of the end of
your ShowDVI.config file:

\begin{verbatim}
f1			TeX:rexx/Start_TeX.sd
f2			TeX:rexx/Start_TeX.sd ?
f8			TeX:rexx/Quit_TeX
f9			TeX:Rexx/CEDtoFront
f10			TeX:rexx/WBtoFront
\end{verbatim}

The function key f1 will compile the file currently shown using the
format stored in ENV:TEXFORMAT (usually the last used). The function
key f2 will prompt
you for a format to be used, then compile. f8 will terminate the
TeX-server. f9 may be used to pop the CygnusEd screen to the front.
Same applies to Workbench with f10. Note that full pathnames are used:
You are not required to put all these files in the {\tt Rexx:} directory.

\subsection{from the Shell}

Calling the server differs from calling virtex directly in that you do
not have all the options available that you have otherwise:

\begin{enumerate}

\item You cannot pass options like {\tt -c, -d,} \dots to virtex.

\item You {\em must} specify an existing filename. You cannot say
"{\tt Start\_TeX testpage}" even though you now that testpage.tex is
somewhere in your (LaTeX) include path. Start\_TeX is looking for
testpage in your current directory and will report an error if it
cannot find it there. 

\item You can, however, say {\tt Start\_TeX TeX:macros/latex/testpage},
as before.

\item You are not obliged to put a \& in front of the format name.
This is mostly usefull for many shells!

\item The server is called asynchronously, your CLI is again free for
use, even if TeX has not finished compiling your file yet!

\end{enumerate}

The general syntax is:

{\tt [rx] Start\_TeX [$<formatname>$] $<filename>$}

The same options relative to the format name are available than for
ShowDVI: supply no format name, a format name or '?' as a format name.
It works exactly the same.

The Start\_TeX macro is not fully asynchronous, if you queue {\em several}
request while the server is busy, you'll have to wait till your
request is accepted. Don't queue several requests!

\subsection{within MG}

The small example file in the installation section shows you how to
define some new commands to run the macros, and how you can bind some
keys to these newly created commands. You can load this file on demand
(just use "ESC-x load $<return>$ $<name-of-file>$"), or you can append
it to your {\tt s:mg-startup} file, which MG automatically reads upon
startup.

MG compiles your current buffer. The file in this buffer must end in
``tex''. 

The same options for starting the server are available than for
ShowDVI: supply no format name, a format name or '?' as a format name.
It works exactly the same way.

Note that the server is called fully asynchronously, thus you are
still able to stay in your favourite editor while the server is
compiling.  If you queue several requests (don't do this!), i.e.\ you
'tex-compile' while the server is still running and busy with another
file, you will get a short message in the status line when the server
finally accepts your request. 

\subsection{{\tt StartDVIprint} Macros}

This is currently available only within ShowDVI. You can bind any
function key to the {\tt StartDVIprint.sd} macros in a manner described
above. Then you'll be prompted for the first and the last page number
to be printed, and if you want to use draft mode or not. Then
DVIprint is called.

\section{Enhancements}

\subsection{smallTeX or BigTeX?}
You are not required to have virtex in the command search path. You
can set the Rexx variable {\tt virtex} (note the lowercase) to the
full path of the virtex executable. If this variable is not set, it
defaluts to {\tt virtex}. This allows you to switch on the fly between
then small and the big versions of TeX. For example, use ``{\tt rxset
virtex TeX:bin/big/virtex}'' to have the server use bigTeX.

\subsection{asynchronous requests}
All the Start\_TeX macros call the server, freeing the caller as soon
as the request is accepted. The caller {\em usually} does not have to
wait until compilation finishes. This is only partially true. The
server can only handle one request at a time. If you queue several
requests while the server is busy, the {\tt Start\_TeX} macro and thus
the caller will have to wait till compilation of the {\em previous}
request finishes. Only MG is an exception to this rule, thanks to it's
amazingly well-thought ARexx interface! Nice job, Mike!

\section{Known bugs and features}

\begin{itemize}

\item Simple NextError macros are supplied for editors. But they do no
work correctly when your documents consist of multiple files, because
the logfile is not analyzed deeply enough to determine the correct
file.

\item DME support: I'd like to add macros for Matthew Dillon's DME
editor, however as far as I know, this editor is lacking one feature
that the present macros require: DME cannot be called through ARexx
from other sources. DME can call ARexx, but the reverse is not true.
Thus I don't see how to write an appropriate {\tt TeXedit.rexx} macro
for DME. {\tt Start\_TeX.dme} would be no problem. You'll have to load
the logfile yourself.

\end{itemize}

Please report all bugs, ideas, suggestions to: \begin{center} Georg
He\ss mann\\ (hessmann@unipas.fmi.uni-passau.de)\\ or\\ J\"org H\"ohle\\
(hoehle@cs.uni-sb.de or Joerg\_Hoehle@SAARAG.ZER)\end{center}

\end{document}