home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d8xx / d854 / upcat.lha / Upcat / Upcat.doc < prev    next >
Text File  |  1993-03-16  |  17KB  |  462 lines
  1.      *****************************************************************
  2.      *                                                               *
  3.      *                   Upcat - Disk catalog program                *
  4.      *                                                               *
  5.      *                          Version 1.0                          *
  6.      *                                                               *
  7.      *                         16 March 1993                         *
  8.      *                                                               *
  9.      *                 Copyright © 1993 Frans Zuydwijk               *
  10.      *                                                               *
  11.      *****************************************************************
  12.      
  13.      
  14.      Table of contents
  15.      
  16.       1. Introduction
  17.       2. Distribution
  18.       3. Running Upcat
  19.       4. Screen layout
  20.       5. Project menu
  21.       6. Settings menu
  22.       7. Catalog menu
  23.       8. Display menu
  24.       9. Catalog file layout
  25.      10. Developing environment
  26.      11. Bug reports
  27.      12. History
  28.      
  29.      
  30.      
  31.      1. Introduction
  32.      
  33.      Upcat is a disk catalog program with the following features :
  34.      
  35.         - Read file information from disks.
  36.         - Store it in a catalog in memory.
  37.         - Save/load catalogs to/from disk.
  38.         - Display catalog in several ways.
  39.         - Select files to be displayed.
  40.         - Print (selection of) catalog.
  41.         - 32 user definable categories.
  42.         - Add comment to files in catalog.
  43.      
  44.      Upcat requires Release 2.04 or higher.
  45.      
  46.      
  47.      
  48.      2. Distribution
  49.      
  50.      Upcat is NOT Public Domain, but copyrighted freeware : it may be
  51.      distributed and used freely.
  52.      
  53.      Upcat may not be sold, but inclusion in a PD-library is permitted as
  54.      long as only a SMALL fee is charged to cover the costs of copying and
  55.      distribution. The Fred Fish Library is the perfect example.
  56.      
  57.      Program and documentation must be distributed together.
  58.      
  59.      The files in the distribution are : Upcat, Upcat.info, Upcat.doc,
  60.      Upcat.doc.info, Example.cat, Example.cat.info.
  61.      
  62.      
  63.      
  64.      3. Running Upcat
  65.      
  66.      Upcat may be started from Shell or Workbench. When started from Shell
  67.      the name of a catalog may be given as argument. Starting from
  68.      Workbench can be done by clicking the Upcat icon, or clicking the icon 
  69.      of an Upcat catalog, in which case the catalog will be loaded.
  70.      
  71.      If no catalogname is supplied and a default catalog is defined in the
  72.      Settings menu, the default catalog will be loaded.
  73.      
  74.      Upcat uses a 640 x 256 (PAL) or a 640 x 200 (NTSC) non-interlaced
  75.      screen. 
  76.      
  77.      Upcat will use your default system text font, provided it is 8 pixels
  78.      high and 8 pixels wide. If this font has a companion 9 pixels high and 
  79.      10 pixels wide, this will be used for gadget texts etc. Default
  80.      Topaz-8 and Topaz-9 will be used.
  81.      
  82.      Upcat is controlled by using the mouse to operate the gadgets and the
  83.      menus. Some keyboard equivalents may be used, as indicated on the
  84.      gadgets and in the menus.
  85.      
  86.      All changes are performed in the catalog, which is currently in
  87.      memory, and are lost, if you quit Upcat or load another catalog
  88.      without saving the catalog first. 
  89.      
  90.      
  91.      
  92.      4. Screen layout
  93.      
  94.      The screen consists of 3 areas :
  95.      
  96.      4.1 The main display area. 
  97.      
  98.      Here you see the catalog records. Clicking the left mouse button on a
  99.      record will select it. Depending on the type of the selected record
  100.      (volume, directory or file), one or two menu items in the Catalog menu
  101.      will be enabled. Instead of selecting the menu item or using its key-
  102.      board equivalent, a second click on the selected record is effective
  103.      too, except for 'Delete Record'.
  104.      
  105.      4.2 The title bar.
  106.      
  107.      This shows you the catalog name and the number of volumes, directories
  108.      and (selected) files in the catalog. After the number of files you see
  109.      either '(A)' or '(S)', this indicates whether all or a selection of
  110.      the files are currently displayed. 
  111.      
  112.      Selecting the Window Close gadget in the upper left corner is the same
  113.      as selecting 'Quit Upcat' in the Project menu, but this has no effect
  114.      when a requester is displayed.
  115.      
  116.      4.3 The scroll bar in the right border.
  117.      
  118.      This shows which part of the currently displayed records is visible on
  119.      screen. 
  120.      You can move through the records by operating the arrow gadgets at the
  121.      bottom of the scroll bar, by moving the knob of the scroll bar, or by
  122.      clicking above (screen up) or below (screen down) the knob. 
  123.      Keyboard equivalents are : cursor up, cursor down, shift cursor up
  124.      (screen up), shift cursor down (screen down), Alt or Ctrl cursor up
  125.      (top of catalog), Alt or Ctrl cursor down (bottom of catalog). 
  126.      
  127.      
  128.      
  129.      5. Project menu
  130.      
  131.      5.1 New
  132.      
  133.      A new, empty catalog will be created in memory. If there is currently
  134.      a catalog in memory, which is changed and not saved, a requester will
  135.      pop up to ask you whether the catalog may be deleted or not.
  136.      
  137.      5.2 Open
  138.      
  139.      A catalog will be loaded from disk. By means of a file requester you
  140.      can select directory and catalog. If there is currently a catalog in
  141.      memory, which is changed and not saved, a requester will pop up to ask
  142.      you whether the catalog may be deleted or not.
  143.      
  144.      5.3 Save
  145.      
  146.      The catalog will be saved to disk. If the catalog has no name yet, you 
  147.      will be asked for the directory and filename by means of a file
  148.      requester.
  149.      
  150.      5.4 Save As
  151.      
  152.      The catalog will be saved to disk in another directory and/or with
  153.      another filename. You must supply this information in a file
  154.      requester.
  155.      
  156.      5.5 Print
  157.      
  158.      Send the currently selected or all records to the printer (PRT:). This 
  159.      is a rather simple print, no print formatting is done. All records,
  160.      which are currently displayed, will be sent to the printer in the
  161.      current display format.
  162.      
  163.      5.6 Print As
  164.      
  165.      Does the same as Print, but writes the records not to the printer, but 
  166.      to a disk file. You must supply directory and filename in a file
  167.      requester.
  168.      
  169.      5.7 About
  170.      
  171.      Displays the About requester.
  172.      
  173.      5.8 Quit Upcat
  174.      
  175.      The current catalog is removed from memory and Upcat quits. If there
  176.      is currently a catalog in memory, which is changed and not saved, a
  177.      requester will pop up to ask you whether the catalog may be deleted or
  178.      not.
  179.      
  180.      
  181.      
  182.      6. Settings menu
  183.      
  184.      By means of the Settings menu you can set several options :
  185.      
  186.      6.1 Input device. 
  187.      
  188.      Select the device from which the file information must be read. In the
  189.      submenu you see the available devices. Default 'df0:'.
  190.      
  191.      6.2 Default directory/catalog. 
  192.      
  193.      Select the default directory where catalogs must be stored. If you
  194.      select a default catalog too, this catalog will be loaded when Upcat
  195.      is started.
  196.      
  197.      6.3 Default display. 
  198.      
  199.      Select the default display type. This does not affect the current
  200.      display, use the Display menu for that.
  201.      
  202.      6.4 Create icons. 
  203.      
  204.      If checkmarked, icons will be created for catalog files during save,
  205.      unless they already exist. If not checkmarked, existing icons will be
  206.      removed during save. Default ON.
  207.      
  208.      6.5 Exclude .info. 
  209.      
  210.      If checkmarked, files with names ending with '.info' (icon files) will
  211.      be excluded from the catalog during a 'Insert Volume' or 'Update
  212.      Volume' operation. Default OFF.
  213.      
  214.      6.6 Save Settings. 
  215.      
  216.      If you select this, the choices from the Settings menu will be saved
  217.      in a file 'Upcat.prefs'. You may choose the directory where this file
  218.      will be saved, either the directory where the program Upcat was loaded
  219.      from, or the directories 'ENV:Upcat' and 'ENVARC:Upcat'. These latter
  220.      directories contain all system preferences files too. 
  221.      
  222.      At startup, Upcat will look in the program directory first and then in
  223.      the 'ENV:Upcat' directory. If 'Upcat.prefs' is not found, the Upcat
  224.      defaults will be used.
  225.      
  226.      
  227.      
  228.      7. Catalog menu
  229.      
  230.      7.1 Show Vol/Dir
  231.      
  232.      This item is usually disabled. It is enabled when the Display type is
  233.      'Volumes only' or 'Directories only' and you click on a record. This
  234.      record is highlighted then. Selecting this item or clicking a second
  235.      time will change the Display type to 'Hierarchy' and will display the
  236.      selected volume or directory.
  237.      
  238.      7.2 File Info
  239.      
  240.      This item is usually disabled. It is enabled when you click on a file
  241.      record, which is highlighted then. Clicking a second time or selecting
  242.      'File Info' brings up the File Information requester, which shows you
  243.      all available information about the file.
  244.      
  245.      You can mark categories for the file by selecting category gadgets.
  246.      
  247.      The comment field may be edited. Originally this contains the comment
  248.      from the file header on disk, buy you may change it.
  249.      
  250.      In case a volume is updated, the existing comment and category
  251.      information of the files is preserved.
  252.      
  253.      7.3 Insert Volume
  254.      
  255.      The file information of the volume in the current Input Device will be
  256.      read and inserted in the catalog. Icon (.info) files will be excluded
  257.      if this is selected. If the volume is in the catalog already, you may
  258.      choose between 'Update' and 'Cancel'.
  259.      
  260.      7.4 Update Volume
  261.      
  262.      Same as Insert Volume, but if the volume is already present, the
  263.      information in the catalog will be updated with the new information
  264.      without asking you first. 
  265.      
  266.      Update means : delete records not existing in the new information,
  267.      insert records not existing in the old information, and replace old
  268.      records by new records with the same name, but keep the categories and
  269.      the comment of the old records.  
  270.      
  271.      7.5 Delete Record
  272.      
  273.      This item is usually disabled. It is enabled when you click on a
  274.      record, which is highlighted then. Clicking a second time or selecting 
  275.      'Delete Record' will bring up a requester asking you whether you want
  276.      to delete the volume or directory or file record(s) or not.
  277.      
  278.      7.6 Categories
  279.      
  280.      There are 32 user definable categories in each catalog. These
  281.      categories are saved in the catalog files.
  282.      
  283.      Selecting the 'Categories' menuitem in the 'Catalog' menu will bring
  284.      up the Categories requester. Select and edit the 32 string gadgets to
  285.      add or change a category. 
  286.      
  287.      Selecting a string gadget will enable the 'Delete' and 'Swap' gadgets. 
  288.      
  289.      Swapping two categories only affects the physical place of the
  290.      categories in the requesters. 
  291.      
  292.      Deleting a category will delete all references to this category in all
  293.      records of the current catalog in memory.
  294.      
  295.      Selecting the 'Load' gadget will bring up a file requester. Choose a
  296.      catalog and the categories information will be read from this catalog
  297.      and overwrite the current categories information in memory. In this
  298.      way you may use the same categories for more than one catalog.
  299.      
  300.      
  301.      
  302.      8. Display menu
  303.      
  304.      8.1 Hierarchy
  305.      
  306.      Displays the records in the same hierarchical way as they were found
  307.      on disk. For each level one space is indented.
  308.      
  309.      8.2 Volumes only
  310.      
  311.      Displays only the volumes in the catalog. You can display the contents 
  312.      of a volume by clicking it twice or clicking it once and selecting the
  313.      'Show Vol/Dir' item in the Catalog menu.
  314.      
  315.      8.3 Directories only
  316.      
  317.      Displays only the volumes and the directories in the catalog. You can
  318.      display the contents of a volume or directory by clicking it twice or
  319.      clicking it once and selecting the 'Show Vol/Dir' item in the Catalog
  320.      menu.
  321.      
  322.      8.4 Files - Name sorted
  323.      
  324.      Display the files only, sorted by name. If you select this and you
  325.      press a character key, the display jumps to the first filename, of
  326.      which the first character is equal to or higher than the selected
  327.      character.
  328.      
  329.      8.5 Files - Date sorted
  330.      
  331.      Display the files only, sorted by descending date and time.
  332.      
  333.      8.5 Files - Size sorted
  334.      
  335.      Display the files only, sorted by descending size.
  336.      
  337.      8.6 Paths/Files
  338.      
  339.      Display the files with the complete path. Empty volumes and
  340.      directories are displayed too.
  341.      
  342.      8.7 File Selection
  343.      
  344.      This brings up the file selection requester. Default all files are
  345.      selected for display.
  346.      
  347.      You may set the following selection criteria (each criterium used will
  348.      restrict the selection further) :
  349.      
  350.        - Name : substring which must occur in the file name. 
  351.          You may use the special character '*' as starting or ending
  352.          character of the substring. In the middle of the substring it is
  353.          just an ordinary character.
  354.          If the substring ends with '*', the filename must start with the
  355.          substring e.g. 'Up*'. If the substring starts with '*', the file-
  356.          name must end with the substring e.g. '*.LZH'. If the substring is
  357.          '*', all filenames will be accepted.
  358.      
  359.        - MinDate : The date of the selected files must be >= MinDate.
  360.      
  361.        - MaxDate : The date of the selected files must be <= MaxDate.
  362.      
  363.        - MinSize : The size of the selected files must be >= MinSize.
  364.      
  365.        - MaxSize : The size of the selected files must be <= MaxSize.
  366.      
  367.        - Comment : substring which must occur in the comment field.
  368.          Use of "*' is the same as for Name.
  369.      
  370.        - Protect : select files with any combination of protect bits. 
  371.          The protect bits are '-sparwed' (script, pure, archive, read,
  372.          write, executable, deletable). The position of these bits is
  373.          fixed.
  374.          Use the character to indicate that the protect bit must be set,
  375.          use '-' to indicate it must not be set, use '*' to indicate both
  376.          are accepted. For instance, '*s*****-' will select all script
  377.          files, which are not deletable.
  378.      
  379.        - Categories : select files by categories. 
  380.          You may select and checkmark the individual categories used for
  381.          the file selection. 
  382.          You may select and checkmark one of the 'Or' and 'And' gadgets.
  383.          'Or' means that a file to be selected must be in one or more of
  384.          the selected categories. 'And' means that a file to be selected
  385.          must be in all of the selected categories. 
  386.          Clicking the 'All' gadget will select all categories.
  387.          Clicking the 'None' gadget will deselect all categories. 
  388.          Clicking the 'Include No Category' gadget will select all files,
  389.          which are in no category.
  390.      
  391.        - Clicking the 'Select all files' gadget will set all gadgets in the
  392.          requester in such a way, that all files will be selected. This is
  393.          the default too.
  394.      
  395.      If any files are selected, the menu item 'File Selection' will be
  396.      checkmarked and the titlebar will show '(S)' instead of '(A)'.
  397.      
  398.      
  399.      
  400.      9. Catalog file layout
  401.      
  402.      9.1 General layout of a catalog file :
  403.        - The first record is always 'Upcat Catalog'.
  404.        - The second record is always 'Categories'.
  405.        - Next there are 0-32 category records.
  406.        - The next record is always 'Records'.
  407.        - The remaining records are the file records.
  408.        - Records are always separated by the linefeed character (hex 0A).
  409.      
  410.      9.2 Layout of a category record :
  411.        - Position number (0-31).
  412.        - /
  413.        - Category number (0-31).
  414.        - /
  415.        - Category name (max 15 characters).
  416.      
  417.      9.3 Layout of a file record  :
  418.        - Level number (0-255). Volumes are always at level 0.
  419.        - /
  420.        - Record type. 'V' = volume, 'D' = directory, 'F' = file.
  421.        - /
  422.        - Name (max 30 characters).
  423.        - /
  424.        - Size (0 for directories, free space in K's for volumes).
  425.        - /
  426.        - Date and time (12 characters YYMMDDHHMMSS).
  427.        - /
  428.        - Protect (max 2 hex characters).
  429.        - /
  430.        - Categories (max 8 hex characters).
  431.        - /
  432.        - Comment (max 79 characters).
  433.      
  434.      
  435.      
  436.      10. Developing environment
  437.      
  438.      Computer : A2000, 1 MB Chip RAM, 2 MB Fast RAM.
  439.      Harddisk : Supra WordSync Series II + Quantum 52 MB.
  440.      OS       : 2.04
  441.      Compiler : SAS/C 6.2
  442.      
  443.      
  444.      
  445.      11. Bug reports
  446.      
  447.      Bug reports, comments etc. can be sent to:
  448.      
  449.          Frans Zuydwijk
  450.          Konijnenweide 84
  451.          2727GH Zoetermeer
  452.          Nederland
  453.      
  454.      
  455.      
  456.      12. History
  457.      
  458.         - Version 1.0 : 16 March 1993
  459.                         First release.
  460.      
  461.  
  462.