Javadoc-style self-documenting system for command line options.

Subversion-branch: /trunk/chocolate-doom
Subversion-revision: 806

7 files changed, 171 insertions, 71 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index 4d5f407c..fb339fc4 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,14 +1,10 @@
 
-MANPAGE_GEN_FILES=chocolate-doom-options.in head foot Makefile doom-options.in
+MANPAGE_GEN_FILES=header footer 
 
 man_MANS=chocolate-doom.6
 
 EXTRA_DIST = $(man_MANS) $(MANPAGE_GEN_FILES)
 
 chocolate-doom.6: $(MANPAGE_GEN_FILES)
-	cp head $@
-	echo .SH DOOM OPTIONS >> $@
-	awk -F"\t" '{print ".TP\n\\fB"$$1"\\fR"; $$1=""; print }' < doom-options.in >>$@
-	echo .SH CHOCOLATE DOOM OPTIONS >> $@
-	awk -F"\t" '{print ".TP\n\\fB"$$1"\\fR"; $$1=""; print }' < chocolate-doom-options.in >>$@
-	sed "s/AUTHORS/`cat ../AUTHORS`/" < foot >> $@
+	./docgen > $@
+
diff --git a/man/chocolate-doom-options.in b/man/chocolate-doom-options.in
deleted file mode 100644
index 2d2cc23a..00000000
--- a/man/chocolate-doom-options.in
+++ /dev/null
@@ -1,14 +0,0 @@
--1	Sets screenmultiply to 1
--2	Sets screenmultiply to 2, doubling up the screen by 2x.
--extraconfig <file>	Specifies a configuration file to use for Chocolate Doom-specific settings. The default is 'chocolate-doom.cfg'
--fullscreen	Runs the game fullscreen. 
--nofullscreen	Runs the game in a window
--window	runs the game in a window
--gameversion <ver>	Emulates a specific release of Doom 1.9.  Valid values are "1.9", "ultimate" and "final".
--grabmouse	Grabs the mouse during play
--nograbmouse	Does not grab the mouse during play
--iwad <file>	Specifies an IWAD file to use. If unspecified, chocolate doom will look for doom2.wad, doom.wad, tnt.wad, plutonia.wad, in /usr/share/games/doom, and the current directory.
--longtics	When recording demos, records in the the modified "Doom v1.91" format to avoid losing turning resolution.
--merge <file>	Loads a PWAD but simulates merging it into the main IWAD
--novert	Turns on novert
--nonovert	Turns off novert
diff --git a/man/docgen b/man/docgen
new file mode 100755
index 00000000..c83cb901
--- /dev/null
+++ b/man/docgen
@@ -0,0 +1,154 @@
+#!/usr/bin/env python
+
+import re
+import glob
+
+class Category:
+    def __init__(self, description):
+        self.description = description
+        self.params = []
+
+    def add_param(self, param):
+        self.params.append(param)
+
+    def format(self):
+        result = ".SH " + self.description.upper() + "\n"
+
+        for p in self.params:
+            result += ".TP\n"
+            result += p.format()
+
+        return result
+
+categories = {
+    None:      Category("General options"),
+    "video":   Category("Display options"),
+    "demo":    Category("Demo options"),
+    "net":     Category("Networking options"),
+    "mod":     Category("Dehacked and WAD merging"),
+    "compat":  Category("Compatibility"),
+}
+
+class Parameter:
+    def __init__(self):
+        self.text = ""
+        self.name = ""
+        self.args = None
+        self.platform = None
+        self.category = None
+
+    def add_text(self, text):
+        if len(text) <= 0:
+            pass
+        elif text[0] == "@":
+            match = re.match('@(\S+)\s+(.*)', text)
+
+            if not match:
+                raise "Malformed option line: %s" % text
+
+            option_type = match.group(1)
+            data = match.group(2)
+            
+            if option_type == "arg":
+                self.args = data
+            elif option_type == "platform":
+                self.platform = data
+            elif option_type == "category":
+                self.category = data
+            else:
+                raise "Unknown option type '%s'" % option_type
+
+        else:
+            self.text += text + " "
+
+    def format(self):
+        result = self.name
+
+        if self.args:
+            result += " " + self.args
+
+        result = '\\fB' + result + '\\fR'
+
+        result += "\n"
+
+        if self.platform:
+            result += "[%s only] " % self.platform
+
+        result += self.text + "\n"
+
+        return result
+
+def process_file(file):
+    f = open(file)
+
+    try:
+        param = None
+        waiting_for_checkparm = False
+
+        for line in f:
+            line = line.rstrip()
+
+            # Currently reading a doc comment?
+
+            if param:
+                # End of doc comment
+
+                if not re.match('\s*//', line):
+                    waiting_for_checkparm = True
+
+                # Waiting for the M_CheckParm call that contains the
+                # name of the parameter we are documenting?
+
+                if waiting_for_checkparm:
+                    match = re.search('M_CheckParm\s*\(\s*"(.*?)"\s*\)', line)
+
+                    if match:
+                        # Found the name!  Finished documenting this 
+                        # parameter.
+
+                        param.name = match.group(1)
+                        categories[param.category].add_param(param)
+                        param = None
+
+                else:
+                    # More documentation text
+
+                    munged_line = re.sub('\s*\/\/\s*', '', line, 1)
+                    munged_line = re.sub('\s*$', '', munged_line)
+                    param.add_text(munged_line)
+
+            # Check for start of a doc comment
+
+            if re.search("//!", line):
+                param = Parameter()
+                waiting_for_checkparm = False
+    finally:
+        f.close()
+
+def print_file_contents(file):
+    f = open(file)
+
+    try:
+        for line in f:
+            print line.rstrip()
+
+    finally:
+        f.close()
+
+# Process all C source files.
+
+files = glob.glob("../src/*.c")
+
+for file in files:
+    process_file(file)
+
+print_file_contents("header")
+
+print categories[None].format()
+
+for c in categories:
+    if c != None:
+        print categories[c].format()
+
+print_file_contents("footer")
+
diff --git a/man/doom-options.in b/man/doom-options.in
deleted file mode 100644
index 3261f900..00000000
--- a/man/doom-options.in
+++ /dev/null
@@ -1,30 +0,0 @@
--deathmatch	start a deathmatch game
--altdeath	start a deathmatch game (alternative mode)
--timer x	exit a deathmatch level after x minutes
--avg	austin virtual gaming (same as -timer 20)
--cdrom	use C:\\DOOMDATA for configuration data
--config x	use x as the configuration file
--devparm	developer mode: F1 saves a PCX screenshot in the current working directory
--dup	put two network commands in each network packet
--episode e	start playing on episode e (from 1-4)
--extratic	send two packets per tic for network redundancy
--fast	monsters move faster
--file f...	add the PWADs f...
--loadgame s	load the save in slot s
--maxdemo x	set the maximum byte size of the recorded demo
--nodes	define the number of players in a network game
-# <not implemented yet> -nodraw	no drawing of the screen is performed
--nomonsters	disable all monsters
--respawn	monsters respawn after being killed
--nomusic	disable music
--nosfx	disable sound effects
--nosound	equivalent to -nomusic -nosfx
--playdemo x	play demo from file x.lmp
--record	record a demo to file x.lmp
--recordfrom x y	start recording y.lmp from save slot x
--skill x 	set the game skill (0-5; 5 being hardest)
--statcopy x	register a stats driver at memory location x
--timedemo x	play x.lmp at double speed and display the redraw count
--warp [x y|zz]	start the game at level ExMy or MAPyy
--wart x y	load PWAD ExMy.WAD and warp to level ExMy
--turbo x	multiple player speed by x%. If unspecified, x defaults to 200. Values are rounded up to 10 and down to 400.
diff --git a/man/foot b/man/footer
index bed6ee78..164ca8ed 100644
--- a/man/foot
+++ b/man/footer
@@ -1,7 +1,7 @@
 .\" this section from foot
 .SH AUTHOR
 Chocolate Doom is written and maintained by
-AUTHORS.
-The manpage was written by Jon Dowland <jon@alcopop.org>.
+Simon Howard.
 .SH COPYRIGHT
 Copyright \(co 2006 Simon Howard.
+
diff --git a/man/head b/man/head
deleted file mode 100644
index ca3888a9..00000000
--- a/man/head
+++ /dev/null
@@ -1,18 +0,0 @@
-.\" this section from head
-.TH chocolate\-doom 6
-.SH NAME
-chocolate\-doom \- historically compatible doom engine
-.SH SYNOPSIS
-.B chocolate\-doom
-[\fIDOOM OPTIONS\fR]
-[\fICHOCOLATE\-DOOM OPTIONS\fR]
-.SH DESCRIPTION
-.PP
-Chocolate Doom is a modern doom engine designed to behave
-as similar to the original doom game as is possible.
-.br
-Command-line arguments are divided up into \fBDOOM
-OPTIONS\fR, a subset of the original doom's command line
-arguments, and \fBCHOCOLATE\-DOOM OPTIONS\fR which are
-specific to this engine.
-.\" this section generated from vanilla-doom-options.in
diff --git a/man/header b/man/header
new file mode 100644
index 00000000..8917506b
--- /dev/null
+++ b/man/header
@@ -0,0 +1,12 @@
+.\" this section from head
+.TH chocolate\-doom 6
+.SH NAME
+chocolate\-doom \- historically compatible doom engine
+.SH SYNOPSIS
+.B chocolate\-doom
+[\fIOPTIONS\fR]
+.SH DESCRIPTION
+.PP
+Chocolate Doom is a modern doom engine designed to behave
+as similar to the original doom game as is possible.
+.br