RK High Performance Archiver v1.04.1 alpha
==========================================

Welcome to the latest version of my file archiver. Below I have
written up some documentation on how to use RK and on what has
changed.

What's new?
===========

New to v1.04.1a:
* Now has a 'normal' compression mode that is a fast and memory efficient
  version of the max mode. This will hopefully bridge the gap between the
  fast mode and the max mode.
* Multi-volumes are now disabled by default, so growable ram drives are a
  valid target for archives.
* Fixed the bug where both win32 sfx modules crashed when not given default
  output directories.
* Fixed the bug which corrupted the last byte in some text files.
* The drive letter is no longer stored if relative paths is selected,
  even if the file is from another drive than the current.

New to v1.03.1a:
* Now comes with three different sfx stubs - Win32 GUI, Win32 console
  and DOS console.
* Supports colours in scripts etc.
* New compression algorithm added for 8bit TGA and BMP files.
* Updated audio compression algorithm is faster and better and now has
  three compression levels.
* Alternative view added for compatibility with archive managers. This
  view doesn't muck up the filename.
* Removed the buggy EOL filter - consequently worse compression on
  some text files but it no longer screws up. I am working on a new one
  that works better on most files, but have yet to finish it.
* Added new text filters that work on almost all text types for
  several % improvement.
* Modified the -mx algorithm to be more adaptive. Get 3-5% improvement
  on sets of many small text files.
* Fixed the WAV compression bug of v1.02a05.
* Fixed a WAV parsing bug which would crash on a few WAVs with extra
  header data.
* Cleaned up internal support for codepages for internationalisation
  of archived filenames. I gave up on unicode support as OS support is
  way to flaky and inconsistent. Maybe someone can support UTF-8 in
  the future once the sources are released.

Usage
=====

The command line help contains a very concise review of the command
line syntax. I'll elaborate on the options here...

-c        Create archive. This will create a new archive and add the
          specified files to it. It will prompt to overwrite if an
          existing archive already exists with the same name.
          This is the default, so its a bit pointless using it
          explicitly.
            eg. rk -c test *.txt   (equivalent to 'rk test *.txt')

-a        Add to archive. This will add the specified files to an
          already existing archive.

-e        Extract files without pathnames. This will extract files from
          an already existing archive, ignoring any pathname
          information. If no files are specified then by default all
          files are extracted.

-x        Extract files with pathnames. This will extract files from
          an already existing archive, preserving any pathname
          information. If no files are specified then by default all
          files are extracted.

-v[av]    View archive contents. There are three possible types of view:
             -v    Default view, fits info onto the 80 column console.
             -va   Alternative view. This view doesn't try to fit within
                   80 columns and so preserves the filename. Should be
                   useful for all those people using archive managers.
             -vv   Verbose view. This outputs all the file directory
                   information in a name value pair format. If you want
                   to support RK archives then parsing this view will
                   give you all the info you will need.

-i        Check archive integrity. This will check the CRC on all the
          files in the archive.

-t[s124]  Type of archive. This option specifies the maximum length of
          the sections in the archive containing multiple files. The
          default is -ts which specifies no limit. The other numbers
          specify a megabyte limit.
          The sections are such that accessing any file within a given
          section requires the decompression of all preceeding files in
          the section. The lower the limit, the less of these there will
          be and hence random access will be easier.
          (Note that this option will become important when the delete
          file feature is added. In this case sections with a limit to
          their size can be decompressed and modified in memory)

-I[0..5]  The level of information displayed while RK works. The
          levels are as follows:
             0 - No information.
             1 - Total progress only.
             2 - Displays info after compressing each file. No progress
                 displayed during compression.
             3 - All progress information on a single line.
             4 - Normal display (default).
             5 - Verbose. Displays compression ratio for each file
                 after compressing it, and total execution time.


-p[0rf]   Path storage options:
            0 - Store no paths.
            r - Store relative paths.
            f - Store full paths.

-ed[+-]   Include empty directories. If -ed- is specified then empty
          directories will be ignored.

-TNNNN    The table size used by the fast and normal modes (max
          16384). A larger table size will be slower, and will not
          always provide better compression.

-BNNNN    The buffer size (in kb). This is the size of the buffer for
          both the fast, normal and max modes. A larger buffer will
          allow the algorithm to refer to more data when compressing,
          and consequently _may_ improve compression (it usually will
          not harm compression ratio).

-MNN      The PPMZ model size for the max mode (in Mb). This only
          affects the normal and max modes, and a larger model
          generally will increase compression ratio (esp. for long
          files or large sets of similar files).
          NB. Model sizes greater than 8Mb will likely have no effect
          on the normal mode, as it uses much less memory than the max
          mode.

-r        Recurse through subdirectories when finding files.

-y        Assume yes to all questions.

-k<pwd>   Encrypt with the qiven password.

-K<file>  Encrypt with the key in the file. The file should contain
          one line consisting of 32 hex digits.

-O        Overwrite existing files when extracting.

-s[ta]    Sort by type or analysis. By default the order will be
          determined by a heuristic based on the analysis of the
          files. By selecting sort by type rk will take less time
          analysing the files and will order them according to their
          extension.

-SFX      Create a self extracting archive. By default the Win32
          version will use the Win32 stub.

-S<stub>  Create a self extracting archive using the given stub. Use
          this option in order to use the other self extracting stubs
          eg. 'rk -Sdos.sfx test *.txt' will create a dos based self
          extracting archive.

-A[rsh+-] Include files according to their file attribute. This option
          works in a double negative manner. That is files with
          attributes explicitly excluded will not be included.
          eg. 'rk -Ar-s+h- test *.txt' will exclude all files with
          hidden or read-only attributes. By default hidden files are
          excluded.

-D<dir>   Specify the destination directory for extraction.

-m[...]   Compression method. There are two main compression methods,
          each with 3 levels.
             -mf[1..3]   The fast mode (level1 to level3).
             -mn[1..3]   The normal mode (level1 to level3).
             -mx[1..3]   The max mode (level1 to level3).

-mw[fnx]  The WAV compression method. When RK comes accross a WAV file
          it will automatically use a specific WAV compression method
          instead of the main method. With this option you can specify
          the amount of work RK spends on compressing WAVs.
             -mwf    Fast mode.
             -mwn    Normal mode.
             -mwx    Max mode.

-f[...]   The filtering method to use. There are several filters that
          can be applied to the data as it is being compressed.
          Normally rk will select the appropriate automatically on a
          per file basis. By using this option it is possible to force
          certain filters to be used or not. The filters are as
          follows:
             -fd{n}  Delta filter where n is a number from 1 to 16. 
                     This filter performs the transform
                     y[i]=x[i]-x[i-n].
             -fe     The x86 EXE filter. This does JMP/CALL
                     translation which improves compression ratio on
                     x86 executable code. RK can automatically
                     recognize most Win32 and DOS exe types, but I do
                     not recognize unix formats yet.
             -ft     Text filter. This performs a transformation on
                     textual data that improves the compression ratio.
          All filters can be forced on or off by using + or -. If a
          filter is forced off then RK will not use it even if it
          recognizes the file type.

-V[NNNN]  Enable multiple volumes. Optionally you can specify the
          length of the volumes to create. If this is not specified
          then the length is determined dynamically by available disk
          space. You can use M for megabytes and K for kilobytes to
          modify the number.

-as       Add a script file to an archive. Script files can be used to
          create archive comments, and direct the default behaviour of
          the self extractors.

-ds       Delete script from archive. Will remove the script in the
          archive if there is one present.

-vs       Prints the script from the archive onto the console.


Scripts
=======

Scripts can be added to archives to enable some automatic functionality,
such as archive comments and self extractor defaults. 

My hope is that the scripting language will eventually grow to support
a fully functional self installer, so at present the language is
pretty loose and simple.

If you have any requests for script commands, or things that you cannot do
with a script but would like to, then please e-mail me. I am keen to get
some feedback on archive scripts as they are pretty unique.


The scripting language has three main constructs - constants, commands
and events.

Constants:
  Constants can be defined either with the define command or the text
  command, both of which are described below.

  define <name> <value ...>
    Defines a constant name with a given value.

  text <name> ...body... [newline]&end
    Defines a constant name with the value given by the body text. The
    body text is terminated by the string '&end' on a new line. This
    is useful for creating constants with large bodies of text.

Commands:
  Commands are used within event handlers. They are pretty self
  explanatory.

  display <name>|<text>
    Displays a message without stopping. The argument can either be
    the name of a constant or a literal string to be displayed.

  message <name>|<text>
    Displays a message and waits for confirmation (a keypress or OK
    button depending on the environment). The argument is the same as
    for display.

  textdlg <name>|<text> [<param>=<value> ...]
    Displays a text dialog. In command line environments it will act
    just like the message command. In windowed environments it will
    display a dialog box with OK and Cancel buttons. There are three
    possible named parameters:
      ok=<value>     The value is the name of the event to fire when the
                     OK button is pressed.
      cancel=<value> The value is the name of the event to fire when
                     the cancel button is pressed.
      title=<value>  The value is used as the caption for the dialog
                     box.
 
  open <name> [<args> ...]
    Executes the program <name> with optional arguments <args>. Note
    that this command makes use of the ShellExecute in windows and as
    such will recognise any file with an association in the shell. For
    example you can install reg files with this function.
    The default directory if no path is given for the program is the
    destination directory.

  exit [<exit_code>]
    Exits the program with an optional exit code.

Events:
  Events are handled with event handlers which have the following
  form:

  on <event> [<event> ...] do
    <command> ...
      ...
  end

  So between on and view you can place a list of events that this
  handler will be called for. When one of the specified events is
  fired the commands in the event handler are executed.

Predefined events:
  Following is a list of predefined events:

  init     - This event is fired in the SFX modules after
             initialisation (ie. before anything is done).
  view     - This event is fired in all modules before an archive is
             viewed.
  extract  - This event is fired in all modules before files are
             extracted from an archive.
  create   - This event is fired in the archiver before creating a new
             archive.
  add      - This event is fired in the archiver before adding files
             to an existing archive.
  check    - This event is fired in the archiver before performing an
             integrity check on an archive.
  finished - This event is fired in the SFX modules after finishing
             extraction.

  Any other name can be used as an event, however as yet the only
  command that fires other events is the textdlg command.

Special constants:
  The SFX modules all recognise a few special constants that can be
  used to set defaults.

  destination - The value of this constant is used as the default
                destination directory.
  overwrite   - This can either be 'yes' or 'no'. Whether the SFX
                should by default overwrite existing files when
                extracting.
  paths       - This can either be 'full' or 'none'. Specifies whether
                the SFX should default to extracting the full paths or
                not.
  title       - The title used by the main SFX window (only used in
                windowed environments).

Comments:
  Comments are signified with a '#' character. Everything after the
  '#' character on the same line is ignored.

Some examples are:

#---------start---------
# An archive comment (display the comment when viewing or extracting)

on view extract do
  display "This is the archive comment!"
end

#----------end----------

#---------start---------
# Defaults for the self extractor

define destination "c:\temp"  # Destination directory
define overwrite no           # Don't overwrite existing files
define paths none             # Ignore the file paths.

#----------end----------

And of course look at the script in the distribution sfx for another
example.


Contact Details
===============

If you find any bugs, have requests for features or just want to chat then
please e-mail me at <mtaylor@clear.net.nz>.

