-----BEGIN PGP SIGNED MESSAGE-----

MIPINDEX, a miptexture indexer for DOS
version 1.1a

  The beaten path
  will lead you to your doom.
  That is its revenge
  for being beaten.

    -- Zen proverb

README.TXT

[0] Table of contents

  1. System requirements
  2. Installation
  3. What mipindex can do, and how to make it do it
     a. Getting the command syntaxes
     b. "Dir" for miptextures
     c. Building WAD2 files
     d. Converting BSP <-> DST
     e. Miscellaneous quirks
     f. Examples
  4. History and Bugs; Updates and Bugfixes
  5. License & legalese
  6. Acknowledgments
  7. About the author

  I might have written things in this file which you already know. I do not
  intend to insult your intelligence, but I cannot read your mind. Please
  forgive me if I bore you -- and don't read the boring parts more than once!

[1] System requirements

  This program was compiled with DJGPP 2.0 and ought to run on any DOS system
  which can run Quake. You may need CWSDPMI.EXE if it says "Load Error: No
  DPMI." You can probably use the CWSDPMI that came with Quake, or you can
  download a new version from the same places that offer DJGPP. To find some
  places that have it, go to the DJGPP homepage at

    http://www.delorie.com/djgpp/

  Under Windows 95, Mipindex does not need CWSDPMI.

[2] Installation

  Put the EXE in whatever directory you prefer. Put CWSDPMI.EXE with it if you
  need to. Then you're done.

  If you have PGP, you can get my public key from my homepage (the URL is at
  the bottom of this file) and check the signature MIPINDEX.SIG. This is the
  signature of the EXE. This README file is also signed. Just so you know it's
  the real thing.

  If you want PGP, the public key on my homepage has links to the U.S. and
  International distribution sites. Make sure you choose the right one.

  If you put Mipindex on your path, or in the directory from which it is used,
  you won't have to type as much when you invoke it.

[3] What Mipindex can do, and how to make it do it

  Mipindex can:

  * give you brief help about itself.
  * act like a "dir" command for miptextures.
  * build WAD2 files for use with editors or QBSP or both.
  * convert BSP <-> DST files.

  Now I'll describe these things.

  [a] Getting the command syntaxes

    Just type Mipindex by itself to get help and see all the syntaxes for
    the various options. If Mipindex ever doesn't understand your options,
    it'll tell you its syntax again.

  [b] "Dir" for miptextures

    Mipindex can act like a "dir" command for miptextures. It only lists each
    miptexture the FIRST time it appears. It can process BSP (version 29
    only, which corresponds to Quake 1.00 - 1.06, I think), WAD2, IDX (a
    Mipindex-specific format you'll read about shortly), and PAK files.
    Mipindex also understands a certain 768-byte file called "palette.lmp".
    "palette.lmp" is the only file Mipindex treats as having a single
    miptexture in it.

    Mipindex will complain if it doesn't understand a file type, and then it
    will move on to the next file without pausing.

    The output can be piped or redirected, just like any other DOS command.

    Mipindex doesn't care whether you use backward or forward slashes.
    Parameters are processed in the order given; wildcards are expanded in
    alphabetical order.

    You can't do a "-list" on a DST with this version of Mipindex.

  [c] Building wad2 files

    Mipindex can also build WAD2 files for use with map editors or QBSP or
    both. No two miptextures are "identical" in the WAD2 that results. This
    keeps it small.

    Mipindex considers miptextures identical if their names and sizes are
    identical. If the names of two textures are the same but the sizes are
    different, like "metal5_8" in registered Quake, Mipindex calls them
    different and includes them both. QBSP only looks at names, though -- that
    fact should convince you, if you create your own textures, to give them
    unique names. "metal5_8" is an oddity.

    Mipindex does not allow empty space to exist in its output WAD2. You can
    build a WAD2 from another WAD2 to get rid of free space created by other
    utilities. This rebuilds the entire WAD2. (It also gets rid of everything
    but miptextures and the first palette. You've been warned.)

    It does not matter whether you have unpacked your PAK files or not --
    except, if you have, you have to specify more files to build a WAD2 from.

    It is possible that Quake contains miptextures with identical names and
    sizes but different image data. Mipindex will think they are the same. A
    future version may keep CRC's of miptextures to respect the distinctions.

    A palette is considered to be a special kind of miptexture. It is indexed
    and written to WAD2's just like a miptexture, except its name is always
    "palette" and its size is always 256 x 3, which is illegal for an actual
    miptexture. (Quake never finds out Mipindex is thinking this way.) Because
    all palettes have the same name and size, Mipindex thinks they are all
    alike and only allows one palette in an index or a WAD2. Right now,
    though, Quake only has one palette anyway, and this behavior shouldn't
    cause any problems.

  [d] Converting BSP <-> DST

    The DST is a new file format introduced with this program. DST means
    "distributable BSP." Depending on how many miptextures a BSP file uses,
    a DST can be 25% to 33% smaller.

    When Mipindex converts a BSP to a DST, it uses a miptexture index. All the
    data in the DST is copied from the BSP, EXCEPT for the miptextures in the
    index (i.e. with "identical" copies in the index) -- only their names are
    copied. If the index covers all of id Software's textures, the DST will
    not contain any of them.

    For the reverse conversion, Mipindex uses the index to recover the
    original textures that were removed. In a future version, maybe commonly
    requested textures will be cached, but for now this seeks all over your
    hard drive. The reverse conversion will NOT result in a byte-for-byte
    identical BSP. Empty space between the miptextures will be removed, and
    if there were multiple references to the same miptexture in the original
    BSP (a possibility which QBSP should eliminate anyway), each reference
    will have its own copy in the resulting BSP. Also, the "lumps" in the BSP
    will be put in "order." However, the files play just the same in Quake.
    I've tested it many times with many BSPs.

    A DST may have interesting legal properties. The creator of a BSP
    typically cannot distribute the BSP for profit, because it typically
    contains id Software's textures, and is therefore a sort of collaborative
    work with id. id Software doesn't like people making money off of the
    redistribution of their textures. However, with Mipindex, you can make a
    DST which does NOT contain id Software's textures. In theory, this DST is
    the sole and entire property of the map creator, and can then be sold if
    the map creator wishes.

    Sometimes (only in specific instances), Mipindex can leave some of id
    Software's miptextures inside the DST. This can happen if an id miptexture
    is not in your index, or if you've created a "derivative work" miptexture
    and given it a new name.

    Also, if a BSP contains a new texture with an old name and size, Mipindex
    will remove it without noticing that the image data is different, and
    the BSP that other people get will contain the wrong image data.

    It is your responsibility to check for these situations and avoid them.

    It is still illegal to sell BSPs or DSTs of a level without the level
    creator's permission. If YOU are the level creator, this is not a problem.
    Otherwise you'd better ask.

    Also, you may have to sign the COMEXP license to use the Quake trademark
    for your own commercial gain. (Or you can just say you're selling Mipindex
    DSTs and hope your customers draw the intended conclusion.)

    An IDX (index) file format is supported, so that Mipindex can index
    several files and use textures from ALL of them for BSP <-> DST
    conversion. This IDX file contains the full paths of its sources, and
    byte-offsets directly into the files, so if you move or alter the files
    you've indexed, you'll have to reindex them.

    A future version of Mipindex may allow WAD2 <-> DST conversion. (Or a
    different extension may be used.)

    You can use wildcards with the conversion commands. Mipindex will not
    overwrite existing files.

    At the end of conversion, Mipindex prints a summary of its successes and
    failures. Failure does not mean that no output file was created. Sometimes
    a bad output file is created. If Mipindex reports an error, delete the
    corresponding output file -- it's probably bad.

  [e] Miscellaneous quirks

    When running under Windows 95, Mipindex supports long filenames. This can
    be particularly insidious at times, such as when you accidentally enter

      mipindex -wad2 my.wad2 d:*.pak

    and it creates my.wad2. You can rename it, but... look out for this.

    If you have any comments, requests, or bug reports, send them to me at

      edkiser@jaxnet.com

    and I'll read them. And, if time permits, I'll do something about them.

  [f] Examples

    To get a directory of miptextures, use "mipindex -list *.pak" or
    "mipindex -list *.bsp". The list is quite long so you'll want to pipe it
    through a pager like "more" or Vernon D. Buerg's "list" (not included).

    To build a WAD2, use something like "mipindex -wad2 output.wad *.pak".

    To convert BSPs and DSTs, first you have to make an index. The command
    is similar to building a WAD2: "mipindex -idx my.idx *.pak" or
    "mipindex -idx my.idx maps/*.bsp". Then, you USE the index for the
    conversion: "mipindex -bsp my.idx ..\addons\maps\schneier.dst" or
    "mipindex -dst my.idx ..\mylevels\maps\*.bsp". The latter will convert all
    your BSPs to DSTs.

    Mipindex never deletes, modifies, or replaces files. It only creates new
    files. The best way to learn to use it is to play with it and read the
    manual -- though not necessarily in that order.

[4] History and Bugs; Updates and Bugfixes

  Version 1.0 of this program was only a WAD2 builder. It had a "theoretical"
  bug where miptextures were not deliberately aligned at multiples of 16.
  (They were accidentally aligned at multiples of 16. The bug is theoretical
  because I never saw it actually do any damage.) It also compared only names
  of miptextures.

  Version 1.1 compared names and sizes and introduced BSP <-> DST conversion.
  But it had the same theoretical bug, and a second bug in BSP <-> DST
  conversion, where certain files would seem to have invalid textures and
  crash Quake as re-expanded BSPs.

  This version, 1.1a, fixes both of those bugs. I've tested BSP <-> DST
  conversion on several Quake levels downloaded from the Internet, and it
  works every time. So far.

  Now and then I release new versions of this program. To see if you have
  the latest version, check the USENET group rec.games.computer.quake.editing
  to see if I've posted anything, or check ftp.cdrom.com to see if they carry
  a later version than the one you have. You can also send me an e-mail and
  I'll tell you what the latest version is, and at least one place where you
  can downloaded it.

[5] License & Legalese

  Everything in this distribution is Copyright (c) 1996 by Edward Kiser. All
  rights are reserved, EXCEPT that anyone can make copies of this program for
  their own use, and anyone can give a copy of the original, unmodified
  archive to anyone else. However, no people or companies can charge for this
  unless they let their customers know beforehand that it's also available
  free on the Internet. Also, no one can USE this program without agreeing to
  the TERMS of USE below. If you're a lawyer and not a computer scientist,
  to "use" this stuff means "to load the software into RAM and execute it."

  This program does not contain any encryption algorithms and so does not fall
  under any export restrictions. :-)

  The TERMS of USE. You can't use this software unless you agree that:

  a) You will respect my Copyright. That means you will not distribute
     modified versions; only originals and separate modifications.

  b) You will respect the Copyrights of the creators of Quake levels by not
     distributing DST files for levels unless such distribution is all right
     with the creators of those levels.

  c) You will indemnify and hold harmless me, the author, as well as any and
     all persons or companies which may have, knowingly or unknowingly,
     contributed to this program, for any damages which may occur as a direct
     or indirect result of the use of this program. Period! I offer no
     warranty of any kind, not even of fitness for a particular purpose or
     activity.

     I do not do this because I think damages are likely, but because I'm
     giving this away for free, so I'm not making enough money to afford any
     liability.

  d) You have read these TERMS of USE.

  If you knowingly violate the TERMS of USE, your right to use Mipindex will
  be retroactively void! (To the extent allowed by law.)

  You can always free yourself from the TERMS of USE by not using Mipindex.

  Quake is a trademark of id Software, and this program was written to work
  with Quake. However, id Software has nothing else whatever to do with this
  little project -- in fact, they may not even know it exists -- so they and I
  will appreciate it if you don't call them up with technical support
  questions about this program. Thanks.

  This program uses the Standard Template Library (STL), which is Copyright
  (c) 1994 by Hewlett-Packard Company. It bears the following notice with
  regard to STL:

    Copyright (c) 1994
    Hewlett-Packard Company

    Permission to use, copy, modify, distribute and sell this software
    and its documentation for any purpose is hereby granted without fee,
    provided that the above copyright notice appear in all copies and
    that both that copyright notice and this permission notice appear
    in supporting documentation.  Hewlett-Packard Company makes no
    representations about the suitability of this software for any
    purpose.  It is provided "as is" without express or implied warranty.

  Hewlett-Packard can't offer technical support for Mipindex, either.

  I'm holding to the position that the Mipindex executable is not a "copy" of
  STL. That's why it doesn't bear the copyright notice for STL.

[6] Acknowledgments

  I'd like to thank:

    Microsoft Word for teaching me how to spell "acknowledgments," :-)

    id Software for Quake,

    Olivier Montanuy for the unofficial Quake specs,

    Alexander Stepanov and Meng Lee (and Hewlett-Packard) for the
    Standard Template Library,

    Cay S. Horstmann and Steve Teale for some great books about C++,

    DJ Delorie for DJGPP and Charles W. Sandmann for CWSDPMI,

    readers of the newsgroup comp.os.msdos.djgpp for their patience, and

    Richard Felker, Michael Stokes, and Brian Curnow for making me SO mad
    with their half-baked utilities that I decided to sit down and write my
    own. :-)

  Thanks to Remy Horton who told me why some editors were choking on
  Mipindex's WAD2 files. (One of those editors, I discovered, was Quest.)

  I'd also like to thank YOU for giving this a try. Thanks. If nobody ever
  tried this program, it would be pointless to have written it.

[7] About the Author

  My name is Edward Kiser. "Kiser" rhymes with "Wiser".

  You can e-mail me at edkiser@jaxnet.com. You can also visit my boring
  homepage at

    http://faraday.ee.unf.edu/~EdwardKiser/

  This homepage is updated infrequently, and that's why it's so boring. Also
  it's hard to reach sometimes.

  I do all sorts of stuff besides program and play Quake, but I've never quite
  been able to confine myself to any one thing. I have a lot of hobbies, of
  which Quake and Programming are but two.

  As to my career, I'm a student majoring in Electrical Engineering... NOT
  computer science! And why shouldn't this be? Electric-stuff is a superset
  of computers.

  When I join Quake Internet games, I am "Nobody". I got this from Homer's
  Odyssey. When Quake says "Nobody ate two loads of So-and-so's buckshot,"
  it's almost worth having died for.

  Almost.

-----BEGIN PGP SIGNATURE-----
Version: 2.6.2

iQDdAwUBMmR9PCliyVzMe6vxAQHK2gY/Yg+OlB1ZKDcRI0+HWFzzr+MH3l7/ATKS
DXNbdDwW5Vmihp6t6S3+H4A+3/wGwJ//fS6fIgk/O/Mos+6hs6fUIOaAgMYT0Euy
pfH9VFUjDA5U1jtGFbfgF38i/Z9Q6xG2ee0xKRw36h0BaA0e3sMcDyiKCzlSCMch
f5/hpjZNxaNJ9ubU81cZf1Y7imOYMeUkqQuSiPT1H/cO23x28yFph8XwohnFN6fV
PH3WkuOCOo5P3NS7MypPF7qwfhNZ3EKl5CNfXvhFXA0=
=+e7w
-----END PGP SIGNATURE-----
