\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}