               A Quick Introduction to LHARC 0.24
               ==================================

1   Intooduction to LHARC

As a compression/decompression utility, LHARC is now much less
popular that it used to be; however, it is still in fairly wide
use (esp. in Japan).

This is a port of the standard LHARC utility, with a few bells
and whistles to make it easier to use on RiscOS; it has two
advantages over SparkFS for LZH files:

   1) It provides write access to LZH archives (SparkFS is read
      only for LZH);
 & 2) It's free.

The standard DOS to RiscOS filename conversion rules have been
used: thus, the DOS filename tharg.txt becomes tharg/txt on
RiscOS. Throughout these notes, the RiscOS format is used, but
internally the archive uses Unix/DOS conventions.

Normally, DOS and Unix LHARC files have the extension ".lzh";
the RiscOS port supports this, but uses "/lzh" rather than
".lzh".

Currently, LHARC is a command line utility only; however, I am
working on a desktop front end to make it easier to use.

                     ~~~~~~~~~~~~~~~~~~~~~~~~

2   Command format

The general format of a command is:

  LHARC <c>[<o>..][w=<path>] <archive-name> [<filename>...]

Where:

   <c> is a single letter indicating the command to be executed
(eg c for create, a for add, x for extract, etc)

   <o> is a single letter option code (eg v for verbose)

On Unix & DOS, the w=<path> option is only used when extracting
files, and gives a directory into which the archive was to be
extracted; this port also allows it to be used when creating or
adding files (see Examples).

The <archive-name> given may drop the "/lzh" part of the filename,
if it present.

The main exception to this general format is the command

  LHARC

by itself, which prints some help text.

Personally, I don't find LHARC particularly intuitive to use,
and it is best described by example.

                     ~~~~~~~~~~~~~~~~~~~~~~~~

3   Examples of use

  i) List

     To list the contents of the archive tharg (or tharg/lzh):

     LHARC l tharg

     or

     LHARC v tharg

     The later format gives somewhat more information.


 ii) Extract

     LHARC x tharg

     will extract the entire contents of the archive tharg into
     the current directory.

     LHARC xw=mydir tharg

     will extract the entire contents of tharg into directory
     mydir.


iii) Extract specific files

     LHARC x tharg eric/txt fred/jpg

     will extract the files fred/txt and fred/jpg into the current
     directory.


 iv) Create

     LHARC c tharg eric/txt fred/jpg

     will create a new archive called tharg/lzh containing the
     files eric/txt and fred/jpg (from the current directory).

     LHARC cw=mydir tharg eric/txt fred/fpg

     will create a new archive called tharg/lzh containing the
     files eric/txt and fred/jpg from directory mydir.

     LHARC c tharg mydir

     Will create an archive called tharg containing directory
     mydir and its entire contents.

     LHARC maintains a pseudo-directory structure in its archives,
     so de-archivers will perceive mydir as a directory. This is
     not always what is required, so this port also provides a
     special (somewhat aberrant format) command:

     LHARC cw=mydir tharg

     This has a similar effect to "LHARC c tharg mydir", except
     that the archive does not include the top-level directory
     mydir. If mydir contains the files eric/txt and fred/jpg,
     then

     LHARC c tharg mydir

     will create an archive with the contents:

     mydir
     mydir.eric/txt
     mydir.fred/jpg

     while

     LHARC cw=mydir tharg

     will generate an archive containing:

     eric/txt
     fred/jpg


  v) Add

     LHARC a tharg help/txt

     will add the file help/txt to archive tharg.

     The add function works exactly as the create function,
     except that the archive must already exist. Any files with
     the same name as those added are overwritten.


 vi) Delete

     LHARC d tharg help/txt

     Will delete the file help/txt from the archive.


LHARC includes a number of other commands, most of which seem
fairly pointless. The rest, as they say, is left as an exercise
for the reader.

                     ~~~~~~~~~~~~~~~~~~~~~~~~

4   RiscOS-specific options

In addition to the use of the i & w=path options on create and add
operations, (the 'i' option on input is only relevant when a
directory is amongst the included files, and prevent lharc from
including all the files inside the directory; it is mainly there
for use by the desktop front end !DtLHARC) this port includes a few
RiscOS-specific options to make life a bit easier:


   i) RiscOS normally limits filenames to 10 characters, and this
limit is imposed by LHARC; however, if the 'l' option is included
in the command line, any length filename is allowed.

eg

      LHARC x tharg longname/txt

will generate a file called "longname/t"; but

      LHARC xl tharg longname/txt

will generate a file called "longname/txt".

  ii) Sometimes it is convenient to retain the entire extension,
rather than to truncate it to fit the entire filename into the
RiscOS 10-character filename limit. To support this, there is the
option 'r' (retain). This is only relevant if the 'l' option is
not present.

eg

      LHARC x tharg longname/txt

will generate a file called "longname/t"; but

      LHARC xr tharg longname/txt

will generate a file called "longna/txt".

NB. The names of archives also apply the same filename length rules.
eg

     LHARC c long_archive_name <list of files>

will create an archive called "long_archi";

     LHARC cr long_archive_name <list of files>

will create an archive called "long_a/lzh";

     LHARC cl long_archive_name <list of files>

will create an archive called "long_archive_name/lzh".

 iii) Automatic conversion from Unix/DOS filename extensions to
RiscOS filetypes is provided by the 'e' option; this option works
on both extraction and insertion.

Assuming "fred" is a JPEG file, then

      LHARC a tharg fred

will generate a file called fred in archive tharg; but

      LHARC ae tharg fred

will generate a file called fred/jpg in the archive.

If LHARC does not know of an appropriate extension for a given
file type (eg an Impression file), it will generate a three
character file extension from the hex value of the file type
(eg a file called "data" of type &fed will generate an entry in
the archive called data/fed).


      LHARC xe tharg longname/txt

      will extract the file longname/txt and call it "longname".
It will also be typed as a text file.

NB Although the file-extension stripping is configurable, the
filetype guessing cannot be disabled on extract. Any file whose
extension is not recognised will be typed as "Data" unless the
extension can be interpreted as a hex value, in which case the
RiscOS file type will be generated using that hex value
(eg Data/fed will be filetyped as &fed).

  iv) The '~' option will suppress the automatic backing up of
archives (see mext section).

                     ~~~~~~~~~~~~~~~~~~~~~~~~

5   Backup archives and temporary files.

Whenever LHARC performs an operation that modifies an existing
archive (eg add, delete), it creates a backup version of the
archive, with a file extension "/bak" (eg tharg/lzh is backed
up as tharg/bak). Any existing file of this name will be lost.

                     ~~~~~~~~~~~~~~~~~~~~~~~~

6   Installation

To install LHARC, simply drag the executable to your library
directory (or any directory that is referenced in the Run$Path
variable).

                     ~~~~~~~~~~~~~~~~~~~~~~~~

7   Known problems and bugs

  i) Directory datestamps

     This version of LHARC does not correctly set the datestamp
     of a directory when it is extracted. I'm working on this.

 ii) Not a bug, but...

     If you are running SparkFS, you should disable LZH support
     while LHARC is being used. If you do not, LHARC is liable
     to complain when you try to open an existing archive.
     Alternatively, you can set the filetype of the archive to
     "Data", and it should work OK.

                     ~~~~~~~~~~~~~~~~~~~~~~~~

8   Conditions of use

This port of LHARC is FREEWARE and can be distributed freely. The
only condition is that it is distributed in its entirety, including
this file.

This port is based on the public domain BSD Unix implementation. 

                     ~~~~~~~~~~~~~~~~~~~~~~~~

9   Oustanding bugs

None of which I am aware.
     
                     ~~~~~~~~~~~~~~~~~~~~~~~~

10  Version history

  0.01-0.10   Development versions
  0.11-0.17   Beta test upgrades
  0.18        First general release
  0.19        Fixed ghastly bug with 'e' option ("Divide by zero")
  0.20        Added r[etain] option
  0.21        Fixed bug with Unix/RiscOS file matching during delete
  0.22        Subtle change imposed by demands of desktop front end
  0.23        Another change imposed by desktop front end
  0.24        Fixed "Please insert <disc>" bug on OS3.1

                     ~~~~~~~~~~~~~~~~~~~~~~~~

11  Disclaimer

LHARC is distributed as is, and the author will not accept any
responsibility for any resultant damage, whatever its form.

                     ~~~~~~~~~~~~~~~~~~~~~~~~

12  Bug Reports

Irrespective of the formal disclaimer above, I am perfectly
happy to receive emails describing any bugs discovered, and I
will do my best to fix them quickly.

Nick Roberts
tigger@argonet.co.uk
