home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 2: Collection B / 17Bit_Collection_B.iso / files / 2042.dms / in.adf / docs / SHRINK.DOC.pp / SHRINK.DOC
Encoding:
Text File  |  1989-07-26  |  11.7 KB  |  282 lines
  1.  
  2.  
  3.  
  4.                            Shrink User's Guide
  5.  
  6.                      Version 1.01b (beta) - May 1992
  7.  
  8.  
  9.                         Written by Matthias Meixner
  10.  
  11.                    Copyright (c) 1992 by Matthias Meixner
  12.                            All rights reserved
  13.                           Not for commercial use
  14.  
  15.  
  16.  
  17.  
  18.    1- Disclaimer
  19.    ~~~~~~~~~~~~~
  20.    The author cannot be held liable for the suitability or accuracy of this
  21.    manual and/or the program(s) it describes.  Any damage directly or
  22.    indirectly caused by the use or misuse of this manual and/or the program
  23.    it describes is the sole responsibility of the user her/him self.
  24.  
  25.  
  26.    2 - Copyright/Distribution
  27.    ~~~~~~~~~~~~~~~~~~~~~~~~~~
  28.    Shrink, (c) Copyright 1992 Matthias Meixner. All rights reserved. This
  29.    Program is FREEWARE, so no financial donations are required (but welcome).
  30.    This  program may be freely distributed as long as all documentation and
  31.    executable(s) remain unchanged and are included with the distribution.
  32.    Also no profit is to be made by selling this program.
  33.    Shrink V1.01b must not be added to other PD-libraries than AmigaLibDisks
  34.    from Fred Fish without my written permission. The price must not exceed
  35.    the costs of disk, package and mailing.
  36.  
  37.    3 - Introduction
  38.    ~~~~~~~~~~~~~~~~
  39.    Shrink is a new archiver for the Commodore-Amiga computer similar to
  40.    LHA, lharc or zoo. It is not as fast as LHA, but compression rate is
  41.    better than the rate of all these other archivers. Shrink uses a new
  42.    IFF - format for its archives, that is designed to handle archives with
  43.    other programs (see IFF-documentation).
  44.  
  45.  
  46.    4 - System requirements
  47.    ~~~~~~~~~~~~~~~~~~~~~~~
  48.    Shrink will run on any Amiga system with at least 512KB RAM an one
  49.    diskdrive. But for compressing large files more memory is needed, because
  50.    shrink loads all files completely into RAM to reduce diskaccess.
  51.    A 68020, 030 or 040 processor is very useful to reducecompression time.
  52.  
  53.  
  54.    5 - Command line syntax
  55.    ~~~~~~~~~~~~~~~~~~~~~~~
  56.    The command line syntax is as follows:
  57.  
  58.    shrink [-options] <Command> <Archive> [dest path] [pattern1] [pattern2] ..
  59.  
  60.    [-options] are optional, [dest path] is only needed for extraction and
  61.    must end with ':' or '/', patterns are optional in some cases and
  62.    sometimes needed (see documentation of commands).
  63.    Patterns are the normal amiga patterns like #? or #?(x|y). Komplex
  64.    patterns like (#?|#?.c) are not supported.
  65.  
  66.  
  67.    6 - Adding files to archive
  68.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69.    There are several ways to add files to an archive. Shrink supports the
  70.    following commands to add files matching the pattern to the archive:
  71.  
  72.       'a':  (add)
  73.             Adds files to the archive if they are not already there.
  74.  
  75.       'aa': (add all)
  76.             Adds or replaces files in the archive. If the files was already
  77.             in the archive, its generation is increased by one.
  78.             (see generations)
  79.  
  80.       'f':  (freshen files)
  81.             Replaces a file in an archive if the file is newer than the file
  82.             in the archive. The generation of the older file is increased
  83.             by one. Files that have not been in the archive are not addes to
  84.             the archive.
  85.  
  86.       'u:   (update archive)
  87.             Files are added to the archive if they are not already in the
  88.             archive or are replaced in the archive if they are newer than
  89.             the files in the archive. In this case the generation is
  90.             increased by one.
  91.  
  92.    Options for adding files:
  93.    The compression method can be set using the -m option. (-m0 no compression
  94.    .. -m7 best compression [default]).
  95.    -r forces shrink to collect the files recursively, e.g. to compress
  96.    directories with subdirectories.
  97.    With the option -a shrink supports the archive flag. When the option is
  98.    set, only files with non-set archive flag are added to the archive. After
  99.    adding them to the archive, the archive flag is set.
  100.    -q (quiet mode) switches the progress indicator off when compressing.
  101.  
  102.  
  103.    7 - Testing archives
  104.    ~~~~~~~~~~~~~~~~~~~~
  105.    The commands 't(n)' and 'ta' are used to test archives if they contain any
  106.    errors. 't(n)' tests generation n of all files matching the pattern. If no
  107.    pattern is given, shrink uses #? as default. 'n' Is a number between
  108.    1 and 255 and specifies the generation that shall be tested. If it is
  109.    ommitted shrink assumes generation 1.
  110.    'ta' tests all files that are contained in the archive. Therefore it does
  111.    not support any patterns.
  112.  
  113.  
  114.    8 - Deleting files
  115.    ~~~~~~~~~~~~~~~~~~
  116.    Using 't(n)' or 'ta' you can delete files from the archive. With 'tn' the
  117.    generation n of a file is deleted from the archive. 'ta' deletes all
  118.    generations of the file.
  119.    When you delete files from an archive they are not really removed from
  120.    the archive, only their generation is set to 256. They are only removed
  121.    when packing the archive (see packing the archive). As long as they are
  122.    not removed from the archive they can be recovered again (see recovering
  123.    deleted files).
  124.  
  125.  
  126.    9 - Recovering deleted files
  127.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  128.    If you wish to get back deleted files or files with an older generation
  129.    you can use 'r(n)' to get back generation n of the file or 'ra' to get
  130.    back a deleted file. The generation of this file is set to 1. The
  131.    generation of the other files with the same name is increased by 1.
  132.    If there exist more than one file with the same name and the same
  133.    generation in an archive, you can use the -i(n) option to turn on the
  134.    file index mode. Then only the n-th file that matches the pattern is
  135.    referred by this command.
  136.  
  137.  
  138.    10 - Packing the archive
  139.    ~~~~~~~~~~~~~~~~~~~~~~~~
  140.    Packing is used to remove all deleted or older files from an archive.
  141.    'p(n)' removes all generations that are higher than n from the archive.
  142.    E.g. 'r255' removes all files with a generation higher than 255 i.e.
  143.    deleted files. Or if you only want to keep 5 generations of each file
  144.    use 'p5' to remove all older files. Shrink generates a backup-file when
  145.    packing an archive. This is disabled by using the -d option.
  146.  
  147.  
  148.    11 - Extracting files
  149.    ~~~~~~~~~~~~~~~~~~~~~
  150.    Extraction is done by using the command 'e(n)' or 'x(n)'. These commands
  151.    extract the generation n of the files matching the pattern. If n is not
  152.    given the first generation is extracted.
  153.    If you do not want the whole pathname to be extracted, use the -c option
  154.    to extract only the filenames. A special feature of this option is to cut
  155.    off part of the filename. This can be used to change the path during
  156.    extraction. For example the file ff500/c/MuchMore would be extracted as
  157.    df0:c/MuchMore by the following command:
  158.        shrink -cff500 x archive ff500/c/MuchMore
  159.    If you wish to set the archive flag of the extracted files. you can use
  160.    the -a option that does exactly this during extraction.
  161.    By using the index-file-mode with the -i(n) option one can refer to the
  162.    n-th file that matches generation and pattern. This is useful when there
  163.    are more than one file of the same name and generation in one archive.
  164.  
  165.  
  166.    12 - Extracting files on the screen
  167.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  168.    's(n)' extracts the n-th generation of the file on the screen. You can
  169.    use the same options that can be used for normal extraction.
  170.  
  171.  
  172.    13 - Listing the contents of an archive
  173.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  174.    'l(n)' or 'v(n)' prints the contents upto generation n of the archive on
  175.    the screen, sorted by name and generation. Use 'la' or 'va' to get a list
  176.    of all files and deleted files. It has the same effect as using 'l256'.
  177.  
  178.  
  179.    14 - Other options
  180.    ~~~~~~~~~~~~~~~~~~
  181.    '-q' disables the progress indicator during compression and decompression.
  182.  
  183.  
  184.    15 - Technical info
  185.    ~~~~~~~~~~~~~~~~~~~
  186.    Shrink uses a dictionary from 1024 upto 65536 bytes for compression due to
  187.    the compression-mode. String down to 2 bytes are replaced by their
  188.    reference to achieve maximum compression. Shrink uses dynamic arithmetic
  189.    encoding instead of huffman encoding to get a better compression rate.
  190.    Shrink is the first archiver on the amiga that uses this method for best
  191.    compression rate.
  192.  
  193.  
  194.    16 - IFF-Archive-Format
  195.    ~~~~~~~~~~~~~~~~~~~~~~~
  196.    Shrink uses a new IFF format for its archive files.
  197.    The structure is as follows:
  198.  
  199.    FORM xxxx CDAF  ; Compressed Data Archive File
  200.         ^^^^ length of FORM
  201.  
  202.    NAME xxxx archivers_name ; This chunk must be the first chunk in the
  203.                             ; archive to determine the archiver that is
  204.                             ; required for compression and decompression
  205.                             ; of files in the archive. The other functions
  206.                             ; like deleting or recovering files should
  207.                             ; work with every archiver using this format
  208.  
  209.  
  210.    FILE xxxx                ; This must be the first chunk of every file
  211.                             ; contained in the archive
  212.       UBYTE Checksum        ; The sum of all bytes in this chunk must be zero
  213.       UBYTE Method,Version  ; Method and version of the compression method
  214.                             ; that was used to compress this file
  215.       UBYTE Generation      ; Generation of the file: 0=new .. 255=deleted
  216.       USHORT SystemID       ; System ID of the computer on which the file
  217.                             ; was compressed.
  218.       ULONG Filesize        ; Original size of the file, the compressed
  219.                             ; size of the file is the size of the BODY chunk
  220.       UBYTE Year,Month,Day  ; Date of the file (year since 1900)
  221.       UBYTE Hour,Mins,Secs  ; Time of the file
  222.       USHORT CRC            ; CRC Checksum of the uncompressed file
  223.       ULONG Protection      ; File attributes on the computer of SystemID
  224.       UBYTE Filname[]       ; The rest of the length of this chunk is used
  225.                             ; to store the filename. This enables filenames
  226.                             ; of any lenght
  227.  
  228.    BODY  xxxx               ; This chunk contains the compressed data of the
  229.                             ; file. This must be the last chunk of every
  230.                             ; file in the archive.
  231.  
  232.  
  233.    Between the chunks FILE and BODY there can be as many chunks as the
  234.    archiver needs to store additional information about the file and/or
  235.    compression. Therefore these chunks must not be removed when packing or
  236.    modifying archives. One of these chunks is the NOTE chunk:
  237.  
  238.    NOTE xxxx filenote
  239.  
  240.    It contains the filenote of the file.
  241.  
  242.  
  243.    17 - SystemID's
  244.    ~~~~~~~~~~~~~~~
  245.    AMIGA        'AM'
  246.    ATARI_ST     'ST'
  247.    ARCHIMEDES   'AR'
  248.    MS_DOS       'MS'
  249.    UNIX         'UX'
  250.    MAC          'MA'
  251.    HELIOS       'HE'
  252.  
  253.  
  254.    18 - Something on bug reports
  255.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  256.    When sending in bug reports, please state exactly under what
  257.    circumstances the bug occurred, what equipment was used and what happened.
  258.    If possible also try to give me enough information to reproduce the bug.
  259.    It is very difficult to find bugs when you don't know exactly what
  260.    happened. Please don't just send messages like "it can't extract files
  261.    from archives sometimes", that really doesn't help me. If possible,
  262.    submit the offending file/archive to me so I can test it myself, or give
  263.    me a pointer where I can find the archive.
  264.  
  265.  
  266.    19 - Notes
  267.    ~~~~~~~~~~
  268.    Bug reports, suggestions, postcards, flames, criticism, contributions,
  269.    ideas, gifts, etc., etc., etc........... to:
  270.  
  271.  
  272.                      Matthias Meixner
  273.                      Sandberg 13
  274.                      W-6417 Hofbieber 2
  275.                      Germany
  276.  
  277.  
  278. P.S.  The CRC-Checksum value of shrink is D6EF. You can use shrink itself
  279. to test the checksum by simply adding itself to an archive. Then the checksum
  280. can be controlled by listing the contents. So you can easily check if
  281. shrink is infected by a virus.
  282.