
			   -------------------
			     J z i p  2 . 1 
			   -------------------
			     User's  Manual

			     By John Holder
			   (jholder@frii.com)

	Contents:
		1.0 Introduction
		
		2.0 What is Jzip?  
		    2.1 Description
		    2.2 How do I play Infocom/Inform Games?
		    2.3 What platforms does Jzip run on?
		
		3.0 Features, and how to use them
		    3.1 Command line options
			3.1.1 Setting the screen size
			3.1.2 Setting the size of the command history
			3.1.3 Getting version information
			3.1.4 Using STRICTZ and why you would want to
			3.1.5 DOS only features
			      - Monochrome mode
			      - EGA/VGA bigscreen mode
		    3.2 Using the command history buffer
			3.2.1 Under DOS
			3.2.2 Under UNIX/Atari ST
		    3.3 Using the INFOCOM_PATH environment variable
			3.3.1 Under DOS
			3.3.2 Under UNIX
			3.3.3 Under Atari ST
		    3.4 Portable Save Game files
		    
		4.0 Utilities for Jzip
		    4.1 Jzexe - make DOS native .exe game files
		    4.2 ckifzs - check a Quetzal save file's validity

		5.0 Building Jzip
		    5.1 UNIX/BeOS
		    5.2 DOS
		    5.3 Atari ST
		    5.4 Bugs

		6.0 Known Bugs

		7.0 Credits

		8.0 License Agreement / Disclaimer


	___________________________________________________________

	1.0 Introduction
		
	    Welcome to the Jzip User's manual.  I hope this 
	    program is useful to you, and that it provides you with
	    many hours of enjoyment.  This release of Jzip has seen
	    incredible amounts of improvement - ZSTRICT checking,
	    Z-Spec 1.0 compliance, and Quetzal save files.

	___________________________________________________________

	2.0 What is Jzip?  
	
	2.1 Description  

	    Jzip is a program that emulates a virtual machine 
	    created by Infocom, called the Zmachine.  All Infocom
	    games (including the famous Zork and many others) are
	    designed to run on this virtual machine, and they are
	    in a format called "Z-code".  There are currently
	    eight different versions of Z-code, and Jzip currently
	    supports versions 1-5 and 8.

	    What does this mean?  It means Jzip can play any game 
	    written in one of these versions of Z-code.  All games
	    writtens by Infocom except for Zork Zero, Journey, 
	    Shogun, and Arthur (which are version 6 Z-code) can be
	    played with Jzip, as can all games created with Graham
	    Nelson's excellent adventure game compiler, Inform.
	    For more on Inform, see section 6.3.
	
	2.2 How do I play Infocom/Inform Games?

	    All Infocom gamefiles end in .dat. These games are in 
	    "Z-code" versions 1-5.  All Inform games end in either .z3, 
	    .z5, or .z8 (so far).  These extensions mean that a file 
	    is a "Z-code" adventure game in version 3, version 5, or 
	    version 8.  These files are not compressed, but are ordinary 
	    binary files, and should be downloaded by FTP in 'binary' 
	    mode. 

	    Jzip can also be combined with a gamefile to make a 
	    standalone DOS executable (that with still be playable by
	    Jzip on OTHER platforms!).  If you want to learn how to
	    do this, see section 4.1.

	2.3 What platforms does Jzip run on?

	    Jzip is known to run on DOS, Windows NT/95, OS/2, UNIX
	    (including DEC/OSF, FreeBSD, HP/UX, IBM/AIX, Linux, 
	    NeXT/Mach, SGI/IRIX, Solaris, and SunOS), BeOS and 
	    Atari ST machines.  If you want to compile Jzip
	    for a new port or just because, see section 5.0.
		
	___________________________________________________________

	3.0 Features, and how to use them

	3.1 Command line options

	    Command line option are options that are entered on the
	    command line after typing the name of the file to run.
	    If you wanted to run Jzip with a 4K command history
	    buffer and play the game Zork 1, you would enter it like
	    this:

	    > jzip -k 4096 zork1.dat

	    The command line options for Jzip may be entered in any
	    order, but they must all come before the name of the game
	    file you wish to run.

	3.1.1 Setting the screen size

	    There are four command-line options that help set the 
	    screen size _if_your_machine_doesn't_do_it_automatically_.
	    
	    -l n   tells Jzip there are n lines on your screen.
	    -c n   tells Jzip there are n columns on your screen.
	    -r n   tells Jzip how big of a right margin to use.  The
		   default is none, but if words get chopped off on the
		   edges of the screen instead of wrap, set this to a
		   higher number, like 5.
	    -t n   tells Jzip to leave n lines as a top margin.

	3.1.2 Setting the size of the command history

	    -k n   tells Jzip to use n bytes to keep track of the the
		   commands you have previously typed.  The minimum
		   is 1024 bytes(1K), and the maximum is 16384 bytes
		   (16K).  For information on how to use the command
		   history, see section 3.2.

	3.1.3 Getting version information

	    -v     tells Jzip to print a short blurb about the current
		   version.

	3.1.4 Using STRICTZ and why you would want to

	    -s n   The valid values for n are:
		   0:  no strict checking
		   1:  report only the first occurance of an error
		   2:  report all occurances of an error
		   3:  exit after any error

		   STRICTZ is a method of reporting errors found in
		   Zcode at execution time.  This mechanism can be very
		   useful to Inform developers to let them know when they
		   have bugs in their code.

	3.1.5 DOS only features
	    
	    Monochrome mode
	    -m     tells Jzip to run in black and white mode.

	3.2 Using the command history buffer & what it is.

	    The command history buffer of Jzip is a small portion of
	    memory used to store your previous commands.  You can
	    easily access your previous commands and edit them, and
	    submit them as new commands.  This is a handy feature,
	    especially to correct simple spelling mistakes.

	3.2.1 Under DOS

	    At the moment, DOS has the most comprehensive set of 
	    editing keys.  Here is a list of them and their function:
  
	    left arrow       - move one character to the left
	    right arrow      - move one character to the right
	    ctrl+left arrow  - move one word to the left
	    ctrl+right arrow - move one word to the right
	    home             - move to beginning of line
	    end              - move to end of line
	    backspace        - delete character to the left of the cursor
	    delete           - delete character below cursor
	    cursor up        - get previous command
	    cursor down      - get next command
	    page up          - get "oldest" command
	    page down        - display blank prompt (clears current line)
	    esc              - display blank prompt (clears current line)

	3.2.2 Under UNIX/Atari ST
	    
	    These are the editing key under UNIX and Atari ST and their
	    functions:
	    
	    left arrow       - move one character to the left
	    right arrow      - move one character to the right
	    backspace        - delete character to the left of the cursor
	    cursor up        - get previous command
	    cursor down      - get next command

	3.3 Using the INFOCOM_PATH environment variable

	    Jzip has one environment variable associated with it called
	    INFOCOM_PATH.  If Jzip cannot find the gamefile that you
	    specified on the command line, it will sequentially search
	    every directory in this path for the gamefile to play.

	3.3.1 Under DOS
	    
	    To use this variable under DOS, add a line that looks 
	    similar to the following one to your AUTOEXEC.BAT file.
	    Of course, you will need to adjust it to point to the
	    directories where your game files are!

	    SET INFOCOM_PATH=D:\IF\LTOI1;D:\IF\LTOI2;D:\IF\INFORM;

	3.3.2 Under UNIX
	   
	    Under UNIX, you need to set up your default shell 
	    initialization file to search in the right places.
	    For csh and tcsh, you would edit your .cshrc / .tcshrc
	    file to include the following:

	    setenv INFOCOM_PATH /usr/games/zcode:/usr/users/jholder/zcode

	    No matter which shell you use (which may mean you need
	    to use set INFOCOM_PATH=/usr/games/zcode), you need to 
	    seperate multiple directories with a colon(:).

	3.3.3 Under Atari ST

	    I'm not sure, but I assume you would use the same process as
	    you use for UNIX under MiNT.
	
	3.4 Portable Save Game files

	3.4.1 Quetzal

	    Jzip now supports the Quetzel portable save file format. 
	    This means that save files made with Jzip can be used
	    by any other Zmachine interpreter that supports this
	    standard.  

	3.4.2 Old Jzip Portable Save files

	    If you have old Jzip save game files, you
	    will need to comment out the "USE_QUETZAL" line in
	    ztypes.h and recompile Jzip to reenable Jzip to read 
	    those files.

	___________________________________________________________          

	4.0 Utilities for Jzip

	4.1 JZexe - making stand-alone Infocom-format games for MS-DOS

	    JZexe by Magnus Olsson (mol@df.lth.se) - see JZexe.txt

	4.2 ckifzs - This executable checks the validity of Quetzal
	    save files, and is included with the permission of Martin
	    Frost.

	___________________________________________________________

	5.0 Building Jzip

	5.1 UNIX / BeOS

	    Copy the file unix.mak to the name Makefile.  Look at the 
	    makefile and set the flags as indicated for the type of 
	    system you have. At the moment, JZIP is known to compile 
	    on SunOS, Solaris, HPUX, AIX, NeXT MACH, DEC OSF, Irix, 
	    BeOS and Linux.
	
	    Now type `make`.  If the compile doesn't happen right, edit 
	    the Makefile and change the "-DPOSIX" to either "-DSYSTEM_FIVE" 
	    or "-DBSD".  Ask your system administrator if you are not sure
	    which flavour of UNIX you are running.  If you still are 
	    getting errors, try changing "-ltermcap" to "-lcurses" on 
	    the LIBS line of the Makefile.  If it still doesn't work, 
	    get help from a friend or email me.

	    If your terminal can understand ANSI escape sequences, 
	    (a la the Linux console), you may wish to add "-DHARD_COLORS" 
	    to the CFLAGS line.
	
	5.2 DOS (& windows, I suppose...)
	
	    Borland C:
		copy bcc.mak makefile
		make
	    
	    Turbo C: 
		Start the development environment, and close all 
		files and projects.  Open the "jzip.prj" project 
		and compile. (Made with TC 3.0) (you may need to 
		change the default directories to coincide with 
		your Turbo C installation)
	
	5.3 Atari ST

	    The Makefile is atari.mak, and is targetted at GNU C.
	    Likely you will get odd results by trying to compile the
	    code with Borland TurboC or PureC.

	5.4 Bugs

	    Please report bugs and portability bugs to the author.

	___________________________________________________________

	6.0 Known Bugs

	    - At the moment, I believe everything works as 
	      advertised.  Please mail me when (not if) you find
	      bugs.

	___________________________________________________________
		
	7.0 Credits

	    For this release, I offer my most profound thanks to
	    Zarf (Andrew Plotkin) for the ZSTRICT code and Martin
	    Frost for the Quetzal code.

	    My sincere thanks also go to John Menicelli, Dancer, 
	    Magnus Olsson, Andrew S. Benham, Mark Phillips,
	    and Michael Phillips for help and bug fixes for past
	    releases, and as always, to all the readers of 
	    rec.arts.int-fiction and the users of Jzip who have sent
	    in bug reports and questions.

	___________________________________________________________

	8.0 License Agreement / Disclaimer

	  See License.txt, or run jzip -z
