home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 3 / FishMoreVol3.bin / fishfinders / aquarium.doc < prev    next >
Text File  |  1991-10-26  |  10KB  |  292 lines
  1. ***************************************************************************
  2. ***************************************************************************
  3.  
  4.         Aquarium (c) B Lennart Olsson 1989 - All Rights Reservered.
  5.         NewFish (c) B Lennart Olsson 1988 - All Rights Reservered.
  6.  
  7. ***************************************************************************
  8. ***************************************************************************
  9.  
  10. Aquarium and NewFish may be copied and redistributed without any additional
  11. permission, provided that no charge is requested for it's use and that
  12. this information is included.
  13.  
  14. Special thanks to Niclas Persson, who supported in many ways.
  15.  
  16. ***************************************************************************
  17.  
  18. 0.  Contents.
  19. -------------
  20.     1.  Intro
  21.     2.  Installation
  22.     3.  Search methods
  23.     4.  Search mode and program mode
  24.     5.  Navigation gadgets
  25.     6.  Project menu
  26.     7.  Hardcopy menu
  27.     8.  Break-"gadget"
  28.     9.  Key logic
  29.     10. Files in data directory
  30.     11. Future revisions of Aquarium
  31.     12. Using NewFish
  32.     13. Version history
  33.  
  34.  
  35.  
  36. 1.  Intro.
  37. ----------
  38.     Aquarium is a program intended for searching through a special
  39.     database containing information on the contents of Fred Fish's 
  40.     AmigaLibDisks in order to find programs, etc, with specified features.
  41.  
  42.     NewFish is a program that appends the AmigaLibDisks contents files
  43.     to the database. !!!! WARNING! Read this doc before you attempt to run
  44.     NewFish: it just might make your database useless if not handled with
  45.     care. A future revision will take care of this problem.
  46.  
  47.  
  48.  
  49. 2.  Installation.
  50. -----------------
  51.     There is nothing special about this: just be sure you have Aquarium
  52.     and the data directory in the same directory level, and if you're
  53.     running it from the CLI you must be in the same directory. See also
  54.     10: about the files in data.
  55.  
  56.  
  57.  
  58. 3.  Search methods.
  59. -------------------
  60.     The program searches through the database in three ways: Keys, sub-
  61.     string in program name and substring in the describing text.
  62.  
  63.     a: All the requested keys must be defined in the sought item,
  64.        otherwise Aquarium continues with the next item.
  65.  
  66.     b: If the keys are all right it scans the item name for the sub-
  67.        string ( not case sensitive) specified in the string-gadget 'name'.
  68.        If this fails it continues the search.  
  69.  
  70.     c: The sub-string specified in the string-gadget 'text' is used to
  71.        search in the contents description as in b.
  72.  
  73.     A special feature is included with the 'name' gadget: You may jump to
  74.     a disk directly by giving the disk number after a '/'. Example: '/150'.
  75.     (Not a beauty, but it works.)
  76.  
  77.     Note that if you're in programming mode no search operations are 
  78.     performed.
  79.  
  80.  
  81.  
  82. 4.  Search mode and program mode.
  83. ---------------------------------
  84.     In search mode you set up the keys by clicking on the keywords and a
  85.     navigation gadget (see section 5). In program mode the setting of a key
  86.     will change the database directly.
  87.  
  88.     Programming mode is recognized by a red screen and by a special image
  89.     for the mode-gadget.
  90.  
  91.  
  92.  
  93. 5.  Navigation gadgets.
  94. -----------------------
  95.     Double left arrows:
  96.         With this gadget you move directly to the beginning of the
  97.         database.
  98.  
  99.     Left and right arrow:
  100.         With these gadgets you search the database towards the beginning 
  101.         or the end for a match. In programming mode you take only one 
  102.         step in the chosen direction.
  103.  
  104.     Printer:
  105.         Make a hardcopy of the item shown, using the settings in the 
  106.         Hardcopy menu.
  107.  
  108.     Right gadget with open lock:
  109.         Search the database for the next item which does not have any keys
  110.         specified.
  111.  
  112.     Mode gadget:
  113.         Switches between search mode and program mode. In program mode the 
  114.         screen turns red and in search mode green-blue.
  115.  
  116.  
  117. 6.  Project menu.
  118. -----------------
  119.     About.
  120.     About Aquarium and me.
  121.  
  122.     Save.
  123.     If you have made any changes to the keys settings in the data
  124.     base, these will be saved to disk.
  125.  
  126.     Save & Quit.
  127.     Save changes as mentioned above and quit THIS program.
  128.  
  129.  
  130. 7.  Hardcopy menu.
  131. ------------------
  132.     Options - Include text.
  133.     The content description is included in all printouts.
  134.  
  135.     Options - Sorted list.
  136.     Normally, when a printed search is started, the program prints directly
  137.     any item found. With this option enabled it first puts all items found in
  138.     a buffer, sorts them when end of file is reached, and then prints them.
  139.  
  140.     Options - Formfeeds.
  141.     With this enabled it send a FormFeed character to the printer whenever a
  142.     new page is to start. Otherwise it sends linefeeds according to the
  143.     settings in preferences.
  144.  
  145.     Count them:
  146.     Search through the database, beginning at the top, count the matches, and
  147.     show the result in the text field.
  148.  
  149.     New Page:
  150.     Start a new page.
  151.  
  152.     Print:
  153.     Search through the database and print the matching items.
  154.  
  155.  
  156. 8.  Break-"gadget".
  157. -------------------
  158.     When time consuming actions take place, as in searching for substring
  159.     in the text or printing, you'll find that a special gadget appears in
  160.     the text field. Clicking in the neighbourhood of this will stop the
  161.     current action.
  162.  
  163.  
  164.  
  165. 9.  Key philosophy.
  166. -------------------
  167.     We have tried to make the keys self-explanatory and the settings
  168.     logical and consistent, but there are a few things that can help you
  169.     understand the logic used:
  170.  
  171.         a:  IFF pictures and such - Data & Graphics
  172.         b:  Sound files           - Data & Sound
  173.         c:  Fonts                 - Data, Text processing & Graphics
  174.         d:  The Subroutine key stands for libraries and useful routines
  175.             in general.
  176.         
  177.     There are some unused keys that you can use for your own purpose.
  178.     Just put the names in the file 'KeyNames' in the 'Data' directory.
  179.  
  180.  
  181.  
  182. 10. Files in data directory.
  183. ----------------------------
  184.     The data directory must reside in the same directory as Aquarium.
  185.     If you run this program from CLI, you must make this your current
  186.     directory. You don't have to make any assignments.
  187.  
  188.     Data:
  189.         This file contains the text describing the programs.
  190.  
  191.     Index:
  192.         Contains the keys and pointers to data file.
  193.  
  194.     Names:
  195.         Contains item names.
  196.  
  197.     KeyNames:
  198.         Contains the key names appearing in the key-gadgets.
  199.  
  200.  
  201.  
  202. 11. Future revisions of Aquarium.
  203. ----------------------------------
  204.     If you have any suggestions or thoughts concerning this program,
  205.     please let me know.
  206.  
  207.  
  208.  
  209. 12. Using NewFish.
  210. -----------------
  211.     NewFish is a program to read the contents files of the Fish's disks
  212.     and append them to Aquarium's database.
  213.  
  214.     WARNING:
  215.     You MUST take a backup copy of all files in the data directory
  216.     before you run NewFish. This program is not very smart and if it failes
  217.     to interpret the contents file correctly and you accept the result,
  218.     there is NO WAY to delete the incorrect item from the data base.
  219.  
  220.     The program reads the contents file and tries to extract the different
  221.     items from the text. For each item it asks you if it is OK and then
  222.     saves it directly to disk. A problem might occure if the file is only
  223.     partly correct and you abort the program. This leaves you with an
  224.     incomplete disk in the database. To correct the situation you must edit
  225.     a version of the contents file and delete those items already appended.
  226.  
  227.     A file with no separable items will be read as one item and called
  228.     Diskxxx.
  229.  
  230.     Make a hardcopy of all the contents files before you try to append
  231.     them to the data base. Read them carefully and check if the following
  232.     rules apply.
  233.  
  234.     a:  A contents file with separate items is allowed to have a multi
  235.         line comment at the beginning, if all the lines start at the
  236.         first column.
  237.  
  238.     b:  All items must be separated by a blank line.
  239.  
  240.     c:  An item's first line must start in the first column and the lines
  241.         thereafter must start with a tab or space.
  242.  
  243.     d:  A contents file that is to be interpreted as only one item must
  244.         not contain any white spaces at the beginning of lines if it
  245.         is to be be correctly interpreted. You may try to read it with NewFish
  246.         to see if it reads correctly. You will be advised whether or not the
  247.         program treats it as a disk item. Just abort if it separate it
  248.         into different items.
  249.  
  250.     In some way I'll make this program easier to use. It's just to
  251.     silly the way it is now.
  252.  
  253.  
  254.  
  255. 13. Version history.
  256. --------------------
  257.     Aquarium 1.11:
  258.         Changes that make it easier to compile for another language by
  259.         linking with a special text file. This also applies for the
  260.         names of files. The program will use the names specified in
  261.         the text file and if these don't work, it tries the default
  262.         Swedish names and thereafter the English names.
  263.  
  264.         Centering of key names did not work if the line in the key-name
  265.         file ended directly after the name. Now it does.
  266.  
  267.         Save caused the program to start at the beginning of the data
  268.         base. Changed.
  269.  
  270.         The disk number option in the name gadget did not always work.
  271.         This bug is now removed.
  272.  
  273.     Aquarium 1.12:
  274.         A minor internal enhancement.
  275.  
  276.     Aquarium 1.13:
  277.         Two bugs removed:
  278.         1/  If an error occured during a "save and quit" action the
  279.             standard output was filled with garbage.
  280.         2/  Breaking a "count them" action caused an extra found item.
  281.  
  282. --------------------------------------------------------------------------
  283.  
  284. That's all. If you have any suggestions or thoughts around this program,
  285.             please don't hesitate to contact me.
  286.  
  287.                 B Lennart Olsson
  288.                 Brunnsgatan 8
  289.                 223 60 LUND
  290.                 Sweden
  291.  
  292.