home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / disks / misc / findcount / gcat / gcat.doc < prev    next >
Text File  |  1981-06-29  |  16KB  |  373 lines
  1. Gcat:- a simple Amiga disk catalogger by John Marchant (aka "Gnome")
  2. ------
  3.               Version 44.02    11.05.95
  4.  
  5.   This program was developed as a project while learning C. It is still
  6. being developed as ideas come for improvements. My best ideas come 
  7. when I'm in my bath, on the toilet seat or gardening. To anyone who
  8. dislikes my spelling of "catalog", I say "Tough. I'm logging the disks
  9. and I like to call the result a catalog."
  10.  
  11. ***********************************************************************
  12.                ##### NOTICE #####
  13.   PLEASE NOTE that Gcat has not been idiot-proofed.
  14. There is no protection against making silly data entries in the
  15. Edit and Insert options.
  16. ***********************************************************************
  17.  
  18.   The program is Public Domain and must be accepted "as is".  NO WARRANTY
  19. is given that it is bug-free, and NO LIABILITY is accepted for any damage
  20. it may do to your hardware, your software or your peace of mind.  However I
  21. use it and I'm happy with it so far as it goes.  I'd call it "cheap and
  22. cheerful".
  23.  
  24.          --------------------------------------------------
  25.  
  26. The following files should be supplied with any copy of this program:-
  27.  
  28. GCat          The catalog program.
  29. CatHelp.txt   The online help text. Should be in the same directory as Gcat.
  30. req.library   Copy this into your libs: directory if you don't have it.
  31. testfile.cat  ..if you're lucky :-)  It's just a demo to play with.
  32. Gcat.doc      The file you are reading. This file includes CatHelp.txt
  33. ppmore        Utility for displaying help text. This should be in your
  34.                  c: or your sys:utilities directory.
  35.  
  36.          ---------------------------------------------------
  37.  
  38. Gcat may be started from the CLI or from Workbench.
  39.  
  40. If started from CLI with an argument c (i.e.  "Gcat c") an
  41. alternative color palette (grey, black, white, yellow) will be used.
  42. Otherwise the Workbench preference setting will be used.
  43.  
  44. If you start it by a CLI command, you should first change directory to the
  45. one in which your Gcat program and this help text are held. Otherwise the
  46. program will not be able to find the help text file, and will complain.
  47. So you should....
  48.  
  49.                cd <path to Gcat drawer>
  50.                run Gcat
  51.  
  52.   or of course you can use a wee startup script that does this for you, and
  53. you could execute this script using an alias. Or you could be clever and
  54. use IconX to execute the script.
  55.  
  56. If you start from the Workbench icon, there's no need to change directory.
  57.  
  58. There is a limit of 5000 set on how many files may be added to one Catalog.
  59. I'm not sure why, but there must be _some_ limit set, and 5000 seemed like
  60. a good idea! This may be revised later. (See also "Bugs" below.)
  61.  
  62.  ==== The following text is also in 'CatHelp.txt' for online viewing ====
  63.  
  64. The program is controlled by pulldown menus or hotkeys.
  65.  
  66. USING GCAT
  67. ============
  68.   To add data to your catalog you must first select the drive which will
  69.     be used for collecting data.
  70.   Then you simply insert disks into this drive and press RtAmiga/A each
  71.     time. The rest is automatic.
  72.   If you want to edit or delete an entry, point to it and click with the
  73.     left mouse button. The Edit window appears. Click on Edit or Delete, 
  74.     make any changes, and then click on Accept or Cancel.
  75.   You can also click & drag the pointer to select several lines, but the
  76.     dragging can't be used to de-select items already highlit. To do this
  77.     you must click on individual lines. The reason for this is to avoid
  78.     accidental deselection. (That's my excuse anyway.)
  79.   To insert an extra (new) entry, select the Insert menu option and follow
  80.     the instructions below.
  81.  
  82. The MENUS.
  83. ~~~~~~~~~~~
  84. Options menu
  85. =============
  86. SELECT INPUT DRIVE
  87.   This is the drive from which data will be read & added to the catalog.
  88.   e.g. If you select DF1: then all file names on DF1: will be added to
  89.     the catalog - ** even if they already exist in the catalog **
  90.   Only currently available drives will be offered.
  91.  
  92.   The drive you select here remains the drive used for gathering more data,
  93.     unless you select a new one from this menu option. It is unaffected by
  94.     the drive & file you may select to "Load Existing Cat" (though these
  95.     may be the same file & drive).
  96.  
  97. ADD DATA FROM DISK (RtAm/A)
  98.   This will cause the 'Input Drive' to be scanned, and all file names
  99.     (except those with .info extensions) will be appended to the current
  100.     catalog file in memory.
  101.  
  102.   The Catalog file will then be sorted & displayed without further menu
  103.     selection, and you can use the editing facilities described below under
  104.     'Load Existing Catalog'.
  105.  
  106.   You may then proceed to select further menu options, such as add
  107.     further data (from the selected "Input Drive"), change the current
  108.     input drive, or load an existing catalog.
  109.  
  110. SAVE FILE  (RtAm/S)
  111.     When you load an existing catalog file, or "add data from disk",
  112.   file names forming the catalog are read into memory. If any change is
  113.   made (edits, additions, deletions) you may wish to save the altered
  114.   catalog. If you ask to load a new catalog or quit without having
  115.   saved, a requester will remind you and ask if you wish to save.
  116.     If a catalog file name has not yet been specified, a requester
  117.   will appear for this purpose.
  118.  
  119. SAVE AS    (RtAm/N)
  120.     This is the same as SAVE FILE but asks you the name of the file you
  121.   wish to save to. e.g. you may wish to save it in a different place or
  122.   under a different name. (The 'N' hotkey represents "Name").
  123.  
  124. LOAD A CAT FILE    (RtAm/L)
  125.   This enables you to read an existing catalog. A requester will appear
  126.     for you to select the path and file.
  127.  
  128.   The file & drive you select here do not alter the current input drive.
  129.     If you want to add data to the catalog you select here and it's on
  130.     a different drive, you must use "Select Drive" to set the new
  131.     "current input drive".
  132.  
  133. START NEW CAT
  134.   Use this to clear the current catalog held in memory and begin a new
  135.     one. If changes have been made to a catalog currently held, you'll
  136.     be asked if you wish to save this first.
  137.  
  138. SELECT SORT
  139.   This produces a submenu with 2 options:
  140.     SORT ON FILENAME  (RtAm/1)
  141.     SORT ON DISKNAME  (RtAm/2)
  142.   These control the presentation of the list on screen. You can change
  143.     the sort at any time.
  144.  
  145. QUIT  (RtAm/Q)
  146.   This is a way to exit the program. You can also exit by using the window
  147.     close gadget. If a catalog is currently in memory & has not been saved
  148.     since it was last changed, a requester will appear to remind you.
  149.  
  150.             ------------------------------------------------
  151.  
  152. Insert Menu
  153. =============
  154.   INSERT ITEM  (RtAm/I)
  155.   ------------
  156.   Selecting this will bring up an 'Insert window' with several string
  157.     gadgets, and 2 button gadgets (OK and Cancel).
  158.  
  159.   There are 4 fields to be entered:
  160.        File Name    Path     File size (bytes)    Date
  161.   
  162.   See also "Edit window" below.
  163.  
  164.   Until the program is properly idiot-proofed, care should be taken to
  165.     enter data correctly. See the screen display for formats.
  166.   After making an entry and clicking on Accept, the new item is planted
  167.     in the file list, which is then re-sorted and displayed.
  168.  
  169.  
  170. Help Menu
  171. ==========
  172.   HELP  (RtAm/H or Help key)
  173.   -----
  174.   This will move the working screen to back and call ppmore to display
  175.   this text file you are reading. After use, the work screen returns.
  176.  
  177.   Please note that ppmore should be in your C directory, or some other dir
  178.     for which a path has been assigned for commands (e.g. Utilities).
  179.  
  180.  
  181. Printer Menu
  182. =============
  183.   PRINT CATALOG  (RtAm/P)
  184.   --------------
  185.   This formats and prints the catalog file currently displayed.
  186.     You should have your printer ready for action, as printing starts as
  187.     soon as you have made the request.
  188.  
  189.   WRITE TO FILE  (RtAm/W)
  190.   --------------
  191.   This will bring up a requester asking for the path & name of the output
  192.     file. The catalog currently being displayed will be formatted and written
  193.     to the selected output file. The Catalog data file is packed, with
  194.     many spaces removed, but 'Write to file' will format it as it appears
  195.     on the screen.  Unlike 'Print', there will be no page-breaks.
  196.  
  197.   SET PAGE LENGTH
  198.   ----------------
  199.   This allows you to change your print page length from the default 66 
  200.     lines to some other value (eg for A4 cut sheets). Two blank lines will
  201.     always be left at the foot of each page - ie 64 lines will be printed
  202.     on a 66 line page. Note that you cannot change the pagelength during the
  203.     printing.
  204.  
  205.   SET LETTER QUALITY
  206.   -------------------
  207.   Use this option if you want non 'draft' quality and your printer does
  208.     not have a high quality option switch on it. Setting this option
  209.     only changes the copy of your printer preferences currently held
  210.     in memory (and restores to its original setting after printing). 
  211.     It does NOT alter the setting of your Preferences held on disk.
  212.     If you already had 'Letter quality' set in your Preferences, this
  213.     option will make no difference.
  214.  
  215.     ----------------------------------------------------------------
  216.  
  217.   When a Catalog is displayed, you can scroll the text up and down, using
  218.     the proportional gadget or the arrow gadgets at right of screen. You
  219.     can also highlight lines by clicking on them with the left mouse button.
  220.     Selecting lines in this way causes the Selection buttons to appear.
  221.     
  222. The Selection buttons
  223. ----------------------
  224.   If you click on one or more lines on the screen, those lines are
  225.     highlighted and the selection buttons are revealed. 
  226.     Deletions & edits do not take effect until 'Accept' is selected.
  227.  
  228.   Delete:- if you click on this one, you are asking to delete all lines
  229.     you have selected whether or not they have scrolled off the screen.
  230.  
  231.   Edit:- brings up a 'string requester' containing the most recently 
  232.     marked line, and you can edit the line. Press OK to accept, or 
  233.     press Cancel. If more than one line was previously selected, only
  234.     the most recent one can be edited. Any others are unaffected.
  235.  
  236.   Accept:- accepts any changes into the catalog data.
  237.  
  238.   Cancel:- cancels the changes you have made and conceals the selection
  239.     buttons.
  240.  
  241.     ================== End of 'CatHelp.txt' =======================
  242.  
  243. The Catalog file (This section for enthusiasts only!)
  244. -----------------
  245.   This is a text file which may be edited if you wish.  A text editor can be
  246.     used: but be sure to retain the format, which has field separators as 
  247.     described below. (ie the lines are 'packed'.)
  248.  
  249.   Field 1 holds the file names in alphabetical order.
  250.  
  251.   Field 2 holds the disk name from which each file was extracted, and
  252.     the name of the lowest level of sub-directory in which it resides.
  253.     e.g. a file on df0:games/zaptype/Amoeba shows as
  254.                            Amoeba  df0:zaptype
  255.           This is only for reason of space in the line.
  256.  
  257.   Field 3 holds the file size in bytes, left-padded with spaces to 8 characters.
  258.  
  259.   Field 4 holds the date found on the file. If this is silly, then the
  260.     file has a silly date (or you entered it wrongly when editing).
  261.  
  262.   Fields are separated on the file by the vertical bar character |
  263.  
  264.   Until a "search" facility is added, the easiest way to search for a
  265.     file name is by using a text editor such as Cygnus Ed, or the DOS
  266.     "search" facility.
  267.  
  268.    ----------------------------------------------------------------
  269.  
  270. Recent History
  271. ================
  272. Vn 41 Revn 5: Option to use Workbench colours (by default), or my
  273.               own choice of colours (using 'c' argument).
  274.  
  275. Vn 42 Revn 0: The window and all gadgets now size themselves according
  276.               to the user's screen size. This cures problems with
  277.               overscan or non-standard screen heights.
  278.       Revn 1: Printing bug now corrected. Output text looped on
  279.               start of each page from page 3 onwards due to really
  280.               stupid coding error.
  281.       Revn 2: Inability to "see" drive Df2: now fixed.
  282.       Revn 3: Cosmetic tweaks of no consequence
  283.       Revn 4: Tiny bug fixed. It was possible to select a line one
  284.                below the bottom of the display window. Messy!
  285.       Revn 5: Menus disabled while in edit or insert mode. It was
  286.                found possible to ask for a sort while lines were
  287.                marked selected. This crashed the program.
  288.       Revn 6: Bug fix. It wasn't possible to select bottom line of scroll.
  289.               Input device submenu extended to include HD0,1,2,3
  290.  
  291. Vn 43 Revn 0: Cosmetic changes to menus, as requested by users.
  292.                 At LAST I've found out how to put only available
  293.                 disk devices into the drive selection sub-menu!
  294.                 It meant an extra program module, but was worth it.
  295.  
  296.       Revn 1: More cosmetic changes requested by pedantic friends :-)
  297.  
  298.       Revn 2: Bug fix: If the saved file path was long, Gcat crashed.
  299.       Revn 3: Cosmetic changes, & tidying of coding used in Revn.2
  300.  
  301. Vn 44 Revn 0: Hopefully the scrolling now behaves correctly and is not
  302.                 upset by different amounts of vertical screen overscan.
  303.       Revn 1: Bug preventing bottom 1 or 2 lines being selected: fixed.
  304.       Revn 2: Further problems fixed with scrolling on different screen
  305.               sizes. Is this problem finally fixed? Let's hope so.
  306.  
  307. It was my intention to change to ASL requesters. The file requester is
  308.   easy, but a two-gadget input requester is very messy since ASL doesn't
  309.   support this and a further IDCMP channel has to be set up. Using
  310.   Req is far simpler, and in my opinion Req does a nicer file requester.
  311.  
  312. Further development is unlikely. This project has gone on far too long 
  313.   (about 3 years) and I'm bored with it. But I'm still fixing bugs.
  314.  
  315.          --------------------------------------------------
  316. BUGS?
  317. ------
  318. 1. If you ask to "Write to disk" a very large catalog (e.g. all of dh0:)
  319.   and try to put output to a file in ram: you can get a 'guru'. On a reset
  320.   & retry, the problem goes away. This is with plenty of free ram: so
  321.   maybe it's due to memory fragmentation?
  322.  
  323. 2.  Under low memory conditions the program may hang or crash with a
  324.   "MemoryInsane" alert. The program checks that memory is available while
  325.   reading in data, but certain activities such as sorting evidently need
  326.   more memory & you can run out. I've not met this in regular use with large
  327.   catalogs of 3 or 4 thousand files, but a tester has reported it. The problem
  328.   may be caused by memory fragmentation, so maybe a reset before running would
  329.   avoid it.
  330.  
  331. 3. In Vn 43.01 a small bug turned up when I had more than 11 disk type
  332.   devices available for data input. The "source drive" submenu didn't have
  333.   enough slots in it, and the parent menu was corrupted. You can now have
  334.   up to 15 possible input devices before any problem arises.
  335.  
  336.   The program has been tested on 68000, 68030 and 68040 processors, and with
  337. Enforcer. No hits were found.
  338.  
  339. User Problems
  340. ---------------
  341.   Bugs or nasties may be reported to me:-
  342.     a) Through fidonet: 2:2500/167.15
  343.              or usenet: gnome@martinac.demon.co.uk
  344.     b) By a message on my Bulletin Board "Moonlight" which is open most
  345.          nights 6pm - 8am.  Tel: +44 (0)1234 212752  (logon, fax or netmail).
  346.          1200 to 14400 baud, V32bis. Standard 8N1 protocol.
  347.     c) By snail mail at the address below.
  348.  
  349.   If possible please supply enough detail so that I can repeat what you
  350.     did to reproduce the bug you observed.
  351.  
  352. Credits
  353. =========
  354. Thanks to....
  355.  
  356.  Jim Perry of "Studio Services" for field-testing this program, and for
  357.     asking for the sort by disk-name. 
  358.  Bil Irving and Anthony Keeley for suggestions, advice & much winding me up.
  359.  Steve Parkinson for helping with programming problems & showing me how to
  360.     do the sort.
  361.  Chris Sumner for reporting some bugs I didn't know about.
  362.  Phillip Lindsay for the coding to list available disk devices - which I
  363.     discovered one day on Usenet.
  364.  Gavin Hamill for suggestions for improvement.
  365.  Mel Potter for testing, and screen-grabs showing the scroll problem.
  366.  Pink Floyd, Queen, and Nescafe Gold Blend for keeping me awake.
  367.  
  368. -----------------------------
  369. Version 44    11 May '95
  370.  
  371. John Marchant,  43 Bowhill, Putnoe, Bedford MK41 8EQ,  UK.
  372. Fidonet:  2:2500/167.15   Internet: gnome@martinac.demon.co.uk
  373.