Merge from raven-branch.

Subversion-branch: /branches/strife-branch
Subversion-revision: 2367

3 files changed, 474 insertions, 1 deletions

diff --git a/man/INSTALL.template b/man/INSTALL.template
new file mode 100644
index 00000000..19d3c88d
--- /dev/null
+++ b/man/INSTALL.template
@@ -0,0 +1,253 @@
+
+Chocolate Doom installation
+===========================
+
+These are instructions for how to install and set up Chocolate Doom
+for play.
+
+#ifn PRECOMPILED
+Building Chocolate Doom
+-----------------------
+
+Before you can play Chocolate Doom, you need to compile a binary that
+you can run.  For compilation, Chocolate Doom requires the following
+to be installed:
+
+ * A C compiler (gcc is recommended)
+ * make (GNU make is recommended)
+ * LibSDL (see http://www.libsdl.org/)
+ * SDL_mixer (see http://www.libsdl.org/projects/SDL_mixer/)
+ * SDL_net (see http://www.libsdl.org/projects/SDL_net/)
+ * Python (optional)
+
+Follow the standard instructions for installing an autotools-based
+package:
+
+ 1. Run './configure' to initialize the package.
+ 2. Run 'make' to compile the package.
+ 3. Run 'make install' to install the package.
+
+An automated build script is available that installs the necessary
+dependencies and builds the source code automatically.  See the build
+instructions on the website.
+
+Advanced topics such as cross-compilation are beyond the scope of this
+document.  Please see the GNU autoconf / automake documentation for more
+information.
+
+#endif
+Obtaining an IWAD file
+----------------------
+
+To play Doom, you need an IWAD file.  This file contains the game data
+(graphics, sounds, etc).  The full versions of the Doom games are
+proprietary and need to be bought.  The IWAD file has one of the
+following names:
+
+   doom1.wad                   (Shareware Doom)
+   doom.wad                    (Registered / Ultimate Doom)
+   doom2.wad                   (Doom 2)
+   tnt.wad                     (Final Doom: TNT: Evilution)
+   plutonia.wad                (Final Doom: Plutonia Experiment)
+   chex.wad                    (Chex Quest)
+
+If you don't have a copy of a commercial version, you can download
+the shareware version (extract the file named doom1.wad):
+
+ * http://www.doomworld.com/idgames/index.php?id=7053
+   (idstuff/doom/win95/doom95.zip in your nearest /idgames mirror)
+
+If you have a commercial version, obtaining the IWAD file is usually
+straightforward.  The method depends on how you obtained your copy of
+the game:
+
+#if _WIN32
+ * The Doom games are available to buy for download on Steam
+   (http://www.steampowered.com/).  Chocolate Doom will autodetect
+   IWADs installed by Steam and you do not need to do anything.
+#else
+ * The Doom games are available to buy for download on Steam
+   (http://www.steampowered.com/).  To find the IWAD files on a
+   Windows system, look in the Steam directory (usually within
+   "Program Files"), under the "steamapps/common" path.
+#endif
+
+ * There have been several CD-based versions of Doom.  Generally, the
+   IWAD files can be found on the CD and copied off directly.
+
+#if _WIN32
+ * If the IWAD files are not directly available on the CD, or you have
+   a floppy disk version, you will need to run the install program to
+   install the game to your hard disk.  As the installer is DOS-based,
+   you may not be able to do this on 64-bit versions of Windows.  In
+   this case, the best suggestion is to use a DOS emulator (such as
+   DOSbox) to run the installer.
+#else
+ * If the IWAD files are not directly available on the CD, or you have
+   a floppy disk version, installation is more difficult.  The best
+   suggestion is to use a DOS emulator (such as DOSbox) to run the
+   installer.
+#endif
+
+ * As an alternative to using an emulator, it is possible to extract
+   the files manually.  On the install disk(s), you will find several
+   files with numbered extensions (with CD versions there may be a
+   single large file with the extension .1, eg. "resource.1").
+
+   From the command line it is possible to combine these files into a
+   single large file, using a command similar to the following:
+
+#if _WIN32
+     copy doom_se.1+doom_se.2+doom_se.3+doom_se.4+doom_se.5 doom_se.lha
+#else
+     cat doom_se.1 doom_se.2 doom_se.3 doom_se.4 doom_se.5 > doom_se.lha
+#endif
+
+   The resulting file is an LHA archive file, and it can be extracted
+   using an LHA archive tool (there is one available for almost every
+   operating system).
+
+Running the game
+----------------
+
+#if __MACOSX__
+Once you have an IWAD file, you can specify its location within the
+graphical launcher program.  Click the "Configure..." button, and then
+click "Set..." for each IWAD to choose its location.  From the main
+launcher dialog you can then choose which game you want to play and
+click the "Launch" button to start the game.
+
+If you are an advanced user and like to run Doom from the command
+line, you can use the "Command Prompt..." menu item to open a Terminal
+window.  The DOOMWADPATH environment variable is preconfigured
+to point to the locations of the IWAD files set within the launcher.
+You can launch the game with a specific IWAD file by typing, for
+example:
+
+    chocolate-doom -iwad tnt.wad
+#else
+Chocolate Doom needs to know where to find your IWAD file. To do this,
+do one of the following:
+
+#if _WIN32
+ * Within Explorer, simply place the IWAD file in the same folder as
+   the Chocolate Doom files, and double-click chocolate-doom.exe.
+
+ * Run Chocolate Doom from the command prompt with the '-iwad' command
+   line parameter to specify the IWAD file to use, eg.
+
+       chocolate-doom -iwad c:\games\doom2.wad
+
+ * Set the environment variable DOOMWADDIR to the location of a
+   directory containing your IWAD files.
+
+ * If you have multiple IWADs in different directories, set the
+   environment variable DOOMWADPATH to be a semicolon-separated list
+   of directories to search (similar to the PATH environment
+   variable).
+#else
+ * Run Chocolate Doom from the Unix console with the '-iwad' command
+   line parameter to specify the IWAD file to use, eg.
+
+       chocolate-doom -iwad /root/doom2.wad
+
+ * Put the file into one of the following directories:
+
+     /usr/share/games/doom
+     /usr/local/share/games/doom
+
+ * Set the environment variable DOOMWADDIR to specify the path to a
+   directory containing your IWAD files.
+
+ * If you have multiple IWADs in different directories, set the
+   environment variable DOOMWADPATH to be a colon-separated list of
+   directories to search (similar to the Unix PATH environment
+   variable).
+#endif
+#endif
+
+Playing with Chex Quest
+-----------------------
+
+Chex Quest is a game based on Doom with some minor modifications that
+was distributed with boxes of Chex cereal in 1997.  It is possible to
+play Chex Quest using Chocolate Doom.  To do this, the following files
+are needed:
+
+ * The IWAD file 'chex.wad', from the Chex Quest CD.
+
+ * The dehacked patch 'chex.deh', which can be found here:
+   http://www.doomworld.com/idgames/?id=15420
+   (utils/exe_edit/patches/chexdeh.zip in your nearest /idgames mirror)
+
+Copy these files into a directory together and use the '-iwad' command
+line parameter to specify the Chex Quest IWAD file:
+
+   chocolate-doom -iwad chex.wad
+
+Installing upgrades
+-------------------
+
+Chocolate Doom requires a version 1.9 IWAD file.  Generally, if you
+install a recent version of Doom you should have a version 1.9 IWAD.
+However, if you are installing from a very old CD version or from
+floppy disks, you might find you have an older version.
+
+The most obvious symptom of an out of date IWAD file is that the game
+will exit at the title screen before the demo starts, with the message
+"Demo is from a different game version!".  If this happens, your IWAD
+file is out of date and you need to upgrade.
+
+Id Software released upgrade patches that will update your game to
+version 1.9.  The following sites have the patches:
+
+  http://www.doomworld.com/files/patches.shtml
+  http://www.doom2.net/doom2/utils.html
+  ftp://ftp.idsoftware.com/idstuff/doom2
+
+#if _WIN32
+As the patches are binary patches that run as DOS executables, on
+recent 64-bit versions of Windows you will need to use a DOS emulator
+(such as DOSBox) to run them.
+#else
+As the patches are binary patches that run as DOS executables, you
+will need to use a DOS emulator (such as DOSBox) to run them.
+#endif
+
+Music support
+-------------
+
+Chocolate Doom includes OPL emulation code that accurately reproduces
+the way that the in-game music sounded under DOS when using an
+Adlib/Soundblaster card.  This is, however, not to everyone's taste.
+
+#if _WIN32
+Better quality MIDI playback is possible by using Windows' native
+MIDI synthesizer that is part of the operating system.  Select "Native
+MIDI" within the sound dialog in the setup tool.
+
+#endif
+#if __MACOSX__
+High quality MIDI playback is possible by using Mac OS X's native MIDI
+synthesizer that is part of the operating system. Select "Native MIDI"
+within the sound dialog in the setup tool.
+
+#endif
+As an alternative it is possible to use Timidity for high quality MIDI
+playback:
+
+  http://timidity.sourceforge.net/
+
+A good set of patches for Timidity is the eawpats collection, which can
+be found here:
+
+  http://www.doomworld.com/idgames/index.php?id=13928
+  (Doom idgames archive, /sounds/eawpats.zip)
+
+#ifn PRECOMPILED
+When compiling from source, be sure to compile and install timidity
+before installing SDL_mixer.
+#endif
+
+# vim: tw=70
+
diff --git a/man/Makefile.am b/man/Makefile.am
index 698c0862..618c0bde 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,6 +1,8 @@
 
 MANPAGE_GEN_FILES=manpage.template docgen default.cfg.template extra.cfg.template
 
+docdir=$(prefix)/share/doc/@PACKAGE@
+
 if HAVE_PYTHON
 
 man_MANS=chocolate-doom.6      \
@@ -9,6 +11,8 @@ man_MANS=chocolate-doom.6      \
          default.cfg.5         \
          $(PACKAGE).cfg.5
 
+nodist_doc_DATA=INSTALL
+
 chocolate-doom.6: ../src $(MANPAGE_GEN_FILES)
 	./docgen -m manpage.template ../src > $@
 
@@ -18,9 +22,14 @@ default.cfg.5: ../src default.cfg.template
 $(PACKAGE).cfg.5: ../src extra.cfg.template
 	./docgen -m extra.cfg.template -c $(PACKAGE).cfg ../src > $@
 
+INSTALL: INSTALL.template
+	./simplecpp -DPRECOMPILED < INSTALL.template > $@
+
 endif
 
 EXTRA_DIST = $(man_MANS) $(MANPAGE_GEN_FILES)        \
              wikipages                               \
-             CMDLINE.template
+             CMDLINE.template                        \
+             INSTALL.template                        \
+             simplecpp
 
diff --git a/man/simplecpp b/man/simplecpp
new file mode 100755
index 00000000..d277f278
--- /dev/null
+++ b/man/simplecpp
@@ -0,0 +1,211 @@
+#!/usr/bin/env python
+#
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
+# Contributors to the Freedoom project.  All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#  * Neither the name of the freedoom project nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+# OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#
+# simple cpp-style preprocessor
+#
+# Understands:
+#
+# #define NAME
+#
+# Set an option
+# You can use -D on the command line too
+#
+# #undef NAME
+#
+# Unset an option if it is set
+#
+# #if .. #endif / #ifdef .. #endif
+#
+# Specify a list of options set, eg #ifdef DOOM2 || ULTDOOM || SHAREWARE
+# The block is only displayed if one of the options is set
+#
+# #ifn .. #endif / #ifndef .. #endif
+#
+# Similarly specify a list of options
+# The block is displayed if none of the options are set
+#
+# #include "filename"
+#
+# include the contents of a file
+
+import sys
+import re
+
+debug = False
+defines = {}
+
+command_re = re.compile("\#(\w+)(\s+(.*))?")
+include_re = re.compile("\s*\"(.*)\"\s*")
+
+def debug_msg(message):
+	if debug:
+		sys.stderr.write(message)
+
+# Parse command line options
+
+def parse_cmdline():
+	for arg in sys.argv[1:]:
+		if arg.startswith("-D"):
+			name = arg[2:]
+			defines[name] = True
+
+def parse_stream(stream):
+	result = read_block(stream, False)
+
+	if result is not None:
+		raise Exception("Mismatched #if in '%s'" % stream.name)
+
+def parse_file(filename):
+	f = open(filename)
+
+	try:
+		parse_stream(f)
+	finally:
+		f.close()
+
+# #include
+
+def cmd_include(arg):
+	# Extract the filename
+
+	match = include_re.match(arg)
+
+	if not match:
+		raise Exception("Invalid 'include' command")
+
+	filename = match.group(1)
+
+	# Open the file and process it
+
+	parse_file(filename)
+
+# #define
+
+def cmd_define(arg):
+	defines[arg] = True
+
+# #undef
+
+def cmd_undef(arg):
+	if arg in defines:
+		del defines[arg]
+
+# #ifdef/#ifndef
+
+def cmd_ifdef(arg, command, stream, ignore):
+
+	# Get the define name
+	name = arg.strip()
+
+	debug_msg("%s %s >\n" % (command, arg))
+
+	# Should we ignore the contents of this block?
+
+	sub_ignore = (name not in defines)
+
+	if "n" in command:
+		sub_ignore = not sub_ignore
+
+	# Parse the block
+
+	result = read_block(stream, ignore or sub_ignore)
+
+	debug_msg("%s %s < (%s)\n" % (command, arg, result))
+
+	# There may be a second "else" block to parse:
+
+	if result == "else":
+		debug_msg("%s %s else >\n" % (command, arg))
+		result = read_block(stream, ignore or (not sub_ignore))
+		debug_msg("%s %s else < (%s)\n" % (command, arg, result))
+
+	# Should end in an endif:
+
+	if result != "endif":
+		raise Exception("'if' block did not end in an 'endif'")
+
+commands = {
+	"include" : cmd_include,
+	"define"  : cmd_define,
+	"undef"   : cmd_undef,
+	"if"      : cmd_ifdef,
+	"ifdef"   : cmd_ifdef,
+	"ifn"     : cmd_ifdef,
+	"ifndef"  : cmd_ifdef,
+}
+
+# Recursive block reading function
+# if 'ignore' argument is 1, contents are ignored
+
+def read_block(stream, ignore):
+
+	for line in stream:
+
+		# Remove newline
+
+		line = line[0:-1]
+
+		# Check if this line has a command
+
+		match = command_re.match(line)
+
+		if match:
+			command = match.group(1)
+			arg = match.group(3)
+
+			if command == "else" or command == "endif":
+				return command
+			elif command not in commands:
+				raise Exception("Unknown command: '%s'" % \
+						command)
+
+			# Get the callback function.
+
+			func = commands[command]
+
+			# Invoke the callback function. #ifdef commands
+			# are a special case and need extra arguments.
+			# Other commands are only executed if we are not
+			# ignoring this block.
+
+			if func == cmd_ifdef:
+				cmd_ifdef(arg, command=command,
+					       stream=stream,
+					       ignore=ignore)
+			elif not ignore:
+				func(arg)
+		else:
+			if not ignore:
+				print(line)
+
+parse_cmdline()
+parse_stream(sys.stdin)
+