Rework documentation system to generate INSTALL files tailored for the

different games.

Subversion-branch: /branches/v2-branch
Subversion-revision: 2652

3 files changed, 153 insertions, 110 deletions

diff --git a/man/INSTALL.template b/man/INSTALL.template
index 6a26cc03..5597439f 100644
--- a/man/INSTALL.template
+++ b/man/INSTALL.template
@@ -1,16 +1,31 @@
+#ifdef DOOM
+#define LONG_GAME_NAME Chocolate Doom
+#define LONG_EXE_NAME  chocolate-doom
+#define DEFAULT_IWAD   doom2.wad
+#elif HERETIC
+#define LONG_GAME_NAME Chocolate Heretic
+#define LONG_EXE_NAME  chocolate-heretic
+#define DEFAULT_IWAD   heretic.wad
+#elif HEXEN
+#define LONG_GAME_NAME Chocolate Hexen
+#define LONG_EXE_NAME  chocolate-hexen
+#define DEFAULT_IWAD   hexen.wad
+#elif STRIFE
+#define LONG_GAME_NAME Chocolate Strife
+#define LONG_EXE_NAME  chocolate-strife
+#define DEFAULT_IWAD   strife1.wad
+#endif
 
-Chocolate Doom installation
-===========================
+== LONG_GAME_NAME installation ==
 
-These are instructions for how to install and set up Chocolate Doom
+These are instructions for how to install and set up LONG_GAME_NAME
 for play.
 
-#ifn PRECOMPILED
-Building Chocolate Doom
------------------------
+#if !PRECOMPILED
+== Building LONG_GAME_NAME ==
 
-Before you can play Chocolate Doom, you need to compile a binary that
-you can run.  For compilation, Chocolate Doom requires the following
+Before you can play LONG_GAME_NAME, you need to compile a binary that
+you can run.  For compilation, LONG_GAME_NAME requires the following
 to be installed:
 
  * A C compiler (gcc is recommended)
@@ -36,80 +51,82 @@ document.  Please see the GNU autoconf / automake documentation for more
 information.
 
 #endif
-Obtaining an IWAD file
-----------------------
+== Obtaining an IWAD file ==
 
 To play, you need an IWAD file.  This file contains the game data
 (graphics, sounds, etc). The full versions of the games are
 proprietary and need to be bought.  The IWAD file has one of the
 following names:
 
+#if DOOM
    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)
-   heretic.wad                 (Heretic)
+#endif
+#if HERETIC
+   heretic1.wad                (Shareware Heretic)
+   heretic.wad                 (Registered / Commercial Heretic)
+#endif
+#if HEXEN
    hexen.wad                   (Hexen)
+#endif
+#if STRIFE
    strife1.wad (+voices.wad)   (Strife)
+#endif
 
+#if DOOM
 If you don't have a copy of a commercial version, you can download
 the shareware version of Doom (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/), but are available for Windows only.
-   To find the IWAD files on a Windows system, look in the Steam
-   directory (usually within "Program Files"), under the
-   "steamapps/common" path.
 #endif
+If you have a commercial version on a CD-ROM, obtaining the IWAD
+file is usually straightforward. Simply locate the IWAD file on the
+disc and copy it off.
 
- * There have been several CD-based versions of Doom. Generally, the
-   IWAD files can be found on the CD and copied off directly.
-
+#if !STRIFE
 #if _WIN32
- * If 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 easiest suggestion is to use a DOS
-   emulator (such as DOSbox) to run the installer.
+The Doom games, along with Heretic and Hexen, are also available to
+purchase for download on Steam (http://www.steampowered.com/).
+LONG_GAME_NAME will autodetect IWADs installed by Steam and you do
+not need to do anything.
 #else
- * If you have a floppy disk version, installation is more difficult.
-   The easiest suggestion is to use a DOS emulator (such as DOSbox) to
-   run the installer.
+The Doom games, along with Heretic and Hexen, are available to buy
+for download on Steam (http://www.steampowered.com/), but are only
+available for Windows. To find the IWAD files on a Windows system,
+look in the Steam directory (usually within "Program Files"), under
+the "steamapps/common" path.
 #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 (eg. "doom_se.1").
+#endif
+#if DOOM || HERETIC
+Older floppy disk versions are harder to deal with. The easiest way
+to install from floppies is to run the original installer program
+inside an emulator such as DOSbox (http://www.dosbox.com/).
+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 (eg. "doom_se.1").
 
-   From the command line it is possible to combine these files into a
-   single large file, using a command similar to the following:
+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
+   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
+   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).
+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
-----------------
+#endif
+== Running the game ==
 
 #if __MACOSX__
 Once you have an IWAD file, you can specify its location within the
@@ -125,19 +142,19 @@ 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
+    LONG_EXE_NAME -iwad tnt.wad
 #else
-Chocolate Doom needs to know where to find your IWAD file. To do this,
+LONG_GAME_NAME 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.
+   the LONG_GAME_NAME files, and double-click LONG_EXE_NAME.exe.
 
- * Run Chocolate Doom from the command prompt with the '-iwad' command
+ * Run LONG_GAME_NAME 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
+       LONG_EXE_NAME -iwad c:\games\DEFAULT_IWAD
 
  * Set the environment variable DOOMWADDIR to the location of a
    directory containing your IWAD files.
@@ -147,10 +164,10 @@ do one of the following:
    of directories to search (similar to the PATH environment
    variable).
 #else
- * Run Chocolate Doom from the Unix console with the '-iwad' command
+ * Run LONG_GAME_NAME from the Unix console with the '-iwad' command
    line parameter to specify the IWAD file to use, eg.
 
-       chocolate-doom -iwad /root/doom2.wad
+       LONG_EXE_NAME -iwad /root/DEFAULT_IWAD
 
  * Put the file into one of the following directories:
 
@@ -167,12 +184,12 @@ do one of the following:
 #endif
 #endif
 
-Playing with Chex Quest
------------------------
+#if DOOM
+== 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
+play Chex Quest using LONG_GAME_NAME.  To do this, the following files
 are needed:
 
  * The IWAD file 'chex.wad', from the Chex Quest CD.
@@ -184,12 +201,11 @@ are needed:
 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
+   LONG_EXE_NAME -iwad chex.wad
 
-Installing upgrades
--------------------
+== Installing upgrades ==
 
-Chocolate Doom requires a version 1.9 IWAD file.  Generally, if you
+LONG_GAME_NAME 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.
@@ -215,10 +231,10 @@ 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
--------------
+#endif
+== Music support ==
 
-Chocolate Doom includes OPL emulation code that accurately reproduces
+LONG_GAME_NAME 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.
 
@@ -245,7 +261,7 @@ be found here:
   http://www.doomworld.com/idgames/index.php?id=13928
   (Doom idgames archive, /sounds/eawpats.zip)
 
-Chocolate Doom also has provides a very limited form "emulation" of
+LONG_GAME_NAME also has provides a very limited form "emulation" of
 the Gravis Ultrasound (GUS) card, using Timidity's GUS patch file
 support. To use this requires a copy of the GUS patch files, found
 here:
@@ -253,7 +269,7 @@ here:
   http://www.doomworld.com/idgames/index.php?id=17127
   (Doom idgames archive, /music/dgguspat.zip)
 
-#ifn PRECOMPILED
+#if !PRECOMPILED
 When compiling from source, be sure to compile and install Timidity
 before installing SDL_mixer.
 
diff --git a/man/Makefile.am b/man/Makefile.am
index 5eb787f1..17ffbe22 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -27,8 +27,9 @@ man_MANS=chocolate-server.6       \
          strife.cfg.5             \
          chocolate-strife.cfg.5
 
-nodist_doc_DATA=INSTALL CMDLINE.doom CMDLINE.heretic \
-                CMDLINE.hexen CMDLINE.strife
+nodist_doc_DATA=INSTALL \
+    INSTALL.doom INSTALL.heretic INSTALL.hexen INSTALL.strife \
+    CMDLINE.doom CMDLINE.heretic CMDLINE.hexen CMDLINE.strife
 
 
 
@@ -43,9 +44,11 @@ chocolate-doom.cfg.5: ../src extra.cfg.template
 	./docgen -g doom -m extra.cfg.template \
                  -c extended ../src/m_config.c > $@
 
-CMDLINE.doom : ../src ../src/doom
+CMDLINE.doom : CMDLINE.template ../src ../src/doom
 	./docgen -p CMDLINE.template ../src/ ../src/doom/ > $@
 
+INSTALL.doom: INSTALL.template
+	./simplecpp -DDOOM -DPRECOMPILED < INSTALL.template > $@
 
 
 chocolate-heretic.6: ../src $(MANPAGE_GEN_FILES)
@@ -59,9 +62,12 @@ chocolate-heretic.cfg.5: ../src extra.cfg.template
 	./docgen -g heretic -m extra.cfg.template \
                  -c extended ../src/m_config.c > $@
 
-CMDLINE.heretic : ../src ../src/heretic
+CMDLINE.heretic : CMDLINE.template ../src ../src/heretic
 	./docgen -p CMDLINE.template ../src/ ../src/heretic/ > $@
 
+INSTALL.heretic: INSTALL.template
+	./simplecpp -DHERETIC -DPRECOMPILED < INSTALL.template > $@
+
 
 chocolate-hexen.6: ../src $(MANPAGE_GEN_FILES)
 	./docgen -g hexen -m hexen.template ../src ../src/hexen > $@
@@ -74,9 +80,11 @@ chocolate-hexen.cfg.5: ../src extra.cfg.template
 	./docgen -g hexen -m extra.cfg.template \
                  -c extended ../src/m_config.c > $@
 
-CMDLINE.hexen : ../src ../src/hexen
+CMDLINE.hexen : CMDLINE.template ../src ../src/hexen
 	./docgen -p CMDLINE.template ../src/ ../src/hexen/ > $@
 
+INSTALL.hexen: INSTALL.template
+	./simplecpp -DHEXEN -DPRECOMPILED < INSTALL.template > $@
 
 
 chocolate-strife.6: ../src $(MANPAGE_GEN_FILES)
@@ -90,13 +98,16 @@ chocolate-strife.cfg.5: ../src extra.cfg.template
 	./docgen -g strife -m extra.cfg.template \
                  -c extended ../src/m_config.c > $@
 
-CMDLINE.strife : ../src ../src/strife
+CMDLINE.strife : CMDLINE.template ../src ../src/strife
 	./docgen -p CMDLINE.template ../src/ ../src/strife/ > $@
 
+INSTALL.strife: INSTALL.template
+	./simplecpp -DSTRIFE -DPRECOMPILED < INSTALL.template > $@
 
 
 INSTALL: INSTALL.template
-	./simplecpp -DPRECOMPILED < INSTALL.template > $@
+	./simplecpp -DDOOM -DHERETIC -DHEXEN -DSTRIFE \
+	            -DPRECOMPILED < INSTALL.template > $@
 
 endif
 
diff --git a/man/simplecpp b/man/simplecpp
index d277f278..000940fc 100755
--- a/man/simplecpp
+++ b/man/simplecpp
@@ -31,39 +31,24 @@
 #
 # simple cpp-style preprocessor
 #
-# Understands:
+# Understands most features of the C preprocessor, including:
+#    #if .. #elif .. #else .. #endif
+#        - with expressions
+#    #ifdef
+#    #define
+#    #include
 #
-# #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 collections
 import sys
 import re
 
 debug = False
-defines = {}
+defines = collections.defaultdict(lambda: False)
 
-command_re = re.compile("\#(\w+)(\s+(.*))?")
-include_re = re.compile("\s*\"(.*)\"\s*")
+command_re = re.compile(r"\#(\w+)(\s+(.*))?")
+include_re = re.compile(r"\s*\"(.*)\"\s*")
+define_re = re.compile(r"\s*(\S+)\s*(.*?)\s*$")
 
 def debug_msg(message):
 	if debug:
@@ -73,9 +58,16 @@ def debug_msg(message):
 
 def parse_cmdline():
 	for arg in sys.argv[1:]:
-		if arg.startswith("-D"):
-			name = arg[2:]
-			defines[name] = True
+		if not arg.startswith("-D"):
+			continue
+
+		name = arg[2:]
+		if '=' in name:
+			name, value = name.split('=', 1)
+		else:
+			value = True
+
+		defines[name] = value
 
 def parse_stream(stream):
 	result = read_block(stream, False)
@@ -91,6 +83,17 @@ def parse_file(filename):
 	finally:
 		f.close()
 
+# Evaluate an expression using Python's eval() function.
+
+def eval_expr(expr):
+	expr = expr.replace("||", " or ")   \
+	           .replace("&&", " and ")  \
+	           .replace("!", "not ")
+
+	code = compile(expr, "", "eval")
+	result = eval(code, {}, defines)
+	return result
+
 # #include
 
 def cmd_include(arg):
@@ -110,7 +113,13 @@ def cmd_include(arg):
 # #define
 
 def cmd_define(arg):
-	defines[arg] = True
+	match = define_re.match(arg)
+	name = match.group(1)
+	value = match.group(2)
+	if value == '':
+		value = True
+
+	defines[name] = value
 
 # #undef
 
@@ -123,20 +132,19 @@ def cmd_undef(arg):
 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)
+	sub_ignore = not eval_expr(arg)
 
 	if "n" in command:
 		sub_ignore = not sub_ignore
 
 	# Parse the block
 
-	result = read_block(stream, ignore or sub_ignore)
+	result, newarg = read_block(stream, ignore or sub_ignore)
 
 	debug_msg("%s %s < (%s)\n" % (command, arg, result))
 
@@ -144,9 +152,14 @@ def cmd_ifdef(arg, command, stream, ignore):
 
 	if result == "else":
 		debug_msg("%s %s else >\n" % (command, arg))
-		result = read_block(stream, ignore or (not sub_ignore))
+		result, arg = read_block(stream, ignore or (not sub_ignore))
 		debug_msg("%s %s else < (%s)\n" % (command, arg, result))
 
+	if result == "elif":
+		debug_msg("%s %s elif %s>\n" % (command, arg, newarg))
+		cmd_ifdef(newarg, "if", stream, ignore or (not sub_ignore))
+		result = "endif"
+
 	# Should end in an endif:
 
 	if result != "endif":
@@ -181,8 +194,8 @@ def read_block(stream, ignore):
 			command = match.group(1)
 			arg = match.group(3)
 
-			if command == "else" or command == "endif":
-				return command
+			if command in ("else", "elif", "endif"):
+				return (command, arg)
 			elif command not in commands:
 				raise Exception("Unknown command: '%s'" % \
 						command)
@@ -204,6 +217,9 @@ def read_block(stream, ignore):
 				func(arg)
 		else:
 			if not ignore:
+				for key, value in defines.iteritems():
+					if isinstance(value, str):
+						line = line.replace(key, value)
 				print(line)
 
 parse_cmdline()