From 0d3b41b4a00e11b09583069b8f7f72a11400d737 Mon Sep 17 00:00:00 2001 From: Simon Howard Date: Sun, 24 Dec 2006 23:53:15 +0000 Subject: Javadoc-style self-documenting system for command line options. Subversion-branch: /trunk/chocolate-doom Subversion-revision: 806 --- man/Makefile.am | 10 +-- man/chocolate-doom-options.in | 14 ---- man/docgen | 154 ++++++++++++++++++++++++++++++++++++++++++ man/doom-options.in | 30 -------- man/foot | 7 -- man/footer | 7 ++ man/head | 18 ----- man/header | 12 ++++ 8 files changed, 176 insertions(+), 76 deletions(-) delete mode 100644 man/chocolate-doom-options.in create mode 100755 man/docgen delete mode 100644 man/doom-options.in delete mode 100644 man/foot create mode 100644 man/footer delete mode 100644 man/head create mode 100644 man/header (limited to 'man') 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 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 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 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 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 -# -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/foot deleted file mode 100644 index bed6ee78..00000000 --- a/man/foot +++ /dev/null @@ -1,7 +0,0 @@ -.\" this section from foot -.SH AUTHOR -Chocolate Doom is written and maintained by -AUTHORS. -The manpage was written by Jon Dowland . -.SH COPYRIGHT -Copyright \(co 2006 Simon Howard. diff --git a/man/footer b/man/footer new file mode 100644 index 00000000..164ca8ed --- /dev/null +++ b/man/footer @@ -0,0 +1,7 @@ +.\" this section from foot +.SH AUTHOR +Chocolate Doom is written and maintained by +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 -- cgit v1.2.3