if2pdb.pl README  4/5/2002


What does it do?

if2pdb.pl is a general IF file converter that creates PalmOS databases (PDB 
files) for Frobnitz, Pilot-Frotz, and PalmHugo.  It is slightly better (IMHO) 
than the previously supplied tools because it can convert a batch of game 
files in sequence without the user having to rerun the tool.


How do I run it?

It runs from a command prompt.  If you're running on Linux (or Unix), then 
you're probably quite familiar with the command prompt.  If you're running on 
Windows, you may not be used to running tools at a command line.  But then 
again if you're into IF you at least have some idea of what a command line is!

To get to a command prompt on Windows, you should click "Start -> Run" and 
then enter "cmd" for Windows NT or Windows 2000 or "command" for Windows 95, 
98, or ME.

I don't have easy access to a Macintosh computer, so I'll just have to hope 
that you Mac users out there can figure out how to run a perl script.

Your machine will also have to have Perl installed on it.  You can download 
Perl from various sites on the internet; do a 'net search for "perl install" 
and find an appropriate site for your computer system.

Once you have perl installed, fire up a command prompt and navigate to the 
directory where you have a bunch of IF story files ready to be converted 
(.z5, .z8, .hex, etc.).  Type the following command:

perl if2pdb.pl

This will cause the script to look in the current directory and start 
converting all the story files it finds.  It will prompt you for story names 
and suggest a default name for each one which can be chosen by simply hitting 
RETURN.

The tool also respects a few options:

-frobnitz      This causes the tool to create Frobnitz compatible PDB files 
               when it converts a Z-machine story file.  This is the 
               default, and never really needs to be entered -- it is really 
               only here for the sake of completeness.

-frotz         This causes the tool to create Pilot-Frotz compatible PDB 
               files when it converts a Z-machine story file.

-nointer       This causes the tool to automatically convert the file 
               without prompting the user for story names.  This is useful 
               if you need to convert a large number of games at once, and 
               you think the suggested names that the tool comes up with for 
               the games are good enough.  

-version       Prints the version of the tool and exits.

-help          Prints out a help screen.

Also, if you put filenames on the command line, the tool will only convert 
the files named.

When the tool grabs filenames from the current directory, it will grab files 
named <story>.z#, <story>.dat, and <story>.hex, where # is a number.  The 
.dat files are recognized because many Infocom games were distributed with 
that file suffix.

Infocom also put out .zip files for their Z-machine version 6 games (Journey, 
Arthur, and Shogun).  Currently there is no PalmOS Z-machine interpreter that 
can handle version 6 games, but if a future version of Pilot-Frotz or 
Frobnitz can handle them, the tool will oblige.  You'll just have to rename 
the .zip file to a .z6 file before conversion.  I decided that recognizing 
the .zip extension would be too confusing since .zip files have a different 
meaning in today's computer world.


Why make this tool?

A little history:

I play IF almost exclusively on my PalmOS handheld using Frobnitz.  I have 
found that I tend to hunt around the IF archive and various IF sites for 
lists of cool sounding games to try.  I then download them all and have to 
convert them all one by one to PalmOS databases.  I quickly wrote a wrapper 
script that would call the z2pdb.exe program repeatedly so that I wouldn't 
have to type the command over and over again.  I named that tool iz2pdb.pl 
(the "I" being for "interactive").

Shortly thereafter, I found the z2pdb.pl tool and decided that I could just 
incorporate its functionality into my wrapper tool.  I then had a tool that 
would convert a bunch of Z-machine files for my Palm at once.

In January of 2002, Kent Tessman released his Hugo interpreter for PalmOS 
machines, and he included a hugo2pdb.pl tool.  It didn't take too much effort 
to get his modifications pulled into my perl script.  At that point the tool 
no longer was a Z-machine converter, but an IF files converter!  That seemed 
pretty cool and perhaps valuable to the IF community, so I've uploaded it.


Who wrote this tool?

My name is Rick Reynolds.  You can contact me with any questions at 
rick@rickandviv.net.  The real guts of this tool is not original with me, but 
is based on the earlier z2pdb and hugo2pdb tools.


Will an executable version of the tool be provided?

I have no desire to code this up in a compilable language at this time.  If 
someone wants to wrestle with a Perl-to-C converter and create an executable 
for the tool, they are welcome to do so.  Also, the tool is fairly generously 
commented and I hope easy to follow.  So it should be pretty easy to 
re-implement it in a compilable language.  By all means contact me if you'd 
like to do so.
