home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 3 / FishMoreVol3.bin / fishfinders / newaqua.doc < prev    next >
Text File  |  1992-01-30  |  17KB  |  451 lines
  1. ==============================================================================
  2.  
  3.   NewAqua    Copyright Glenn Gribble 1991,1992    - All Rights Reserved.
  4.   FishBowl    Copyright Glenn Gribble 1992        - All Rights Reserved.
  5.   AddFish    Copyright Glenn Gribble 1992        - All Rights Reserved.
  6.  
  7.   NewAqua may be copied and redistributed provided that this notice
  8.   is included.  NewAqua may not be sold for profit, but reasonable
  9.   distribution fees may be charged.
  10.  
  11.   NewAqua uses the same data file format as Aquarium, but is not
  12.   based on the source to Aquarium.
  13.  
  14.   Aquarium is Copyright Lennart Olsson 1989 - All Rights Reserved.
  15.  
  16. ===============================================================================
  17.  
  18. Table of Contents
  19.  
  20.   1. Introduction
  21.   2. Getting Started
  22.   3. Using the Menus
  23.   4. Keyboard acceleration
  24.   5. Edit mode
  25.   6. Configuration commands
  26.  
  27.   A. Author information
  28.   B. Release Notes
  29.   C. Files In Release
  30.   D. Keyboard reference
  31.   E. Menu reference
  32.   F. FishBowl program
  33.   G. AddFish program
  34.   H. Installation
  35.  
  36.  
  37. 1. Introduction
  38. ---------------
  39.   NewAqua is a program for viewing and printing Aquarium databases.
  40.   Aquarium databases contain information about disks and programs
  41.   on those disks.  The most popular Aquarium database has all of the
  42.   Fred Fish disks from 1 to 560 and beyond (maintained by Udo Shuermann,
  43.   walrus@wam.umd.edu).
  44.  
  45.   NewAqua does most everything that the original Aquarium by B Lennart
  46.   Olsson does and more.
  47.  
  48.   Additional features:
  49.     Support for splitting the database onto multiple disks or directories.
  50.     Has resizable index and description windows.
  51.     Index and description windows have scroll bars.
  52.     Can display information about multiple fish in the description window.
  53.     Can store descriptions in memory after being read from disk.
  54.     Can display fish selected from index window.
  55.     Many screen modes supported.
  56.   Missing features:
  57.     NewAqua can not edit database entries.
  58.   
  59.   The FishBowl allows manipulation of the database.  Using FishBowl, the
  60.   database can split onto multiple floppies, or merged onto one large
  61.   disk.
  62.   
  63.   The AddFish program adds new entries to the database.
  64.  
  65. 2. Getting Started
  66. ------------------
  67.   In order to keep the archive size small, this release includes only the
  68.   database for fish 551 to 580.  Data for fish 1 to 550 are available on
  69.   ab20.
  70.  
  71.   A few terms used in this document:
  72.  
  73.     Fish          - the description of a single program from the
  74.                 Fred Fish public domain collection
  75.     fish Disk          - all the descriptions from a single Fred Fish disk
  76.     Fish Bowl          - a directory containing many fish disks worth of
  77.                 descriptions (must be stored on only one disk)
  78.     Aquarium database - a complete database consisting of many fish bowls
  79.                 which may be on separate disks
  80.  
  81.   To start the program, just double click on the "NewAqua" icon.
  82.   
  83.   You will be presented with three windows:  the Control window which
  84.   contains search control gadgets, the Description window, and the About
  85.   window which contains copyright information.  Click on the close gadget
  86.   in the upper left corner of the About window to close the About window.
  87.   
  88.   The 5 arrow and box gadgets in the control window control simple
  89.   search operations.  The "next fish" gadget ( > ) advances to the next
  90.   fish in the database and displays its description in the description
  91.   window.  The "next disk" gadget ( >> ) advances to the next disk in
  92.   the database and displays the description of all of the fish from that
  93.   disk.  The "prev fish" ( < ) and "prev disk" ( << ) gadgets move
  94.   backwards in the database. The box gadget in the middle resets the
  95.   database to the beginning.
  96.   
  97. 2.1 The Control Window
  98.  
  99.   In addition to the simple movement gadgets, the control window
  100.   contains search control gadgets and long range movement gadgets.
  101.   
  102.   The 30 buttons at the top of the control window select various categories
  103.   to which each displayed fish must belong.  For instance, if the
  104.   "Communication" button is selected, the "next fish" button will only
  105.   select fish that belong to the "Communication" category.
  106.   
  107.   The "Name" text gadget causes NewAqua to only display fish if the text
  108.   in the "Name" gadget appears in the name of the fish.  For instance,
  109.   enter "pp" in the name gadget (reset the "Communication" button also).
  110.   Now, the next fish button will only display "pp" fish ("PPmore",
  111.   "PPlib", and "PP..." from the shipped database).
  112.   
  113.   The "Text" gadget works the same way, only it searches through the
  114.   descriptive text to find a match.
  115.   
  116.   The two gadgets "Disk Range" and "To" limit searching to the selected
  117.   range of disks.
  118.  
  119.   If more than one of these search controls is in use, then all of the
  120.   conditions must be met.  For instance, to search for communication
  121.   programs that have AREXX ports and do VT100 emulation, you would select
  122.   the "Communication" and "ARexx" buttons, enter "100" in the "Text" gadget
  123.   (use "100" because the text might include a space between "VT" and "100"),
  124.   and then press the next fish gadget to see matching fish.
  125.   
  126.   The search control fields are not used by the "next disk" and "prev disk"
  127.   gadgets.
  128.  
  129.   The long range movement gadgets are the "Disk" and "Fish" gadgets.
  130.   The "Disk" gadget displays the current disk number.  This number will
  131.   be updated by the movement gadgets.  To jump to another disk, just
  132.   enter the number in the "Disk" gadget and press the return key.  The
  133.   "Fish" gadget works like the "Disk" gadget, except it displays the
  134.   current fish number instead of the current disk number.  Fish numbers
  135.   range from 1 to the number of fish in the database. 
  136.  
  137. 2.2 The Description Window
  138.  
  139.   The description window is is a scrollable window which contains the
  140.   description of the current fish or fishes.  The "Describe/All Matches"
  141.   menu item can be used to fill the description window with descriptions
  142.   of all fish matching the current selection controls.
  143.  
  144.   When the database is at the beginning position, the description window
  145.   displays some statistics about the database such as total number of fish,
  146.   and the names of the fish bowls and number of fish in each.
  147.  
  148. 2.3 The Index Window
  149.  
  150.   The index window is a scrollable window which contains the disk
  151.   numbers and names of all of the fish in the database which match the
  152.   current selection controls.  An entry may be selected/deselected by
  153.   clicking on that entry.  Double clicking on an entry will cause the
  154.   descriptions of all selected entries to be loaded into the description
  155.   window.
  156.  
  157. 3. Using the Menus
  158. ------------------
  159.  
  160.   More commands are available on the menus attached to each window.  The
  161.   Menu Reference appendix contains a complete listing of each menu command.
  162.  
  163. 3.1 Control Window Menus
  164.  
  165.   The "Project" menu contains the About and Quit commands.
  166.   
  167.   The "Windows" menu contains commands to access each window.  Selecting
  168.   a window from this menu will cause the window to be brought to the front.
  169.   In addition, selecting the "Index" window from this menu causes the
  170.   contents of the Index window to be recalculated.
  171.  
  172.   The "Describe" menu contains commands to describe larger collections of
  173.   fish.  The available collections are: 
  174.     all fish matching the current selection controls
  175.     the current disk
  176.     all selected fish in the index window
  177.  
  178.   The "Display" menu contains a toggle item which controls display of the
  179.   categories along with the fish name and disk number in the index and
  180.   description windows.
  181.  
  182. 3.2 Scrolling Window Menus (Description, Index, Help)
  183.  
  184.   All scrolling windows contain a "Print" menu which controls printing the
  185.   contents of that window.
  186.  
  187.  
  188. 4. Keyboard acceleration
  189. ------------------------
  190.  
  191.   Many of the operations are accessible from the keyboard also.  The
  192.   up/down arrow keys will scroll the current window (or the description
  193.   window if the current window is the control window).  The right/left
  194.   arrow keys will select the next/previous fish.  Shifted right/left
  195.   arrow keys will select the next/previous disk. 
  196.  
  197.  
  198. 5. Edit mode
  199. ------------
  200.  
  201.   There is no edit mode yet.
  202.  
  203. 6. Configuration commands
  204. -------------------------
  205.  
  206.   Newaqua can be configured using a configuration file ("NewAqua.cnf"),
  207.   or the tool type properties on the icon (use the WorkBench/Info
  208.   command).  The commands are the same in either the configuration file
  209.   or the icon.  All commands must be UPPERCASE.  Values may be either
  210.   case.  All paths are relative to icon/current directory.  If NewAqua
  211.   is run from the CLI, an alternate configuration file name can be given
  212.   on the command line (for example: `NewAqua TwoDisk.cnf').  NewAqua
  213.   does not read "NewAqua.cnf" when invoked from the WorkBench, but may
  214.   be made to read it by using a CONFIG=NewAqua.cnf tool type command.
  215.   
  216.   A minimum config file contains a KEYNAMES command, a BOWL command, and
  217.   a HELP command (if help is to work).
  218.  
  219.   Command:  KEYNAMES    Value:    KeyNames file name
  220.                 There must be exactly 1 KEYNAMES command.
  221.   Examples: KEYNAMES=data/KeyNames
  222.             KEYNAMES=AQdata:KeyNames
  223.  
  224.   Command:  HELP    Value:    Location of NewAqua.help file
  225.   Examples: HELP=NewAqua.help
  226.             HELP=AQdata:NewAqua.help
  227.  
  228.   Command:  BOWL    Value:    Data directory (Data, Index, and Names files)
  229.                 There must be at least 1 BOWL command.  There
  230.                 may be upto 8 BOWL commands.
  231.   Examples: BOWL=data
  232.         BOWL=AQdata000:data
  233.         BOWL=AQdata500:data
  234.  
  235.   Command:  CONFIG    Value:    Configuration file name
  236.                 CONFIG is entirely optional.  There may be
  237.                 any number of CONFIG commands (avoid loops!)
  238.   Examples: CONFIG=NewAqua.cnf
  239.             CONFIG=TwoDisk.cnf
  240.  
  241.   Command:  ALLOCATE    Value:    Controls allocation of description entries
  242.                 when read from disk.  Do not turn this on
  243.                 unless you have lots of memory.
  244.                 ALLOCATE defaults to OFF
  245.   Examples: ALLOCATE=ON
  246.  
  247.   Command:  COMMENT    Value:    Comment string which is ignored
  248.   Examples: COMMENT=This config file is for Fish 200-400 only
  249.  
  250.   Command:  SCREEN    Value:    Either CUSTOM or WORKBENCH.  CUSTOM causes
  251.                   NewAqua to open a custom screen.  WORKBENCH
  252.                 causes NewAqua to use the WorkBench screen.
  253.                 The COLORS, DEPTH, and VIEWMODES commands are
  254.                 ignored if SCREEN=WORKBENCH.  Default: CUSTOM.
  255.   Examples: SCREEN=WORKBENCH
  256.         SCREEN=CUSTOM
  257.  
  258.   Command:  VIEWMODES    Value:    Either INTERLACE or NOINTERLACE.  Allows a
  259.                   CUSTOM screen to be opened in INTERLACE mode.
  260.   Examples: VIEWMODES=INTERLACE
  261.         VIEWMODES=NOINTERLACE
  262.  
  263.   Command:  DEPTH    Value:    Depth of CUSTOM screen.
  264.                 Default: 2.  Range: 1 to 4.
  265.   Examples: DEPTH=2
  266.  
  267.   Command:  COLORS    Value:    Up to 16 HEX color constants.  The first
  268.                 example is the default value.
  269.   Examples: COLORS=0x0999 0x0000 0x0FFF 0x0666
  270.             COLORS=0x0AAA 0x0000 0x0FFF 0x068B 0x000D 0x0FFF 0x0000 0x0FC0
  271.  
  272.   NewAqua does not yet support project icons.
  273.  
  274.  
  275. A. Author information
  276. ---------------------
  277.  
  278.   Author
  279.     Glenn Gribble                            glenn@netcom.com
  280.     1906 Coastland Ave
  281.     San Jose, CA 95125                       (408) 448-1612
  282.     USA
  283.  
  284.   Compilation & test environment
  285.     Amiga 2500/2630 5 Meg RAM, 250 Meg Disk, 60 Meg Tape, OS 1.3.
  286.     C++ compiler: Lattice C++ 1.0
  287.     C compiler:   SAS/C 5.10
  288.     Source:       5000 lines C++ and 35 lines C
  289.  
  290. B. Release Notes
  291. ----------------
  292.   NewAqua release 1.0
  293.  
  294.   This version is the first release with a (nearly) complete set of
  295.   features.  If this version proves to be bug free, it will be sent to
  296.   Fred Fish.
  297.  
  298.   If you find any bugs, please report them via e-mail to glenn@netcom.com.
  299.  
  300. C. Files In Release
  301. -------------------
  302.   NewAqua1.0.info - icon
  303.   NewAqua1.0/      - directory containing program and data
  304.     NewAqua.doc   - this file
  305.     NewAqua.doc.info - Fred Fish README icon
  306.     NewAqua.info  - Simple Icon
  307.     NewAqua.help  - The Help file
  308.     NewAqua      - The program
  309.     NewAqua.cnf      - An example config file showing all of the commands
  310.     AddFish      - A program to add more disks to the database
  311.     FishBowl      - A program to split and merge fish bowls
  312.     History      - History of distribution
  313.     WishList      - WishList of new features
  314.     Data/      - sample data directory containing ONE fish disk
  315.       KeyNames      - key names file
  316.       Data      - descriptions file
  317.       Index      - index file
  318.       Names      - fish names file
  319.  
  320. D. Keyboard reference
  321. ---------------------
  322.   NewAqua thinks the cursor arrow keys and the key pad arrow keys are
  323.   exactly the same.  Thus there are two keys that act like "Left Arrow".
  324.  
  325.   Scrolling windows (Description, Index, Help)
  326.     Down Arrow        - Move window down
  327.     Up Arrow        - Move window up
  328.     PgDn        - Move window down one page
  329.     PgUp        - Move window up one page
  330.     Home        - Jump to top of window
  331.     End            - Jump to bottom of window
  332.  
  333.   Control window
  334.     Left Arrow        - Next fish
  335.     Right Arrow        - Prev fish
  336.     Shift-Left Arrow    - Next disk
  337.     Shift-Right Arrow    - Prev disk
  338.     Keypad "5"        - Reset current fish
  339.  
  340.     Arrows, PgUp, PgDn, Home, End - move Description window
  341.  
  342. E. Menu Reference
  343. -----------------
  344.  
  345. E.1 Control window
  346.  
  347.     Item: Project/About
  348.       Displays Version and Author information
  349.     Item: Project/Quit        [Amiga-Q]
  350.       Quits program (does not ask for confirmation)
  351.  
  352.     Item: Windows/Description
  353.       Opens Description window and brings it in front of the other windows.
  354.     Item: Windows/Index        [Amiga-I]
  355.       Opens Index window, loads it with the index entries that match the
  356.       current search control fields and brings the Index window in front
  357.       of the other windows.
  358.     Item: Windows/Control
  359.       Brings the Control window in front of the other windows.
  360.  
  361.     Item: Describe/All Matches        [Amiga-A]
  362.       Loads the descriptions of all matching fish into the description window.
  363.       CAUTION:  This command can take a long time and use a lot of memory if
  364.       the selection criteria is too general.
  365.     Item: Describe/Disk            [Amiga-D]
  366.       Loads the descriptions of all fish on the current disk into the
  367.       description window.
  368.     Item: Describe/Selected
  369.       Loads the descriptions of all fish that have been selected in the Index
  370.       window.  This function can also be invoked by double-clicking on an
  371.       entry in the Index window.
  372.  
  373.     Item: Display/Categories        [F1]
  374.       Toggle display of categories in index and description windows.
  375.  
  376. E.2 Scrolling windows (Description, Index, Help)
  377.  
  378.   All scrolling windows contain a Print menu.
  379.  
  380.     Item: Print/Print            [Amiga-P]
  381.       Send contents of window to printer.
  382.     Item: Print/Eject page        [Amiga-E]
  383.       Send a form feed to the printer.
  384.     Item: Print/File            [Amiga-F]
  385.       Send contents of window to a file (default: "t:NewAqua.lis").
  386.  
  387. F. FishBowl program
  388. -------------------
  389.  
  390.   The FishBowl program can be used to split and merge fish databases.
  391.  
  392.     Usage: FishBowl [-nowrite] [-low N] [-high N] inBowls ... outBowl
  393.  
  394.   FishBowl copies the selected range of disks from all of the
  395.   input bowls to the output bowl.  Each `bowl' is a directory
  396.   containing the Data, Index, and Names files.
  397.  
  398.   Examples:
  399.     merge bowls 1&2 into bowlMerge
  400.     FishBowl bowl1 bowl2 bowlMerge
  401.     copy disks 100 to 199 into new bowl f100
  402.     FishBowl -low 100 -high 199 data f100
  403.     merge and select at the same time
  404.     FishBowl -low 151 -high 250 f100 f200 aq151-250
  405.  
  406.  
  407. G. AddFish program
  408. ------------------
  409.  
  410.   The AddFish program is used to add additional fish to the database.
  411.   AddFish can read the multiple disk Contents files as posted to the net.
  412.   
  413.   To add new fish to the database, first figure out the names of all of
  414.   the Contents files you wish to add.  For example, "downloaded-ff560"
  415.   or "AmigaLibDisk544:Contents".  Next, create a directory for a bowl
  416.   full of new fish, for example "NewBowl".  Then, run the program
  417.   without writing to the database like this (all on one line):
  418.  
  419.     AddFish -output NewBowl -log 2 
  420.        AmigaLibDisk544:Contents AmigaLibDisk545:Contents
  421.  
  422.   If errors were generated, the Contents file will have to be editted.  If
  423.   you can not figure out what went wrong, try re-running the command with
  424.   "-log 10" to print out everything that happens.
  425.  
  426.   If this ran without errors, then run it again with the "-write" option.
  427.  
  428.     AddFish -output NewBowl -log 2 -write
  429.        AmigaLibDisk544:Contents AmigaLibDisk545:Contents
  430.  
  431.   This will actually write data to the NewBowl directory.  You can continue
  432.   to add fish to the NewBowl database using these commands.  After all of
  433.   the new fish have been added, you can use NewAqua to browse the NewBowl
  434.   database.  To do this, you will need to create a file NewBowl.cnf and
  435.   invoke "NewAqua NewBowl.cnf" from the CLI.  NewBowl.cnf should contain:
  436.  
  437.     HELP=NewAqua.help
  438.     KEYNAMES=data/KeyNames
  439.     HELP=NewAqua.help
  440.     BOWL=NewBowl
  441.  
  442. H. Installation
  443. ---------------
  444.  
  445. Nothing to it.  Just copy the entire NewAqua1.0 drawer to wherever you
  446. want to keep it.
  447.  
  448.  
  449. RCSID: $Id: NewAqua.doc,v 1.2 92/01/30 08:49:28 glenn_gribble Exp $
  450.  
  451.