
			
			This is the readme file for
			   the first release of

			WADCOMP.EXE and EXTRACT.EXE
			  (also includes LIST.EXE)

				07-25-1995

			 Written by Serge Smirnov
			   (sxs111@po.cwru.edu)



Don't let the size of this document discourage you from looking at it.  It's
provided mainly as a reference.  A quick look at the sample .bat files may
well explain it all for you.  However, do read the first two sections before
you try anything.



Table of Contents
-----------------

   Disclaimer             -- I am not responsible for anything...
   Statement of purpose   -- who and what the programs are for
   List of files included
   Program descriptions   -- explains how they work in great detail
   General usage notes    -- applicable to all three programs
   Known problems
   Bug reports/comments   -- how to contact the author
   Credits
   Copyrights/permissions



DISCLAIMER
==========

	The programs included in this .zip file are freeware.  Use them
however you like, but I am not to be held responsible for any damage they
do.  YOU DO NOT HAVE MY PERMISSION TO USE THESE PROGRAMS FOR ANY PURPOSE FOR
WHICH THE LAW WOULD SUPERSEDE THIS DISCLAIMER.  BY USING ANY OF THE PROGRAMS
YOU ARE INDICATING THAT YOU ACCEPT THESE TERMS.

ID SOFTWARE IS IN NO WAY AFFILIATED WITH THIS PROJECT, AND THEY CANNOT BE
EXPECTED TO PROVIDE ANY TECHNICAL SUPPORT FOR IT.



STATEMENT OF PURPOSE
====================

	EXTRACT.EXE and WADCOMP.EXE are two utilities for compiling WAD files.
Together, these two programs should let you build a "custom" WAD file.
WADCOMP.EXE is the actual "compiler", and EXTRACT.EXE is a powerful tool for
extracting stuff from WAD files.  You will find them especially useful if
you want to manipulates WADs in a way other programs won't let you.  Since
these utilities work with directory entries (lumps), you can use them with
any valid WAD file, be it a Doom2 WAD or a Heretic WAD.

	Although these programs can be used to simply extract a map from a WAD
file or group sevaral WAD files, you pretty much need to know a little about
the structure of WAD files to appreciate all of the features.  For that
purpose, I recommend downloading and reading the first few pages of
The Unofficial DOOM Specs by Matt Fell, available as

ftp://ftp.cdrom.com/pub/idgames/docs/editing/dmspecs16.zip.

	Also included in this distribution is LIST.EXE, which lets you view
the directory of a WAD file.  There are many programs out there that do that,
and I am including mine only for your convenience, just in case you don't
already have one.  Also, LIST.EXE will let you check if a WAD file contains
a certain entry in batch mode.

	Two sample batch file are included to demonstrate the features of
EXTRACT.EXE and WADCOMP.EXE.  REBUILD.BAT rebuilds your v1.666-1.9 DOOM.WAD
and eliminates the redundant sound entries (miraculously enough, it even 
works with The Ultimate DOOM).  SPRITES.BAT shows how you can emulate other 
programs (e.g., nwt -as) using WADCOMP.EXE and EXTRACT.EXE.  To test 
SPRITES.WAD, I also created a small sprite replacement WAD called HUMANS.WAD.  
It swaps the sprites for sergeants and former humans.  To try it out, type 
something like:
		sprites \doom\doom.wad humans.wad \doom\tmp.wad
		cd \doom
		doom -file tmp.wad.



LIST OF FILES INCLUDED
======================

	CUSTMWAD.TXT (this file)
	EXTRACT.EXE
	WADCOMP.EXE
	LIST.EXE
	REBUILD.BAT     -- a demo batch file
	SPRITES.BAT     -- another demo batch file
	HUMANS.WAD      -- use it to try SPRITES.BAT
	SOURCE.ZIP
	


PROGRAM DESCRIPTIONS
====================

	If you invoke either WADCOMP.EXE or EXTRACT.EXE with no parameters,
it will give you the basic sytax and a brief explanation of every option.
This section explains the options in more detail.  Note that you probably
don't have to read all of it.


EXTRACT.EXE
-----------

First of all, "extract" here really means "copy", so the input WAD is never
modified in any way.  Also, although the examples in this section all use
doom.wad as the source file, there are absolutely no restrictions on the
input file, other than it must be a valid WAD file.

Usage: extract in.wad pattern [-{A|a}ENTRY] [-{B|b}ENTRY] [-wout.wad|path]
OR     extract in.wad ENTRY   [-{A|a}ENTRY] [-{B|b}ENTRY] [-wout.wad|fname.ext]

BASICS.  The simplest syntax for EXTRACT.EXE is

		EXTRACT.EXE filename.wad DIRENTRY

This command will try to open filename.wad and extract every entry whose name
matches DIRENTRY to a separate file.  All entries are extracted as raw and no
conversion is performed.

*****************************************************
*** Note that DIRENTRY is CASE SENSITIVE, it will ***
*** not work if you specify e1m1 instead of E1M1. ***
*****************************************************

The DIRENTRY field can contain wildcards (? and *), so you can extract multiple
entries at a time.  For example,

		EXTRACT.EXE doom.wad DS*

will extract every sound effect contained in doom.wad.
	The base file name of the file to which an entry is extracted is by
default the entry name.  The extension is determined as follows:
	if the entry is between S_START and S_END, the extension is ".SPR";
	if the entry is between P_START and P_END, the extension is ".PTC";
	if the entry if between F_START and F_END, the extension is ".FLT".
If none of the above is true, the entry name is examined:
	if the entry name matches "D_*", the extension is ".MUS";
	if the entry name matches "DS*", the extension is ".SND";
	if the entry name matches "DP*", the extension is ".PCS".
See The Unofficial DOOM Specs for an explanation of why I chose these 
extensions.
	All other entries are extracted to .RAW files, except for entries that
match "E?M?" or "MAP??".  These entries are special because they indicate that
the next few entries represent map data.  Accordingly, they receive special
treatment.  First, if such an entry is extracted, it is extracted to a WAD
file (E1M6 would be extracted to E1M6.WAD).  Second, all subsequent entries are
also extracted to that file, until the program hits an entry whose name does
not match any of the following: "THINGS", "VERTEXES", "LINEDEFS", "SIDEDEFS",
"SECTORS", "SSECTORS", "SEGS", "NODES", "REJECT", "BLOCKMAP".  These entries
are stored in the output WAD in the order they appear in the input WAD.  For
example,

		EXTRACT.EXE doom.wad E1M1

causes E1M1 and all the entries following it, up to but not including "E1M2",
to be extracted to E1M1.WAD.

EXTRACTING ENTRIES TO A WAD FILE.  Although by default all entries except maps
are extracted to raw files, it is possible to direct EXTRACT.EXE to extract
everything to a .WAD file.  For example,

		EXTRACT.EXE doom.wad DS* -wsounds.wad

will extract all DS* entries to sounds.wad.  The '-w' option affects the level
data as well.

		EXTRACT.EXE doom.wad E?M? -wlevels.wad

will extract all the level data from doom.wad to levels.wad.  In fact,

		EXTRACT.EXE doom.wad * -wnewmain.wad

would have the same effect as

		COPY doom.wad newmain.wad,

unless doom.wad contained holes, which would be removed.

SPECIFYING THE OUTPUT FILE NAME.  If you wish to extract entries to a directory
other than the current directory, or if you wish to extract an entry to a file
other than the default filename for that entry, use the following syntax:

		EXTRACT filename.WAD ENTRY outpath.

Whether outpath is a filename or a direcotry name is determined by whether
ENTRY contains wildcards.  If it does, EXTRACT.EXE interprets outpath as a
directory name (e. g., c:\tmp) and attempts to extract files to that directory.
Otherwise, it thinks that outpath is a file name and attempts to create a file
with that name.  Examples of proper use are:

		EXTRACT doom.wad DS* c:\tmp
		EXTRACT doom.wad TITLEPIC doomlogo.pic

NOTE: do not use this syntax in conjunction with the '-w' option.  They are
mutually exclusive.  Also, the following two commands will have the same
effect:

		EXTRACT doom.wad E1M1 -wlevel1.wad
		EXTRACT doom.wad E1M1 level1.wad

(that's because E1M1 is extracted to a WAD file by default).

EXTRACTING A RANGE OF ENTRIES.  Sometimes it's useful to extract all entries
that come before or after a specified entry.  An example of this would be
extracting sprites: the sprites are always between S_START and S_END.  The
way to do so it is to use one (or two) of the following options:
		-aENTRY -- process all entries after ENTRY;
		-AENTRY -- process ENTRY and everthing that follows; 
		-bENTRY -- process all entries upto (but not including) ENTRY;
		-BENTRY -- process all entries up to and including ENTRY.
In these options, ENTRY cannot contain wildcards.
By 'process' I mean 'look at it and extract it if it matches the pattern'.
That means you still have to specify a pattern (or an entry name).  Here are
some examples.
		EXTRACT doom.wad * -AS_START -BS_END -wsprites.wad
extracts all sprites to sprites.wad;

		EXTRACT doom.wad * -AS_START -wgraphics.wad
extracts all entries from S_START till the end of file to graphics.wad;

		EXTRACT doom.wad DS* -bS_START
extracts all DS* entries prior to S_START.  This is probably better than

		EXTRACT doom.wad DS*
because some sprites could match the pattern and be extracted as well, even
though they are not sound entries.
NOTE: As the first example shows, you can use '-A' and '-B' in one command.
You can also combine '-a' and '-B', or '-A' and '-b', etc.  The only
requirement is that '-a' (or '-A') must come first.  Also, you cannot use
both '-a' and '-A' (or '-b' and '-B').  It is your responsibility to make sure
that the entry specified in '-a' preceeds the one specified in '-b'.  If that
is not the case, the '-b' option will have no effect.
	Another use for this syntax is extracting map resources.  The command
		EXTRACT doom.wad THINGS
will extract ALL 27 THINGS resources, overwriting the file THINGS.RAW each time.
After it's done, you will always end up with THINGS from E3M9.  To get around
this, you can instruct EXTRACT.EXE to ignore all THINGS resources not contained
in a specified range.  Thus, to extract THINGS from E1M6, you would type
		EXTRACT doom.wad THINGS -aE1M6 -bE1M7


WADCOMP.EXE
-----------

Usage: wadcomp [-I]outfname.wad { file[@[ENTRY]] | @ENTRY } ...
OR     wadcomp [-I]outfname.wad -rrespfile

BASICS.  WADCOMP.EXE builds a new WAD file, inserting everything you tell
it to.  It will overwrite any existing file with the given name without
asking your permission.  By default, it builds a PWAD, but you can use the
'-I' option to make it an IWAD.
	The entries inserted into the destination WAD are specified on the
command line (or in the response file).  Each parameter specifes a PWAD,
an entry, or a set of entries.  You can specify as many parameters as you
can fit in one command line, and if that's not enough, you can put them in
a response file.  The parameters are processed in the order they appear on
the command line (or in the response file).
	Each parameter must be in one of the following formats:

(1) filename -- the simplest format.  If filename is not a WAD file, it is
		inserted as an entry whose name is the base file name.
		Otherwise, every entry from filename is copied to the
		destination WAD.
		Examples:

			WADCOMP mywad.wad c:\tmp\genmidi.raw

		will create mywad.wad with one entry int it: GENMIDI.

			WADCOMP mywad.wad *.raw

		will create a WAD with as many entries as there are files
		that match *.raw.

			WADCOMP mywad.wad tmp\*.wad

		will group all the WADs it finds in tmp.

(2) filename@ENTRY -- specifies the name of the entry that will contain the
		data from filename.  In this syntax, filename cannot contain
		wildcards, since that could cause multiple entries with the
		same name.  The file is treated as raw regardless of whether
		or not it's a WAD.
		Examples:

			WADCOMP mywad.wad e1m1.wad mywad.txt@INFO

		will copy all the entries from e1m1.wad to mywad.wad and add
		an entry called INFO with the contents of mywad.txt.

			WADCOMP mywad.wad e1m1.wad@E1M1

		will produce a WAD file with one entry, E1M1, which is
		actually a copy of the WAD file e1m1.wad.  I don't think
		anybody would wanna do it, but the option is there.  It
		would be useful if you wanted to insert a raw file that
		was unfortunate enough to start with "xWAD", where x is
		any character.

(3) filename@   (filename can contain wildcards) simply forces EXTRACT to
		treat all files that match filename as raw, even if some
		of them appear to be WAD files.
		Examples:

			WADCOMP mywad.wad file01.raw@

		is the same as

			WADCOMP mywad.wad file01.raw@FILE01

(4) @ENTRY      inserts an entry of length 0.
		Example:

			WADCOMP mywad.wad @S_START *.spr @S_END

		would build a WAD file whose first entry is S_START, whose
		last entry is S_END, and everything in between comes from
		the files matching *.spr.
			Since the program does not check for the length of
		the entry name, it is possible to use '@' as a parameter by
		itself.  The effect of this parameter would be to insert
		a 0-length entry with no name (technically the name would be
		"\0\0\0\0\0\0\0\0").  That would be pointless, so consider
		this option undocumented.

In the above explanations and examples, ENTRY should not be longer than 8
characters.  If it is, it will be truncated and you'll get a warning.  Also,
to give you more freedom, the entry name is never converted to all-caps.
I have yet to see a WAD that contains entries with lower case letters, and
I don't know how DOOM would react to them, so you should probably make all
you entries upper case anyway.
	I know this can be annoying, but I wanted to make as few assumptions
as possible.  At one point I assumed that all entry names would make valid
DOS filenames, only to find out that DOOM2.WAD has entries like VILE\5.  So
what if some day somebody writes a DOOM-type game that uses both AA1 and aa1 ?

USING A RESPONSE FILE.  Since WADCOMP.EXE is supposed to be a semi-universal
WAD compiler, it's a drag that DOS allows only 127 characters per command.
Hence, you can put all your parameters (except the output file name) in a
text file and tell WADCOMP to take its input parameters from that file.  I
think this feauture is pretty much self explanatory.  I jsut wan to point
out that I implemented it at the last minute, and my 'parser' is very
primitive.  Therefore, avoid blank lines and trailing/leading spaces in the
response file.

HOW WADCOMP DETERMINES IF AN INPUT FILE IS A WAD FILE.  Should this be of
interest to anybody, here's how it works.  It does not look at the extension.
Instead, it checks to see if the file is 12 bytes or longer, and if it is,
reads in the first 12 bytes.  Then it looks at bytes 2-4 of the file, and
checks if they are 'W', 'A', and 'D', respectively.  If so, the program
decides it's a WAD file.  Otherwise (file shorter than 12 bytes, or does not
start with "?WAD"), the file is assumed to be raw.

NOTES ON USING WILDCARDS WITH WADCOMP.EXE.  If a parameter contains wildcards,
wadcomp attempts to insert every file that matches the path into the
destination WAD.  The order in which the files are inserted is the order in
which DOS finds them.  I think this is the order files are diaplayed in if
you type DIR with no ordering options.  Sometimes the order is irrelevant,
but I remember at least one occasion where it seemed to make a difference.
I compiled a WAD that replaced all of the D_E?M? entries and D_INTER.
Somehow the order got messed up and DOOM crashed.  Therefore, you should use
wildcards with caution.
	If you find that the files you're trying to insert into a WAD are not
in the right order, I recommend copying them one by one to another directory,
in the order you want them stored.  I don't know if this always works, but it
worked for me.  Also, I've noticed that overwriting a file does not change its
place in the directory list.  For more information on how DOS orders files
and how the FindFirst/FindNext system calls work, consult your local DOS guru.



GENERAL USAGE NOTES
===================

	The stuff in this section is applicable to all three programs.  First
of all, if a program bombs to DOS with a message that starts with the words
"system error:", it's not your system that's reporting the problem, it's
actually the program complaining about not being able to allocate memory,
write/read/close files, etc.  If you see a message like that, it means one
of the following:

      * The program ran out of memory.  This really shouldn't happen unless
	you try to compile a WAD with 4096 entries or more, but if it does, 
	let me know.
      * The program could not read from a file.  It probably means the file
	is either corrupt, or not what the program thinks it is.  It is
	possible to confuse any of my programs by giving it a "WAD" file that 
	has the right header, but contains a pointer to a place past the end 
	of file.
      * The program could not write to a file.  A write protected floppy
	or a full hard disk could cause it.
      * Last but certainly not least, there is always a possibility that
	you've found a BUG !  If you believe that's the case, E-mail me
	and I'll attempt to figure out what the problem is.

	Another thing that could happen is that one of the programs exists to
DOS with a "*** PROGRAM ERROR ***".  That definitely indicates a bug, and
I'll fix it as soon as I can.

	Since these utilities are meant to be suitable for use in batch files,
any abnormal termination or warning is accompanied by a non-zero exit code:
      1 is returned if there were any warnings (symptomatic of incorrect
	usage or missing input files);  LIST.EXE also returns this value
	if the specified input file does not contain the epecified entry.
      2 is returned if a "system error" (explained above) occurs;
      3 is returned on a "*** PROGRAM ERROR ***".
Any other non-zero value indicates a bug.



KNOWN PROBLEMS
==============

	The following is a list of bugs I knowingly left in the programs at
the time of the first release.  I did not bother to fix them because they
all seemed to be pretty harmless.  Let me know if I was wrong.

      * Both WADCOMP.EXE nor EXTRACT.EXE will crash if the output WAD has
	4096 or more entries (the exact threshold number might be slightly
	lower).  The only easy way to fix this is to recompile the programs
	using a DOS extender (e.g., DJGPP).

      * When compiling a new WAD, if the destination file name matches one
	of the source parameters, WADCOMP.EXE will insert the destination
	file into itself.  Under DOS, it usually becomes a 0-length entry
	and doesn't hurt anything.

      * The extensions EXTRACT.EXE gives to entries like S_START and S_END
	are different.  A _START entry gets the extension appropriate for
	the entries that follow it, while the corresponding _END entry will
	have ".raw" as its extension.

      * SPRITES.BAT will not work if the source WAD file does not contain
	an S_START lump.  If you come across such a file, do the following:

		wadcomp sprites.wad @S_START whatever.wad
		sprites <main> sprites.wad <dest>



BUG REPORTS / COMENTS
=====================

	If you believe you have found a bug in one of the programs, please
e-mail me at

sxs111@po.cwru.edu.

I cannot guarantee that I will fix everything pointed out to me, but I will
try to respond quickly.  I may also supply additional information about the
source code if you request it.  Feel free to send me any comments you have.
I'll be happy to know that somebody has actually looked at my programs.  If
you must use regular mail, my address is

2365 Murray Hill Rd 620D  Cleveland  OH  44106.



CREDITS
=======

This project was made possible by the following people's efforts:

	id sofware  -- created DOOM
	Matt Fell   -- wrote The Unofficial DOOM Specs

Thanks to Michael Zoran for beta testing the software for me.



COPYRIGHTS/PERMISSIONS
======================

	These programs are intellectual property of the author.
You are free to do whatever you like with the executables, as long
as you don't charge anybody for it.  If you use a significant portion
of the source code in another program, please be kind and mention me
somewhere in the documentation.  E-mail me at sxs111@po.cwru.edu with
any questions (I may give you my premission to include the executables
in a package that is not free, but only if you ask for it).

DOOM, MS-DOS, and Borland C are registered trademarks of their well
known creators.

PLEASE DO NOT USE THIS SOFTWARE TO MAKE WADS THAT WORK WITH SHAREWARE DOOM

