\documentstyle[makeidx,twoside]{article}

\newcommand{\adjusttextheight}{
\setlength{\textheight}{29.7cm}         % DIN A4 paper height
\addtolength{\textheight}{-1.7cm}       % inaccessible space
\addtolength{\textheight}{-1in}
\addtolength{\textheight}{-\topmargin}
\addtolength{\textheight}{-\headheight}
\addtolength{\textheight}{-\headsep}
\addtolength{\textheight}{-\topskip}
\addtolength{\textheight}{-\footheight}
\addtolength{\textheight}{-\footskip}
}

\newcommand{\adjusttextwidth}{
\setlength{\textwidth}{21cm}    % DIN A4 paper width
\addtolength{\textwidth}{-1in}
\addtolength{\textwidth}{-\oddsidemargin}
\addtolength{\textwidth}{-1in}
\addtolength{\textwidth}{-\evensidemargin}
}



\setlength{\topmargin}{-0.5cm}
\setlength{\footskip}{0cm}
\adjusttextheight
\setlength{\evensidemargin}{0cm}
\setlength{\oddsidemargin}{0cm}
\adjusttextwidth


\newcommand{\Arcgsh}{{\em Arcgsh\/}}
\newcommand{\field}[1]{{\sf ``#1''}}
\newcommand{\menu}[1]{{\sf ``#1''}}
\newcommand{\button}[1]{{\setlength{\fboxsep}{1pt}\framebox{\sf #1}}}

\makeindex
\pagestyle{headings}
\flushbottom
\sloppy

\title{
{\bf ARCGSH}\\
Archiver GEM Shell\\
--- Version 3.5 ---
}

\author{
Dipl.-Inform. Rainer Klute\\
Vinckeplatz 5\\
D--4600 Dortmund 1\\
\normalsize klute@irb.informatik.uni-dortmund.de
}



\begin{document}

\thispagestyle{empty}

\maketitle

\newpage

\tableofcontents

\newpage




\section{Manual changes since version 3.2}

\begin{itemize}

\item New options \field{Repeat last dialog} and \field{Zoom boxes}. See
section \ref{options menu} (page \pageref{options menu}).

\item \menu{File} menu dialogs from can be invoked from the keyboard now. See
section \ref{Invoking File menu dialogs from the keyboard} (page
\pageref{Invoking File menu dialogs from the keyboard}).

\item Paragraph about parameter passing to a dependend program added. See
section \ref{Passing parameters to a dependend program} (page
\pageref{Passing parameters to a dependend program}).

\end{itemize}




\section{Copyright}\index{copyright}

\begin{center}
{\large \bf Copyright 1990 Rainer Klute}
\end{center}

Permission to use, copy, and distribute \Arcgsh\ and its documentation for
any purpose and without fee is hereby granted, provided that the above
copyright notice appears in all copies and that both that copyright notice
and this permission notice appear in supporting documentation. The file {\tt
ARCGSH.CFG} is explicitly excluded from the permission to distribute. I do
not make representations about the suitability of this software for any
purpose. It is provided ``as is'' without express or implied warranty.




\section{Introduction}\index{introduction}

\Arcgsh\ is a program that eases the calling of the well-known archivers Zoo,
Arc, LHarc and Shar. Furthermore the programs Uud and Uue are supported to
let you decode resp.\ encode binary files for handling with e-mail. You can
use your favorite file viewer and your favorite editor from \Arcgsh\ without
any need to leave the program.

With \Arcgsh\ it is no longer neccessary to start a
command-line-shell\index{command-line-shell}, ``cd'' to the directory where
your archive file is (or should be created), remember the various archiver
options (each archiver has its own set of options), type them in and
finally start the program. With \Arcgsh\ you can handle everything with GEM
objects: Dialog boxes let you select program options, and filenames are
comfortably selected using the GEM file selector box.

\Arcgsh\ serves especially well for uudecoding and unarcing any stuff
received from computer networks.  The programs {\tt ZOO.TTP, ARC.TTP,
LHARC.TTP, UUD.TTP, UUE.TTP,} and {\tt SHAR.TTP} are not part of the
standard \Arcgsh\ distribution. You have to get them elsewhere.

{\bf Important:} If you have suggestions on how to improve the program or
this manual\footnote{e.\,g.\ my ``german'' English} please let me know!




\section{The usual shareware plea}\label{The usual shareware
plea}\index{shareware}

You may use, copy and distribute \Arcgsh\ without having to pay anything.
However, if you find \Arcgsh\ useful and use it regularly you are encouraged
to transfer {\bf DM 30,--} to my bank account {\bf 4412\,46-300} at the {\bf
Postgiroamt Hannover, BLZ 250\,100\,30} in Germany. Alternativly you can
send me a cheque or money order made out in your own
currency\footnote{Making out the cheque or money order in your currency
minimizes the transfer costs.}.

A dialog box will pop up from time to time to remember you to pay the
shareware fee. You may well ignore it (resp.\ click it away) without having
to have a bad conscience. However, if you are so kind to send me the
shareware fee I shall tell you how you can get rid of those dialog boxes to
appear. Furthermore the xArgv and ARGV extended parameter passing schemes
will be activated for you. They allow you to pass long parameter strings to
dependend programs.

Please do not forget to mention your name and address (e-mail address
preferred)! I cannot get in contact with you if you forget them!




\section{Some general remarks}\index{general remarks}

\Arcgsh\ does its job by calling other programs. These programs are
subsequently referred to as {\bf dependent programs\index{dependent
program}.} The calling of programs follows a common scheme\index{programm
calling scheme}. Here only a short outline is given; detailed explanations
you can find below.

\begin{itemize}

\item Select the program you want to start from the \menu{File} menu,
e.\,g.\ \menu{Zoo ...}.

\item A dialog box will show up where you have to specify the program
parameters.  This can be done by clicking at buttons, selecting filenames or
typing text into fields.

Many text fields serve to hold a filename or folder name. If you
doubleclick at such a field the GEM file selector box will show up and let
you select a file resp.\ folder. If the field does not hold any text a
single click is sufficient to let the file selector box appear, otherwise a
single click only positions the text cursor into the field and allows
editing of the text.

To select a {\bf folder} just navigate the file selector box into that
folder, select any file or simply click at the \button{OK} button.

The selector box automatically appears to select a mandatory filename
parameter, e.\,g.\ the archive file handled by an archiver.

For further details on filename fields refer to section \ref{The file
selection handler} (page \pageref{The file selection handler}).

\item Execution of the selected dependent program starts when you click at the
\button{OK} button in the parameter dialog box.  If the dependent program is
of type TOS or TTP the screen is cleared before launching the program.  If
\Arcgsh\ does not know where the program resides it will display the GEM file
selector box asking you to locate the program.

\item Upon termination of the dependent program \Arcgsh\ will (optionally)
beep to let you know about the termination (very useful for long-running
programs).  The dependent program's output is (optionally) kept on the
screen until you press any key or click with the left mouse button.

{\bf Beware:} If an error occurred the dependent program itself may hold the
screen and ask you to type any key. In this case you will have to hit the
key twice: once for the dependent program and once for \Arcgsh.  If the
dependent program exits with a return code not equal to zero that code will
be displayed in an alert box.

\end{itemize}




\section{The Arcgsh menus}\index{\Arcgsh\ menus}

When you start up \Arcgsh\ you will see a menu bar like this:

\begin{tabular}{@{}|lllll|}
\hline
{\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \\
\hline
\end{tabular}

\noindent The subsequent paragraphs will explain the individual menus.



\subsection{The ``ARCGSH'' menu}\index{ARCGSH menu}

\begin{tabular}{@{}l@{}llll@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
\vline {\sf ~About~Arcgsh~...~} \vline & & & &\\
\cline{1-1}\\
\end{tabular}

\noindent This menu shows the entry \menu{About Arcgsh ...}. If you select
this menu item a dialog box will pop up showing you some general information
about the program and its author.



\subsection{The ``File'' menu}\index{file menu}

\newlength{\pl}
\settowidth{\pl}{\sf ~Other~program~...  p~}
\begin{tabular}{@{}l@{}l@{}lll@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& \vline \parbox{\pl}{\sf ~Zoo~...           \hfill z~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Arc~...           \hfill a~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~LHarc~...         \hfill l~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Shar~...          \hfill  ~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Uud~...           \hfill u~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Uue~...           \hfill  ~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Other~program~... \hfill p~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Show~file~...     \hfill s~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Edit~file~...     \hfill e~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Quit              \hfill q~} \hfill \vline & & &\\
\cline{2-2}\\
\end{tabular}

\noindent The \menu{File} menu is the one you will use to get the archivers
to work. The meaning of the menu items is as follows:

\begin{description}

\item[\menu{Zoo ...}, \menu{Arc ...}, \menu{LHarc ...}, \menu{Shar ...}:]
These are the names of the archivers \Arcgsh\ supports. If you want to start
one of them select it from the \menu{File} menu. A archiver-specific dialog
box will appear and you can select filenames, options, etc. Please refer to
the individual descriptions in section \ref{How to use the archivers} (page
\pageref{How to use the archivers})!

\item[\menu{Uud ...}, \menu{Uue ...}:] Uue is a program that encodes files in
such a way that it can be transferred to another host via electronic
mail\index{electronic mail}.  The encoded file will contain printable
characters only which will (hopefully) not be mangled by any mailers.

Uud on the other side allows you to decode uuencoded files. It is most
useful to decode file you have received via news or e-mail.

To uuencode or uudecode a file select one of these menu entries.  A dialog
box will pop up which allows you to select the various parameters of Uud
resp.\ Uue. For details refer to section \ref{Uud and Uue} (page
\pageref{Uud and Uue}).

\item[\menu{Other program ...}:] A dialog box will pop up and allows to
select any other program you want to execute. It is also possible to give
parameters to that program and also choose its working
directory\index{working directory}. For details refer to section
\ref{Calling other programs} (page \pageref{Calling other programs}).

\item[\menu{Show file ...}:] If you want to look at a file you can select
this menu item. However, \Arcgsh\ itself does not display the file but calls
another program, the {\bf user-defined pager}. You can use the pager program
you like best. For details refer to section \ref{The user-defined pager}
(page \pageref{The user-defined pager}).

\item[\menu{Edit file ...}:] You can use this menu entry to edit a file.
\Arcgsh\ does not have a built-in editor but allows you to use your own
favorite text editor. For details refer to section \ref{The user-defined
editor} (page \pageref{The user-defined editor}).

\item[\menu{Quit}:] terminates \Arcgsh.

\end{description}



\subsubsection{Invoking ``File'' menu dialogs from the
keyboard}\label{Invoking File menu dialogs from the
keyboard}\index{keyboard, invoking \menu{File} menu dialogs from the}

Most \menu{File} menu dialogs can also be invoked from the keyboard. Just
type the key that is shown at the right hand side of the menu item, e.\,g.
{\sf ``z''} to make the Zoo dialog box appear on the screen.



\subsection{The ``Configuration'' menu}\index{configuration menu}

\begin{tabular}{@{}ll@{}l@{}ll@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& & \vline {\sf ~Locate~Zoo~...~}       \hfill \vline & &\\
& & \vline {\sf ~Locate~Arc~...~}       \hfill \vline & &\\
& & \vline {\sf ~Locate~LHarc~...~}     \hfill \vline & &\\
& & \vline {\sf ~Locate~Shar~...~}      \hfill \vline & &\\
& & \vline {\sf ~Locate~Uud~...~}       \hfill \vline & &\\
& & \vline {\sf ~Locate~Uue~...~}       \hfill \vline & &\\
\cline{3-3}
& & \vline {\sf ~Configure~pager~...~}  \hfill \vline & &\\
& & \vline {\sf ~Configure~editor~...~} \hfill \vline & &\\
\cline{3-3}
& & \vline {\sf ~Save~configuration~}   \hfill \vline & &\\
\cline{3-3}\\
\end{tabular}

\noindent \Arcgsh\ calls several other programs, the so-called {\bf dependent
programs}\index{dependent program}. However, before \Arcgsh\ is able to
execute any program it must first know where this program resides on disk.
You can tell \Arcgsh\ the locations\index{locations} of the various programs
with the
\menu{Configuration} menu.

Let us suppose you want to locate the Zoo archiver. First you have to select
the \menu{Locate~Zoo~...} menu item. The GEM file selector box together with
the prompt {\sf ``Locate program ZOO.TTP''} will be shown\footnote{If you
have TOS~1.4 the prompt will appear in the file selector box; if you still
have an older TOS version it will be displayed in the menu bar.}. Now you can
navigate the file selector to the directory where {\tt ZOO.TTP} resides,
select {\tt ZOO.TTP} and click at the \button{OK} button. From now on
\Arcgsh\ knows where it can find {\tt ZOO.TTP}.

The menu items \menu{Configure pager ...} and \menu{Configure editor ...}
let you choose a program you want to use to look into files resp.\ to edit
files.

Example: You want to configure 1st Word Plus (filename {\tt WORDPLUS.PRG}) as
your editor. When you select \menu{Configure editor ...} a dialog box will
appear and --- if you do not have selected an editor yet --- immediately
afterwards the GEM file selector with the prompt {\sf ``Locate user-defined
editor''} pops up. The first line of the file selector shows you that only
files called {\tt EDITOR.PRG} will be displayed. As this is inappropriate to
select {\tt WORDPLUS.PRG} you have to change {\tt EDITOR.PRG} to {\tt
WORDPLUS.PRG}.  The file selector now shows all files named {\tt
WORDPLUS.PRG}, you can navigate it through your file system and select {\tt
WORDPLUS.PRG} as described above for {\tt ZOO.TTP}.

After you have selected the editor you can modify the command \Arcgsh\ uses
to call it. By default the editor will be called with one parameter: the
name of the file to be edited. This filename is represented by {\tt \%f} in
the \field{Parameters ...} text edit field. Say you want to give the
additional options {\tt -l~-w} to the editor. You have to change the text
edit field to {\tt -l~-w~\%f} then.

Of course you would not like to locate every program once again every time
you start \Arcgsh. The program locations can be saved on disk with the
\menu{Save configuration} menu item. \Arcgsh\ creates the file {\tt
ARCGSH.CFG} in the same directory as {\tt ARCGSH.PRG} and writes every
neccessary information into it.



\subsection{The ``Utilities'' menu}\index{utilities menu}

\begin{tabular}{@{}lll@{}l@{}l@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& & & \vline {\sf ~Copy~file~...~}     \hfill \vline &\\
& & & \vline {\sf ~Move~file~...~}     \hfill \vline &\\
& & & \vline {\sf ~Delete~file~...~}   \hfill \vline &\\
\cline{4-4}
& & & \vline {\sf ~Create~folder~...~} \hfill \vline &\\
& & & \vline {\sf ~Delete~folder~...~} \hfill \vline &\\
\cline{4-4}\\
\end{tabular}

\noindent \Arcgsh\ offers you a very simple tool for basic file manipulation.
You can copy, move\footnote{copy a file to another place and delete the
original} and delete a file, create and delete a folder by selecting the
corresponding menu item.  The file resp.\ folder names are requested by the
GEM file selector box.

\begin{description}

\item[\menu{Copy file}, \menu{Move file}:] These functions ask for the file
to be copied resp.\ moved with the GEM file selector box.  Then the file
selector box appears once again and asks for the destination filename. (As I
said, very simple.)

In case the file is to be copied/moved into another folder but with the same
basename\index{basename}\footnote{This is the ``essential'' last part of the
filename without drive and path specification.} it is sufficient to specify
the destination directory, not the full destination filename.  To do this
navigate the file selector box to the destination folder and simply click at
\button{OK}. You do not have to select or type any filename.

\menu{Copy file} and \menu{Move file} both preserve the creation date and
time of the file to be copied/moved as well as the file attributes
(read/write access or read-only access etc.)

Another word about the \menu{Move file} function:  If a file is to be moved
to another folder on the {\bf same} disk the \menu{Move file} function is
very efficient because no actual file copying has to be
performed.\footnote{The GEMDOS function Frename is used.}

\item[\menu{Delete file}, \menu{Create folder}, \menu{Delete folder}:] These
functions do what their names say.  The GEM file selector box lets you
specify the desired file/folder name.

\end{description}



\subsection{The ``Options'' menu}\label{options menu}\index{options menu}

\begin{tabular}{@{}llll@{}l@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& & & & \vline {\sf ~Show~command~line~}     \hfill \vline \\
& & & & \vline {\sf ~Hold upon termination~} \hfill \vline \\
& & & & \vline {\sf ~Beep upon termination~} \hfill \vline \\
\cline{5-5}
& & & & \vline {\sf ~Repeat last dialog~}    \hfill \vline \\
& & & & \vline {\sf ~Zoom boxes~}            \hfill \vline \\
\cline{5-5}\\
\end{tabular}

\noindent By use of this menu you can influence the behaviour of \Arcgsh\
when a dependent program\index{dependent program} --- e.\,g.\ an archiver
--- is executed. Each of these options can be {\bf active} or {\bf
inactive}. An active option is indicated by a check mark at the left side of
the option text in the menu.  The meaning of the options is as follows:

\begin{description}

\item[\menu{Show command line\index{show command line}}:] If this option is
active \Arcgsh\ displays the command line that is used to call the dependent
program.  This option is ignored for programs ending with {\tt .PRG} or {\tt
.APP}.

\item[\menu{Hold upon termination\index{hold upon termination}}:] If this
option is active \Arcgsh\ holds the screen before returning to the \Arcgsh\
desktop. This is useful to see the messages the dependent program has
written to the screen. Press any key or click with the left mouse button to
return to the \Arcgsh\ desktop. This option is ignored for programs ending
with {\tt .PRG} or {\tt .APP}.

\item[\menu{Beep upon termination\index{beep upon termination}}:] If this
option is active \Arcgsh\ beeps when the dependent program terminates. This
is useful when the dependent program runs for a long time and you do not
want to watch the screen all the time to know whether it has terminated.

\item[\menu{Repeat last dialog\index{repeat last dialog}}:] If this option
is active \Arcgsh\ automatically repeats the dialog for the last executed
function. This is especially useful when an archiver has to be called several
times in succession. The cycle is stopped when the \button{Cancel} button of
the dialog box is clicked.

\item[\menu{Zoom boxes\index{zoom boxes}}:] If this option is active a
growing box is drawn when a window is opened and a shrinking box when it is
closed. This was \Arcgsh's normal behavior before version 3.5. When you
disable this option the ``zoom'' boxes are not drawn and you will get a
little speed gain in the dialogs.

\end{description}

The current options setting can be saved with \menu{Save configuaration} in
the \menu{Configuration} menu.




\section{How to use the archivers}\label{How to use the archivers}

The calling of archivers follows a common scheme: First you select the
archiver you want to use from the \menu{File} menu. Then a dialog box
specifically designed for that particular archiver will pop up and you can
specify archiver parameters by clicking at buttons and selecting filenames
with the GEM file selector box. When you have selected all the parameters
you need click at the \button{OK} button. \Arcgsh\ will clear the screen and
run the program with the parameters you specified\footnote{Passing
parameters to an archiver or to a dependend program in general can be done
in different ways. See section \ref{Passing parameters to a dependend
program} (page \pageref{Passing parameters to a dependend program}) for
details.}.  If you have changed your mind not to execute it click at the
\button{CANCEL} button.


We will consider the different archivers now in some detail by use of
examples. However, you should remember that this manual is about \Arcgsh\
and not about the archivers as such. I strongly recommend to read the
original archiver documentations!



\subsection{Zoo}\label{Zoo}\index{Zoo}

\Arcgsh\ works together with Zoo version 2.01g ported to the Atari ST by
Daan Jitta.\index{supported Zoo version}



\subsubsection{Extracting a whole Zoo archive file}\index{extracting a whole
Zoo archive file}

As our first example we want to extract a whole Zoo archive file. Its name
is {\tt EX1.ZOO}.

When you have selected the \menu{Zoo ...} menu item from the \menu{File}
menu the Zoo dialog box will pop up and allows you to enter Zoo parameters.
The first parameter you have to select is the Zoo archive file. You can do
that with the GEM file selector box which will appear automatically.
Navigate the file selector to the directory where {\tt EX1.ZOO} is stored
and select the archive file. The file selector box disappears and the file
name is shown in the \field{Archive} field.

To extract all files from the archive select the \button{e~~extract files}
button. You will notice that on the right hand side of the dialog box a lot
of {\sf ``Zoo modifiers''} will appear. By use of these modifiers you can
influence the Zoo extraction process.

For now we will not select a Zoo modifier but simply click at \button{OK}.
Zoo starts up, extracts every file from the archive and writes it to the same
directory where {\tt EX1.ZOO} is in.



\subsubsection{Extracting particular files from a Zoo archive
file}\index{extracting particular files from a Zoo archive file}

Consider now that we do not want to extract {\bf all} the files stored in
{\tt EX1.ZOO} but only those with a particular name, say with the extension
{\tt .C}.

Recall the Zoo dialog box by selection of the \menu{Zoo ...}\ menu item. From
the previous call the Zoo archive file is still selected so the GEM file
selector will not appear this time. Now we have to specify the files we want
to extract: Move the text cursor to the \field{Filename} field, type {\tt
*.c} into it, then click at \button{OK}.

In many cases the \field{Filename} field is sufficient to specify the files
you want to extract from an archive file. However, if you want to specify
more files you can click at the \button{more files...} button. This will make
another dialog box --- the file selection handler --- to appear. Here you
have more fields to select filenames. You can even redirect standard input,
standard output and select a working directory for the Zoo program. A
detailed description you will find in section \ref{The file selection
handler} (page \pageref{The file selection handler}).



\subsubsection{Extracting into another directory}\index{extracting into
another directory}

In the examples above the destination of extraction has always been the
directory where the archive file itself was in. Now we want to extract into
another directory.

When Zoo is executing it has a ``current directory''\index{current
directory} or ``working directory''\index{working directory}. Files that
have no explicit drive\index{drive specification} and directory
specification\index{directory specification}\footnote{In {\tt
A:$\backslash$FOO$\backslash$BAR$\backslash$EX1.ZOO} the part {\tt
A:$\backslash$} is the drive specification and {\tt
FOO$\backslash$BAR$\backslash$} is the directory specification.} are
addressed relative to this directory.  When Zoo extracts files it (normally)
creates them relative to the current directory.\footnote{A special case is
when files are stored in the archive with an absolute pathname (except drive
specification). This should be avoided.} The default current directory is
the folder the archive is in.  If we want to extract into another folder we
have to change the current directory. This can be achieved by clicking at the
\button{more files...} button in the Zoo dialog box.

The dialog box that pops up now is the file selection handler. It is
described in detail in section \ref{The file selection handler} (page
\pageref{The file selection handler}). Here only the \field{Working
directory} field is of interest. Click at this field, see the GEM file
selector box appear, and select a directory to be the working directory. To
select it move the file selector {\bf into} that directory, then click at
\button{OK}.

A click at the \button{OK} button of the file selection handler makes it
disappear. Proceed as described above now and Zoo will extract into the
selected directory.



\subsubsection{Adding files to a Zoo archive}\index{adding files to a Zoo
archive}

To add files to a Zoo archive you have to select the
\button{a~~add~files} button. If the Zoo archive file does not yet exist it
will be created. The files you want to add to the archive can be given with
``wildcards''\index{wildcards}. That is, if you want to add all files with
the extension {\tt .C} you move the file selector box to the directory in
question, type {\tt *.C} and click at the \button{OK} button.

If you specify files with the GEM file selector box you will always get a
full pathname with drive id and directory identification. However, in most
cases you do not want to store files with their full pathnames in the Zoo
archive. For example you have a directory {\tt LETTERS} somewhere deep down
in your folder path and now you want to save all those letters in a Zoo
archive. I suppose you only want to have the pure filenames of the letters
in your Zoo archive, say {\tt THOMAS.DOC, SUSAN.DOC,} and {\tt CINDY.DOC}
instead of their full filenames.

Well, \Arcgsh\ also thinks so. It tries to be clever and guesses what you
would like as the working directory\index{working directory} for Zoo. Why a
working directory? Well, as explained above Zoo accesses files given without
an absolute path relative to its working directory. This is of course also
true when {\bf adding} files to an archive. In the above example \Arcgsh\
would set Zoo's working directory to the letters directory {\tt
(...$\backslash$LETTERS)} assuming you have selected {\tt
...$\backslash$LETTERS$\backslash$*.*} as files to be added.

How does \Arcgsh\ proceed to determine an appropriate working directory? It
looks at all those filenames that are given as full pathnames (with drive id
and path specification) and determines their common prefix\index{common
prefix}. For instance the files {\tt A:$\backslash$FOO$\backslash$FILE1,
A:$\backslash$FOO$\backslash$FILE2,} and {\tt
A:$\backslash$FOO$\backslash$BAR$\backslash$FILE1} have {\tt
A:$\backslash$FOO$\backslash$} as their common prefix. This common prefix is
chosen as the working directory for Zoo, and \Arcgsh\ hands the specified
files over to Zoo with their prefixes stripped off. In the example above the
files are not stored as {\tt A:$\backslash$FOO$\backslash$FILE1,
A:$\backslash$FOO$\backslash$FILE2,} and {\tt
A:$\backslash$FOO$\backslash$BAR$\backslash$FILE1} but as {\tt FILE1, FILE2,}
and {\tt BAR$\backslash$FILE1.}

However, this mechanism is not always appropriate. Consider the case when we
want to archive all files in the directory {\tt
A:$\backslash$FOO$\backslash$BAR} but we want them to be stored {\bf with}
{\tt BAR} before the filename. We can achieve this by specifying the working
directory explicitly with the file selection handler: We set the working
directory to {\tt A:$\backslash$FOO$\backslash$} and specify {\tt
BAR$\backslash$*.*}.  {\bf Whenever the working directory is selected
explicitly by the user \Arcgsh\ will leave all selected filenames as they
are.}



\subsubsection{Adding complete file trees to a Zoo archive}\index{adding
complete file trees to a Zoo archive}

A complete file system can be added to a Zoo archive by use of the {\sf
``//''} modifier. This modifier is not available in the original Zoo program
but only in the Atari ST port done by Daan Jitta. It tells Zoo the
following: If one of the selected files is a directory
recursively\footnote{{\bf Recursively} means that all subdirectories are
added, all subsubdirectories contained in the subdirectories and so on.} add
all its files and subdirectories to the archive.

If the {\sf ``//''} option is not set Zoo ignores directories.



\subsubsection{Zoo modifiers}\index{Zoo modifiers}

The behavior of Zoo commands can be influenced by the the use of {\bf Zoo
modifiers.} When you select any Zoo command button \Arcgsh\ will display the
modifiers that are available with this particular command.

In principle you are free to choose any combination of modifiers.  However,
there are some cases where some modifiers are either mutually exclusive or
have to be specified either together or not at all.  \Arcgsh\ does not check
for those cases. It will leave this task to Zoo.

A special field in the \field{Zoo modifiers} box is the \field{Number}
field. You can insert any numeric parameter(s) to Zoo into this field.  This
is neccessary in connection with generation limits and corrupted archives.
Please refer to the Zoo reference manual!



\subsubsection{The TMPDIR field}\index{TMPDIR field}

In the \field{TMPDIR} field you can specify a directory where Zoo should
create temporary files during packing.\footnote{It is committed to Zoo in
the environment variable TMPDIR.} This directory should be on a fast medium
like RAM disk or hard disk.


\subsection{Arc}\label{Arc}\index{Arc}

\Arcgsh\ works together with Arc 6.02 although the really important
functions are also available if Arc 5.21 is used.\index{supported Arc
versions}

The Arc dialog box pops up when you select the \menu{Arc~...}\ menu item from
the \menu{File} menu. Its handling is similar to the handling of the Zoo
dialog box. In fact it is even easier. Therefore the instructions given in
this section do not go so much into detail as the section before. If you are
not able to understand anything read the instructions about the Zoo archiver
in section \ref{Zoo} (page \pageref{Zoo}).



\subsubsection{Extracting a whole Arc archive file}\index{extracting a whole
Arc archive file}

\begin{itemize}

\item Select the archive file to be extracted (extension {\tt .ARC}) into the
\field{Archive} field.

\item Click at the \button{Extract} button in the \field{Arc commands} field.

\item Optionally select one or more options from the \field{Arc options}
field.

\item Click at the \button{OK} button. Now {\tt ARC.TTP} is executed and
extracts the files into the same directory the archive file is in.

\end{itemize}



\subsubsection{Extracting particular files from an Arc archive
file}\index{extracting particular files from an Arc archive file}

If you do not want to extract {\bf all} files from an archive you have to
specify the names of the files you want to extract.

This can be done in the \field{Filename} field or in the file selection
handler. The latter will appear if you click at the \button{more~files...}
button.

Filenames may be given with wildcards\index{wildcards}. So it is possible to
specify {\tt *.C} as a filename which will lead to extraction of all files
with the extension {\tt .C}. It is not neccessary to specify all of them
separately, e.\,g.\ {\tt FOO.C, BAR.C, ...}



\subsubsection{Extracting into another directory}\index{extracting into
another directory}

In addition to the above steps you have to specify the directory where the
extracted files should be created.

It can be given in the \field{Working directory} field in the file selection
handler. Another possibility is to prepend the names of the files to be
extracted with the full drive and directory specification. So it is
equivalent either to specify {\tt A:$\backslash$FOO$\backslash$BAR} as the
working directory and {\tt *.C} as files to be extracted or to specify {\tt
A:$\backslash$FOO$\backslash$BAR$\backslash$*.C} as files to be extracted.



\subsubsection{Adding files to an Arc archive}\index{adding files to an Arc
archive}

To add files to an Arc archive you have to select the \button{Add} command
button. If the Arc archive file does not yet exist it will be created. The
files you want to add to the archive can be given with
wildcards\index{wildcards}.

Arc always stores files {\bf without} drive or directory identification no
matter what you have specified.



\subsubsection{Adding complete file trees to an Arc archive}\index{adding
complete file trees to an Arc archive}

Archiving of subdirectories is possible from Arc 6.02 on. If you select the
{\sf ``Include subdirectories''} option a {\bf whole} directory tree is
archived. The directory name must be specified like a normal filename. {\bf
Attention:} There is no chance to archive particular files from a
subdirectory. Similarly you can either extract the {\bf whole} subdirectory
tree or nothing at all.



\subsubsection{The ARCTEMP field}\index{ARCTEMP field}

In the \field{ARCTEMP} field you can specify a directory where Arc should
create temporary files.\footnote{It is committed to Arc in the environment
variable ARCTEMP.} This directory should be on a fast medium like RAM disk or
hard disk.



\subsection{LHarc}\label{LHarc}\index{LHarc}

The LHarc archive format has become more and more popular because it offers
a very good compression factor. However, if you want to work with LHarc you
should be aware of a lot of problems:

\begin{itemize}

\item The format of LHarc archive files\footnote{LHarc archives can be
recognized at their extension {\tt .LZH}.} is not unique. I have seen at
least three different LHarc formats.

\item There are several programs called {\tt LHARC.TTP} available which have
different commands, different options and different command line formats.

\item The documentation is in Kanji.

\item The program is not the fastest.

\end{itemize}

\Arcgsh\ works together with LHarc 1.02 based on MSDOS LHarc 1.13c. It was
ported to the Atari ST by Bill Shroka (bjsjr@ncoast.org).\index{supported
LHarc version} This LHarc implementation is compatible with the UNIX LHarc
and is said to be the most stable for the ST.

I shall not write a more detailed documentation here before a) I get the
LHarc documentation in a form I can read (e.\,g.\ not Kanji) and b) the
situation in the ``LHarc market'' becomes more stable. I simply implemented
an LHarc interface in \Arcgsh\ and that's it.  Try it out and see whether it
works for you or not.  If LHarc failes please do not blame \Arcgsh\ or even
me!



\subsection{Shar}\index{Shar}

Under the UNIX operating system there are so-called shell
archives\index{shell archive}. They are created by the program {\em shar\/}
and usually contain pure text files.  For extraction the Bourne Shell, {\em
/bin/sh,\/} is used.  This is of course not possible on the Atari ST.  So I
hacked together (not more than that) a Shar program for the ST that also has
an ``unshar''\index{unshar} component. For this I used two already existing
versions of Shar:  one I found on a local UNIX machine and one available for
the Atari ST.  The former one did not have an unshar component, and the
latter did not have a good directory support.  So I built my own one and
adopted \Arcgsh\ to it.\index{supported Shar version}

   This Shar version is not included in the \Arcgsh\ distribution but you
should be able to get it through the same channel you got \Arcgsh.  If you
already have a UNIX compatible Shar running on your ST you should at least
be able to {\bf create} Shar archives --- extracting is another matter.

The Shar dialog box pops up if you select the \menu{Shar ...}\ menu item
from the \menu{File} menu. You will see the following fields:

\begin{description}

\item[\field{Archive}:] The name of the Shar archive is specified here.
Default extension is {\tt .SH} but you may change it.

\item[\field{Create}, \field{extract}, \field{overwrite}:] Select whether you
want to {\bf create} a new Shar archive (this is the default) or {\bf
extract} an existing one.  {\bf Overwrite} is the same as {\bf extract} but
with overwriting already existing files.

\item[\field{Filename}:] Filenames to be included in the Shar archive may be
specified here or in the file selection handler.  Directory names may also
be given, but must not have a backslash {\tt $\backslash$} at the end. The
easiest way to select a directory name is to select a file from that
directory with the GEM file selector box and then edit the filename ``by
hand''.

\item[\field{more files ...}:] A click at this button invokes the file
selection handler. The specification of a working directory\index{working
directory} is essential upon extraction.  Files without an absolute path are
written to this directory.

\item[\field{clear ...}:] Clears all entries in the file selection handler.

\item[\field{Shar options}:] Shar options may be selected here.  Refer to
the documentation of your Shar.

\end{description}




\section{Uud and Uue}\label{Uud and Uue}\index{Uud}\index{Uue}

The program pair Uud and Uue help to transfer arbitrary files through a
computer network\index{computer network}. Uue takes a file as input and
generates one or more output files. The output files consist of printable
characters only and can be sent by electronic mail\index{electronic mail}
etc. The receiver of the ``uuencoded''\index{uuencode} file(s) makes use of
Uud to generate the original file.

\Arcgsh\ works together with Uud 3.4 (25.11.1988)\index{supported Uud
version} and Uue 3.1 (6.8.1987)\index{supported Uue version}.



\subsection{Uud}\index{Uud}

\begin{description}

\item[\field{File to be uudecoded}:] The file to be uudecoded should have an
extension {\tt .UUE} for a single file or {\tt .UAA} for the first one of a
sequence of files.

\item[\field{Source directory}, \field{Target directory}:] If these
directories are specified Uud reads the input file(s) from the source
directory and writes the generated file to the target directory.

\end{description}



\subsection{Uue}\index{Uue}

Usually Uue generates one {\tt .UUE} file from the file to be uuencoded.
However, if the button \button{Generate multiple file output ...} is
selected Uue will create several output files with extensions {\tt .UAA,
.UAB, ..., .UZZ.} To change the maximum number of lines per file proceed as
follows:  Select the \button{Generate ...} button, then click at the field
with the max. number of lines per file and edit the number as you like. The
default of 500 line seems appropriate since the individual output files will
be smaller than 32 KB and most mailers can handle files of that size.




\section{The user-defined pager}\label{The user-defined
pager}\index{user-defined pager}

The user-defined pager allows you to look at a file without having to leave
\Arcgsh.  It is not a built-in function of \Arcgsh. Instead you are free to
choose a ``pager program'' which actually displays the file.  (I use and
recommend the public domain program {\tt LESS.TTP} by Moshe Braner.)

When you select the \menu{Show file ...}\ menu item from the \menu{File}
menu the GEM file selector box appears and asks you for the name of the file
to be shown. If the pager program has not yet been selected a dialog box
appears to let you do so (see description of the \menu{Configuration} menu).




\section{The user-defined editor}\label{The user-defined
editor}\index{user-defined editor}

The user-defined editor allows you to edit a file without having to leave
\Arcgsh. It is not a built-in function of \Arcgsh. Instead you are free to
choose a text editor with which you actually edit the file.

When you select the \menu{Edit file ...}\ menu item from the \menu{File}
menu the GEM file selector box appears and asks you for the name of the file
to be edited. If the editor has not yet been selected a dialog box appears
to let you do so (see description of the \menu{Configuration} menu).




\section{Calling other programs}\label{Calling other programs}\index{calling
other programs}

Any other program than those mentioned above may be called by the menu item
\menu{Other program ...}.  In the dialog box you must enter the filename of
the program. Of course you can also enter program parameters, you can select
a working directory, and you can redirect standard input and standard
output.

Most programs take filenames as parameters. Therefore the GEM file selector
box will appear if you doubleclick at the \field{Parameters} field.  You
may e.\,g.\ first select a filename and then edit the field appropriately.

If no working directory\index{working directory} is selected explicitly with
the file selection handler the directory of the dependent program is taken
as the working directory. {\bf Note:} If a GEM program needs a resource file
it usually tries to load it from the working directory and failes if the
working directory is not the directory the program itself is located.
Therefore no working directory should be selected if such a program is to be
started.




\section{The file selection handler}\label{The file selection
handler}\index{file selection handler}

The file selection handler\index{file selection handler} is a dialog box
(and some program logic behind it) that allows you to specify a lot of
filenames or other text to be given to a dependent program\index{dependent
program} as parameters. Additionally you can redirect standard input and
standard output, and you can choose the working directory\index{working
directory} of the dependent program.

When the file selection handler appears you can see the following items:

\begin{description}

\item[Lines:] These lines are usually used to enter filenames. However, you
are free to enter any other text you want.

If you click at an empty line the GEM file selector will appear. You can now
navigate it to any directory and select a file from it. The name of the
selected file will be displayed with drive id and directory specification in
that line. If you like you can edit the line ``by hand''.

A filename too long to fit into the available space will be abbreviated at
the front by three dots so that you can see the last part of the filename
only. Abbreviated filenames are not editable. If you want to change the
contents of such a line you have to click at it. The GEM file selector will
appear again and you can select a file with a name short enough to fit into
the line. Then you can edit the line as you like.

The mechanisms described here also apply to the fields described below.

\item[\field{Standard input}:] Here you can specify a file the dependent
program should use as standard input\index{standard input}.

\item[\field{Standard output}:] Here you can specify a file the dependent
program should use as standard output\index{standard output}.

\item[\button{Append}, \button{Create}:] These buttons are useful when you
have selected a file for standard output. They specify whether the dependent
program should {\bf append} its output to an already existing file or if
the file used as standard output should be {\bf created} --- possibly
overwriting an already existing file.

\item[\field{Working directory}:] Here you can specify a working
directory\index{working directory} for the dependent program.

\item[\button{OK}:] A click at this button leaves the file selection handler.

\item[\button{CANCEL}:] This button also offers you a way to leave the file
selection handler. In contrast to the \button{OK} button all selections
and/or modifications you have made will be discarded.

\item[\button{Clear all}:] This button clears all filename fields.

\end{description}




\section{Passing parameters to a dependend program}\label{Passing parameters
to a dependend program}\index{parameter passing}

When you execute a program in many cases you hand over one or more
parameters.  They tell the program what to do. A good example are the
archivers supported by \Arcgsh: They take parameters that a) tell what to do
(e.\,g.\ add files to an archive, extract from an archive) and b) on what
files to operate (e.\,g.\ the archive, archive elements or files).

All these parameters are handed over to the dependend program as a string of
characters on a so-called {\em command line}\index{command line}. However,
there is a tight TOS limitation that restricts the total parameter string
length to 125 characters. If you specified more characters on the command
line they are gracelessly clipped off.

Of course there is a need to pass more than 125 characters to a program,
e.\,g.\ when an archiver is called with a lot of files that should be
processed. Consequently procedures have been worked out by several people to
achieve this.  These {\em extended parameter passing schemes}\index{extended
parameter passing scheme} work as follows: The calling program communicates
the long parameter string to the callee by use of an certain environment
variable\index{environment variable}. The called program reads its
environment and checks for the variable that indicates an extended parameter
string. If it finds that variable it uses it. Otherwise it takes its
parameter from the command line. It is clear that both caller and callee
must support the extended parameter passing scheme\index{extended parameter
passing scheme}.

The most common extended parameters passing schemes\index{extended
parameters passing scheme} are the {\em xArgv\/}\index{xArgv parameter
passing scheme} and the {\em ARGV\/}\index{ARGV parameter passing scheme}
scheme. \Arcgsh\ supports both these schemes and can therefore hand over
more than 125 characters to a dependend program that also supports the xArgv
or ARGV parameter passing scheme. The archivers Arc, Zoo, and LHarc are
examples for such programs.

\Arcgsh\ supports xArgv and ARGV for registered users only. On how to
register see section \ref{The usual shareware plea} (page \pageref{The usual
shareware plea})!




\section{Automatic startup --- installing Arcgsh as a desktop
application}\index{automatic startup}\index{desktop application}

A very common situation is that you are working with the GEM desktop
browsing through your files. Now suppose you have an archive file of any
kind in one window and want to have a quick look at its contents (or do
something else with it). If it were a text file you could doubleclick at it
and view it with the desktop's built-in file viewer.

This is of course inappropriate for an archive file. What you could do is
open another window, navigate to the directory where you have \Arcgsh\
installed, doubleclick at {\tt ARCGSH.PRG}, select the appropriate archiver
from the \menu{File} menu, navigate the file selector box to the directory
where your archive resides, select the ``list'' command for the archiver and
execute the latter.

However, \Arcgsh\ in cooperation with the GEM desktop\index{GEM desktop}
offers you a much simpler method\footnote{This method works well under
TOS~1.4\index{TOS 1.4} (``Rainbow TOS''\index{Rainbow TOS}). If you do not
yet have TOS~1.4 you should get it --- it has a lot of advantages above
former TOS versions. To make \Arcgsh's autostart feature work under
pre-TOS~1.4 versions you must include the directory where \Arcgsh\ is
installed in the PATH environment variable\index{PATH environment variable}.
However, this is not trivial from the GEM desktop and can only be achieved
with a dedicated program run from the AUTO folder. I think the free program
GEMBOOT by Konrad Hahn does so.}:  You can tell the GEM desktop to install
\Arcgsh\ as a desktop application\index{desktop application}.  After having
done that all you need to do is doubleclicking at the archive file. \Arcgsh\
will automatically start up and display the right dialog box with the name
of the archive file already filled in. Simply select a command button,
e.\,g.\ ``list'', and run the archiver.

You can do the same with a uuencoded file\index{uuencoded file}:
Doubleclicking on a file with the extension {\tt .UUE} causes \Arcgsh\ to
start and display the Uud parameter box with the name of the uuencoded file
filled in.

Here is a short explanation on how to install \Arcgsh\ as a desktop
application\footnote{The strings {\sf ``EXTRAS'', ``Install application'',}
and {\sf ``Save work''} cited in this paragraph are only roughly translated
from the corresponding strings of my German desktop. They may be different
on a real English desktop. They are surely different on other national
desktop versions. If in doubt consider your Atari ST User's Manual.}:

\begin{enumerate}

\item On the GEM desktop select the file {\tt ARCGSH.PRG}.

\item Move the mouse cursor to the \menu{EXTRAS} menu and select the
\menu{Install application} menu entry.

\item Type {\tt ZOO} into the {\sf file type} field and click at the
\button{OK} button.

\item Select the \menu{Save work} menu entry from the \menu{EXTRAS} menu.
This causes the file {\tt DESKTOP.INF}\index{DESKTOP.INF} to be written to
the root directory of your boot disk now and will make \Arcgsh\ permanently
installed as a desktop application.

\end{enumerate}

What you have done so far is installing \Arcgsh\ as an application for Zoo
archive files. Whenever you doubleclick at a file with extension {\tt .ZOO}
\Arcgsh\ will start up and display the Zoo dialog box. If you go on and
install \Arcgsh\ in the same way as described for the other archivers and
Uud, specifying the extensions {\tt .ARC, .LZH} and {\tt .UUE}, you will fail.
The reason is a limitation of the GEM desktop which forgets about an earlier
specified extension if a new one is given for an installed application.

To circumvent this problem you have to edit the file {\tt
DESKTOP.INF}\index{DESKTOP.INF} with a text editor after you have performed
the above mentioned steps. Somewhere in {\tt DESKTOP.INF} you will find a
line like

\begin{quote}
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.ZOO@}
\end{quote}

Here {\tt "C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG"} is
the full pathname of the \Arcgsh\ program. It may well be different on your
installation. The string {\tt "*.ZOO"} specifies the files for which
\Arcgsh\ should start up automatically.

Copy this line three times and change the string {\tt ZOO} within the copies
to {\tt ARC, LZH,} and {\tt UUE,} resp. Now you should have

\begin{quote}
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.ARC@}\\
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.LZH@}\\
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.ZOO@}\\
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.UUE@}
\end{quote}

Save {\tt DESKTOP.INF} to disk and reboot the system. After that \Arcgsh\
automatically starts up for Arc, LHarc, and Zoo archive files and uuecoded
files with the extension {\tt .UUE.}




\section{Limitations}\index{limitations}
\begin{itemize}

\item LHarc is troublesome. Read section \ref{LHarc} (page \pageref{LHarc})
for details!

\item A configuration file generated with \Arcgsh\ versions older than 3.0
cannot be used with this version. You have to establish a new version from
scratch.

\item A filename may not be longer than 119 characters. This is the filename
length the GEM desktop can handle. \Arcgsh\ may well bomb on longer
filenames. If you need \Arcgsh\ to support longer filenames please send me a
note!

\item The index of this manual is poor. Please share your ideas on how to
improve it!

\item Autostarting \Arcgsh\ under TOS versions older than
TOS~1.4\index{TOS 1.4} only works if the \Arcgsh\ directory is included in
the PATH environment variable.

\end{itemize}




\printindex
\end{document}
