\newcounter{Version}
\setcounter{Version}{10}                % update at each new release
\newlength{\Cmdwidth}                   % used to indent command lists
\setlength{\Cmdwidth}{8em}              % set by eyeball
\documentstyle[twoside,12pt]{article}
\pagestyle{headings}
%\makeindex                             % someday
\load{\footnotesize}{\sf}               % Load smaller
\load{\small}{\sf}                      % Sans-Serif fonts
\hyphenation{Menu-Cat}
\renewcommand{\labelitemii}{$\bullet$}  % Second-level \item
\parskip 3pt plus 2pt minus 1pt                 % this looks better than
\parindent 20pt                                 % the standard style
%
% Define textual macros:
% \_                    not correct in standard TeX for big fonts
%
% The following are used to switch fonts for special Uemacs terms.
%
% \Name{xxx}            Command name (changes font to Sans-Serif)
% \Text{xxx}            Display text (changes font to typewriter)
% \Nameitem{xxx}        \item[] if contents are command names.
%                       (Will put name in index eventually)
%
\renewcommand{\_}{{\tt \char95}}
\newcommand{\Text}[1]{{\tt #1}}
\newcommand{\Name}[1]{{\sf #1}}
\newcommand{\Nameitem}[1]{\item [\Name{#1}]}
%
% Environment for command lists.  Like \begin{description}, but
% with special indentation.  Usage:
% \begin{cmdlist}
%   \Nameitem{xxx} Explanation of item xxx.
%   \Nameitem{yyy} Explanation of item yyy.
% \end{cmdlist}
%
\newenvironment{cmdlist}{%
  \list{}{%                                     % homemade description envt.
    \setlength{\rightmargin}{0em}               % on either side.
    \setlength{\labelwidth}{\Cmdwidth}  % \item indentation
    \setlength{\labelsep}{1em}                  % between item and text
    \setlength{\leftmargin}{\labelwidth}        % Indent by indentation
    \addtolength{\leftmargin}{\labelsep}        %   + a little space
    \renewcommand{\makelabel}[1]{##1\hfill}     % Add \index command someday
  }
}{\endlist}

\begin{document}
\author{\
Steve D. Poling\\
701 Livingston NE\\
Grand Rapids, MI 49503
}
\title{\
  MenuCat\\[3ex]
  {\large Easy to use Cataloger} \\
  {\large for} \\
  {\large The Amiga } \\
}
\maketitle
\abstract{
This document describes MenuCat,
a public-domain disk cataloger. This document is a reference manual
for users already familiar with the Amiga interface.

This is MenuCat Version \arabic{Version}.
}
\vfill
\vfill                  % Set this 2/3 down on the page.
\begin{quotation}
This document was produced using the \LaTeX{} document
preparation system developed by Leslie
Lamport.  All page composition and make-up was performed
by \TeX,\footnote{\TeX{} is a registered trademark of the
American Mathematical Society.} the typesetting system developed by
Donald E. Knuth at Stanford University.
\end{quotation}
\vfill
\newpage
\tableofcontents
\newpage
\section{Introduction}
This document describes MenuCat,
a public-domain disk cataloger. This reference manual is intended
for users already familiar with the Amiga interface.

This is MenuCat Version \arabic{Version}.

\subsection{General Description}

MenuCat is a program which collects data from diskettes.  This
data is all of the files residing on disks and how one can find each file.
The user should process all the disks in that person's library so every
data or program file in the user's library may be quickly found.  

Since this exposes the user's entire software assets to MenuCat, the user's
responsibility is to verify that MenuCat is performing correctly.  The user
must realize that running MenuCat exposes the user's entire software assets to
some element of risk.  Pretty grim stuff, but MenuCat or a program
like it could be the carrier of an {\bf extremely} virulent software plague. 

Despite the last paragraph, MenuCat can be extremely useful.  The output of
MenuCat is a list of every file and where to find it.  

\subsection{Orientation and Scope}

This manual intended to reach the typical Amiga hobbyist.  This document 
assumes the user is conversant in the operations of the Amiga personal
computer. One should have no problem selecting a menu item from the Amiga pull
down menu-bar.   The user should have no problem ``clicking'' on a gadget in a
requester. 

The user should be able to read this document and be able to operate MenuCat to
catalog micro-floppy diskettes.

\subsection{Overview of MenuCat}

When run, MenuCat opens a window on the standard Workbench screen and sets up a
menu structure.  MenuCat receives as input a micro-floppy diskette inserted into
the Amiga drive unit DF1.  MenuCat then produces a sequence of records which is
useful in identifying where data and program files may be found among the disks
of the user's library.

% \subsection{Guide to Use of Manual}
% i don't know what to say here.

\section{User Environment and Interfaces}

MenuCat does not run in a vacuum.  It interacts with the user as described
below.  MenuCat also makes some assumptions about its hardware environment.  
These assumptions are described in following subsections.

\subsection{User--Seen Data Flow}

The user will only see one of two messages on MenuCat's screen: either a message
that MenuCat is processing or finished with a disk.

If the user runs MenuCat with output routed to the standard output channel, the
user will see a sequence of records printed on the CLI window from which 
MenuCat was run.  These records are of the following form:\\ 
\medskip
{\it filename white-space path}\\
\medskip
The user will see the one such record for each file on the disk.  The white-space
will be sufficient to distinguish the filename from the path which follows.  The
path will consist of the volume label of the diskette being cataloged followed
by a colon followed by enough subdirectory names (separated by slashes) to
specify the complete path to the file. 

%define pipe
If the user ``pipes'' output to a file, the user will see no output except that
presented on MenuCat's window.  However, when MenuCat finishes the output will
be in a file consisting of records as described above.

While MenuCat is 
processing a disk, the user should hear the same level of disk activity one
would expect from a CLI command such as {\tt dir df1: opt a}.  Sounds of disk
activity which deviate from this should lead you to suspect {\it incorrect}
operation of MenuCat.  One should cease the cataloging operation and validate 
correct operation of MenuCat at this point.

\subsection{User Environment}

This document assumes the user has a 512k Amiga computer with a disk device
named DF1.  Should the user have more than 512k of RAM installed, there should
be no problem.  No data has been collected from users of Amigas who do {\bf not}
have 3.5" drives attached as drive DF1.  The author would be most interested to
hear whether people with 5.25" drives as DF1 can run MenuCat. 

\subsection{Operational Interface}

MenuCat uses the Amiga Mouse for menu selection and to indicate when disk
exchanges have been completed.   The MenuCat window also has a close gadget
which is clicked when the user is finished cataloging.  This window may
be moved about the Workbench screen.  It may be put into the foreground and
background by the standard gadgets in the upper right hand corner.  One who
has 60 character/line fonts may find MenuCat's custom text is somewhat
slewed around a bit.  %verify menucat in 60 char/line mode.
The user who uses interlace mode, may also note some peculiarities. 

\section{Features of MenuCat}


\subsection{Input, Actions, and Outputs}
MenuCat reads a disk in DF1.  While MenuCat is reading a disk, 
the display changes to inform the user that the volume in question is being 
processed.  When MenuCat finishes with a volume, a ``finished'' message is
presented to the user.  The user then replaces the disk in DF1 with the next
disk to be cataloged.  Output to the MenuCat window is to cue the user to
proceed with disk swaps.  Output to ``stdout'' is as described in section 2.1. 

\subsection{Use of MenuCat}
The user runs MenuCat from CLI, typing\\
\medskip
{\tt menucat >catdisk:catfile}\\
\medskip
Catfile is the file you wish to receive catalog data.  Since catalog data
tends to be rather large, try to make certain there's ample space on volume
CatDisk.  Running out of space on CatDisk can be annoying.

\subsection{Performance Characteristics}
As mentioned above, MenuCat can create big files.  The following measurements
were made on the author's personal software library, the first 30 disks of the
Fred Fish public domain library, and the first 8 disks of the AMICUS library.
The first column identifies the library in question; the second identifies the
size of the output file; and the third identifies typical times required to
perform the task of cataloging the library in question.  Users of this software
are encouraged to submit similar performance data on their personal libraries.

\bigskip
\begin{tabular}{||l||c|c||}
\hline
Poling Library & 155.6k & 55 min \\
\hline
Fish Library (1-30) & 75.9k & 22 min \\
\hline
Amicus Library (1-8)& 22.7k & 9 min \\
\hline
\end{tabular}
\bigskip

\section{Procedures for Use}

\subsection{Initiation and Protocols}

The user is advised to dedicate a disk solely to the task of holding
catalog data.  This will make the task of finding catalog data easier.  

\subsection{Preparation of Input}

The user is advised to make a point of establishing a {\bf unique} volume
name for each disk.  Be aware that tools such as Marauder or the Copper State
copier will produce disks with identical volume names.  The user is advised to
go through the library and re-label disks where necessary.  When this task is
complete, one is ready to run MenuCat. 
 
\subsection{Run Procedures}

One should run MenuCat from CLI.  At the CLI prompt type:\\
\medskip
{\tt MENUCAT >CATDISK:CATFILE}\\
\medskip
Push the menu button on the mouse and select the {\it Start Cataloging} menu
option.  Put the first disk to be cataloged in drive DF1.  Click on the {\bf
DISK} gadget in the MenuCat window.  Wait until the MenuCat window displays the
``Finished with disk'' message.  When that message appears, exchange the disk in
DF1 with the next disk to be cataloged.  Repeat the procedure of clicking on the
{\bf DISK} gadget and exchanging disks until all disks have been cataloged.
After the last disk has been cataloged, click on the {\bf QUIT} gadget and also
click on the {\it close window} gadget of the MenuCat window.  If the {\bf QUIT}
gadget is inadvertantly clicked, simply re-select the {\it Start Cataloging} menu
option and proceed.  

\subsection{Restrictions}

One can only catalog Amiga disks properly inserted in drive DF1.  One should
probably not attempt to pipe output of MenuCat to a disk inserted in DF1.  It
may cause a lot of disk swapping.  MenuCat cannot catalog 5.25" disk nor can it
catalog RAM disks or Hard disks.  An attempt to catalog the disk receiving the
catfile would probably necessitate quite a few disk swaps.  One should never
swap disks in DF1 while the drive light is lit. 

\subsection{Error Handling and Recovery}

If one clicks the {\bf DISK} gadget before amigados has mounted the disk in DF1,
an AmigaDos requester will appear saying there's no disk in drive 1.  Ignore it;
the requester should go away after a few seconds.  If the user clicks the {\bf
DISK} device more than once between disk swaps, the same disk will be cataloged
multiple times.  This is wasteful of operator time and of space on the catdisk.

\section{Theory of Applications}

\subsection{Program Model}

MenuCat was written with the philosophy that one problem should be solved as
simply as possible.  MenuCat solves the problem of being unable to find a file
with a specific name among many boxes of disks.  MenuCat is a first-order
solution to the larger problem of data management.  Keep in mind the limited
nature of MenuCat and nobody will be disappointed. 
 

\subsection{Algorithm Analysis}

The algorithm is a simple walk through all the directories of a disk. A simple
breadth-first tree traversal accomplishes this.  Each filename generates a
record of MenuCat output.  When all filenames have been recorded, the user is
prompted. When the user has finished swapping disks, a simple mechanism is
provided to allow the user to communicate that fact.  (The {\bf DISK} gadget.) 


\subsection{Extensions and Limitations}

Early on, it was recognized that Catfiles get big fast.  Thus, it makes sense to
remove any fluff from the records associated with each and every file.  However,
this ``fluff'' might not be perceived as useless in some contexts.  Tradeoffs
are in order here.  Rather than attempt to add any un-needed data to the output
records at the outset, MenuCat is intended to grow and develop according to {\bf
user} demand.  Therefore, it is the responsibility of the user to suggest
improvements and extensions to MenuCat. 

Since this exposes the user's entire software assets to MenuCat, it is the
user's responsibility to verify that MenuCat is performing correctly.  The user
must realize that running MenuCat exposes the user's entire software assets to
some element of risk.  Pretty grim stuff, but MenuCat or a program like
it could be the carrier of an EXTREMELY virulent software plague.

\appendix

% \section{Glossary}

% \section{References}

\section{Output Format}
Output records are of the form:\\ 
\medskip
{\it filename white-space path}\\
\medskip
There is one such record for each file on the disk.  The white-space consists of
either one or two TAB (Control-I) characters, depending upon the length of the
filename.  The path will consist of the volume label of the diskette being
cataloged followed by a colon followed by enough subdirectory names (separated
by slashes) to specify the complete path to the file. 

% \section{Summary of Features}

\section{Detailed Example}

One should prepare a disk with almost nothing on it.  For sake of discussion,
give the disk the volume name ``CatDisk.''  From CLI, recite the following
incantation: \\
\medskip
{\tt MenuCat >CatDisk:CatFile}\\
\medskip
This will cause MenuCat to run and any data which would go to standard output
goes instead to the file {\tt catdisk:catfile}.  If disk CatDisk has the file
CatFile on it already, {\bf the earlier version will be annihilated!}
A window will open up entitled {\it MenuCat}.  The menu bar will now display
only one selection: {\it Start Cataloging}.  

When the {\it Start Cataloging} selection is made, a
custom requester will appear over the MenuCat window.  On that custom requester
will be two pushbutton type gadgets labelled {\bf DISK} and {\bf QUIT}.
The first disk to be cataloged should be put into drive DF1.  Click on the {\bf
DISK} gadget in the MenuCat window.  Wait until the MenuCat window displays the
``Finished with disk'' message.  When that message appears, exchange the disk in
DF1 with the next disk to be cataloged.  Repeat the procedure of clicking on the
{\bf DISK} gadget and exchanging disks until all disks have been cataloged.
After the last disk has been cataloged, click on the {\bf QUIT} gadget and also
click on the {\it close window} gadget of the MenuCat window.  If the {\bf QUIT}
gadget is inadvertantly clicked, simply re-select the {\it Start Cataloging} menu
option and proceed.  
 
\end{document}
