!Help file for !Upd8LHSh v1.00 (24 June 1997)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Legal Drivel
~~~~~~~~~~~~
	Upd8LHSh is  Musus Umbra and Stefan Jokisch 1997.  It was
	created using DeskLib (the freeware C library for RISC OS machines).

	Upd8LHSh is FREEWARE: The authors retain copyright at all times,
	but permission is granted for distribution provided that *no* profit
	is made in so doing (a small charge to cover handling/media is
	acceptable), and the software is ditributed whole and unaltered.

	You are permitted to use and modify this software in any way you like,
	but you may not distribute modified copies (you should inform the
	author of any changes so that the official version may be updated).

	This software is supplied with absolutely NO WARRANTY of any kind,
	the author(s) cannot under any circumstances be held responsible for
	any damage/loss arising from the use, abuse or inability to use this
	software.

	DO NOT pester Stefan about problems with this software - contact
	me (Musus Umbra) instead.


What is it?
~~~~~~~~~~~
	Upd8LHSh is a simple utility program to update the PC versions of
the infocom classics The Lurking Horror and Sherlock to the Amiga
versions.  This update is desirable since the Amiga versions of these games
are capable of playing sound effects, whereas the PC versions are not.


What do I need?
~~~~~~~~~~~~~~~
	In order to upgrade your story files, you'll need:

	1. A valid story-file.  Upd8LHSh can only update the following
	   story-files:
	   	The Lurking Horror release 203, serial# 870506
	   	Sherlock release 21, serial# 981214
	2. Stefan Jokisch's conversion file(s) for the game(s) you wish
	   to upgrade (see below).

I'm afraid that if the story-file you have isn't one of the ones listed above,
you won't be able to update it. (Note that there is a release 219 of
the Lurking Horror that doesn't need updating anyway).

As for the conversion files, these are available from ftp.gmd.de along with
the sound samples the games actually play (as two archives: one for each of
the games).

The conversion file in each archive is the file ending '/CNV' (or as much as
will fit in the RISC OS 10 character filename). ie. the files LURKING/CNV
and SHERLOCK/C.


How do I use it?
~~~~~~~~~~~~~~~~
	Double-click on the !Upd8LHSh icon in a directory display.  After a
short period of disc activity, Upd8LHSh will install its icon on the iconbar
and open its main window.

The iconbar icon offers the usual menu (Info and Quit), and if clicked on
with Select or Adjust will (re)open the main winow.

Drag the story-file (type 11a Z-Code) of the relevant game to the main
window.  The program will check to make sure that the file is suitable for
updating, and if it is you'll see the icon under the Z-Code file icon change
to hold the name of the file.  If the story-file isn't suitable a window
will appear telling you why.

Drag the /CNV file (ie. the conversion file from the archive) to the main
window.  The program will check that the /CNV file matches the story-file,
and complain if it doesn't.

Once the two files have been dragged to the main window, the Update button
should un-grey itself (ie. become available).  Click on the Update button
to start the upgrade process.

If anything goes wrong during the upgrade, you'll be presented with an error
box telling you what, and no output will be produced (see later for an
explanation of what the errors mean).

All being well (after a bit of drive-light flashing :-), a standard 'Save' box
will appear allowing you to save the upgraded story-file.  If you try to save
the new story-file over an existing file, you'll be asked for confirmation.

DO NOT SAVE THE UPGRADED STORY-FILE OVER THE ORIGINAL ONE!!! (Please?)

That's it!


Special notes for floppy disc users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use the updater effectively from floppy disc, you'll need to follow the
following procedure:

	1. Start with a blank floppy (DD or HD - it doesn't matter).  If
	   you can spare 800K for a RamDisc, use this rather than a floppy!
	2. Copy the story-file and /CNV files onto the disc
	3. Copy a !Scrap onto the disc (eg. from your applications suite
	   discs).
	4. Run !Upd8LHSh (from whichever disc it's on).
	5. Double-click on the !Scrap on your disc
	6. Follow the procedure detailed above (be prepared for a wait)
	7. Save the updated file onto the disc.

Whatever you do, don't have !Scrap, the story-file or the /CNV files on
different discs - if you do, you'll be swapping discs till you wish you'd
actually read this bit first time around.



What do the error messages mean?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main errors produced by the update process are:

 couldn't open the ... file
	The program wasn't able to open a file it needed.  The story-file
	and /CNV file *must* be available for reading.

 couldn't create a temporary file
	The program needs to use a scrap file to generate the updated
	story-file.  For this to happen properly, !Scrap *must* be
	available.

 an error occurred whilst reading...
	Something nasty has happened whilst the program was trying to
	read information from the story/CNV file - it might be a disc
	error, or something else entirely.  Try again, and if that doesn't
	work try making a copy of the file and using that instead.

 an error occurred whilst writing...
	Something has gone wrong whilst the program was trying to write the
	updated story-file (as the scrapfile).  It could be a disc error,
	but it's most likely to be because you're out of disc space.

 the story file is the wrong version
 the updated file's checksum was wrong
	You should never get these two errors!  They are caused by the
	story- or /CNV file being corrupt or the wrong version.


History
~~~~~~~
1.00	First release version.  Basically a desktop front-end to modified
	versions of Stefan's update programs.

Contact Details
~~~~~~~~~~~~~~~
The Musus Umbra may be reached by:

	e-mail (should be valid until about September '97):
		A.J.Holdsworth@ncl.ac.uk

	snail:  until June '98:			After June '98:
			A.J.Holdsworth			A.J.Holdsworth
			47 Fawdon Park Road		c/o 23 Baronsway
			Fawdon				Whitkirk
			Newcastle Upon Tyne		Leeds
			NE3 2PL				LS15 7AW
			ENGLAND				ENGLAND


Musus Umbra, 24.06.97
