ref: 3951c995ebb761de6bfc2f852c5a81eb51ba42f5
parent: 7329c58b0d10b2705594b35ae000301c80e29eb7
author: Simon Howard <[email protected]>
date: Mon Feb 25 18:50:07 EST 2008
Replace manpage header, footer, environment files with a single template file. Generate documentation for the default.cfg and chocolate-doom.cfg configuration files. Subversion-branch: /trunk/chocolate-doom Subversion-revision: 1091
--- a/Makefile.am
+++ b/Makefile.am
@@ -49,7 +49,7 @@
if HAVE_PYTHON
CMDLINE : src/
- ./man/docgen -p src/ > $@
+ ./man/docgen -p man/CMDLINE.template src/ > $@
endif
--- a/man/.gitignore
+++ b/man/.gitignore
@@ -1,3 +1,4 @@
Makefile.in
Makefile
*.6
+*.5
--- /dev/null
+++ b/man/CMDLINE.template
@@ -1,0 +1,8 @@
+== Command line parameters ==
+
+This is a list of the command line parameters supported by Chocolate Doom.
+A number of additional parameters are supported in addition to those
+present in Vanilla Doom.
+
+@content
+
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,12 +1,22 @@
-MANPAGE_GEN_FILES=header footer environment docgen
+MANPAGE_GEN_FILES=manpage.template docgen default.cfg.template extra.cfg.template
if HAVE_PYTHON
-man_MANS=chocolate-doom.6 chocolate-server.6 chocolate-setup.6
+man_MANS=chocolate-doom.6 \
+ chocolate-server.6 \
+ chocolate-setup.6 \
+ default.cfg.5 \
+ $(PACKAGE).cfg.5
chocolate-doom.6: ../src $(MANPAGE_GEN_FILES)
- ./docgen -m ../src > $@
+ ./docgen -m manpage.template ../src > $@
+
+default.cfg.5: ../src default.cfg.template
+ ./docgen -m default.cfg.template -c default.cfg ../src > $@
+
+$(PACKAGE).cfg.5: ../src extra.cfg.template
+ ./docgen -m extra.cfg.template -c $(PACKAGE).cfg ../src > $@
endif
--- /dev/null
+++ b/man/default.cfg.template
@@ -1,0 +1,53 @@
+.TH default.cfg 5
+.SH NAME
+default.cfg \- Chocolate Doom configuration file
+.SH DESCRIPTION
+.PP
+\fIdefault.cfg\fR
+is the configuration file for \fBchocolate-doom\fR(6). The configuration
+options stored in the file are the same as those stored in the
+original DOS Vanilla Doom.
+Extra Chocolate Doom-specific options are stored in a separate
+configuration file, \fBchocolate-doom.cfg\fR.
+.PP
+\fIdefault.cfg\fR is normally stored in the user's home directory,
+in \fI~/.chocolate-doom/default.cfg\fR.
+.PP
+The \fBchocolate-setup\fR(6) tool provides a simple to use front-end
+for editing \fIdefault.cfg\fR.
+.br
+.SH FILE FORMAT
+The file is a plain-text file, consisting of a list of configuration
+options and their values, separated by whitespace. Each option is stored
+on a separate line. Options have different types; an option may have
+either an integer, floating point or string value. If the option is
+of a string type, the value is surrounded by quotes (").+.PP
+For example:
+.RS
+.PP
+integer_value 1
+.br
+integer_value2 1
+.br
+floating_point_value 4.2
+.br
+string_value "hello world"
+.RE
+.PP
+Invalid lines or comments in the file will be ignored, but it is advisable
+not to put them in the file; the file is rewritten from scratch every time
+the game exits, so any invalid lines or comments will be lost.
+.PP
+Some options are used for keyboard key bindings; these are stored as
+integer values containing the keyboard scan code of the key to be bound to.
+Boolean values are also stored as integers, with a value of zero usually
+indicating "false" and a non-zero value indicating "true".
+
+@content
+
+.SH SEE ALSO
+\fBchocolate-doom\fR(6),
+\fBchocolate-doom.cfg\fR(5),
+\fBchocolate-setup\fR(6)
+
--- a/man/docgen
+++ b/man/docgen
@@ -1,8 +1,12 @@
#!/usr/bin/env python
#
-# Command line parameter self-documentation tool. Reads comments from
-# the source code in the following form:
+# Chocolate Doom self-documentation tool. This works similar to javadoc
+# or doxygen, but documents command line parameters and configuration
+# file values, generating documentation in Unix manpage, wikitext and
+# plain text forms.
#
+# Comments are read from the source code in the following form:
+#
# //!
# // @arg <extra arguments>
# // @category Category
@@ -13,38 +17,80 @@
#
# something_involving = M_CheckParm("-param");#
-# From this, a manpage can be automatically generated of the command
-# line parameters.
+# For configuration file values:
+#
+# //! @begin_config_file myconfig.cfg
+#
+# //!
+# // Description of the configuration file value.
+# //
+#
+# CONFIG_VARIABLE_INT(my_variable, c_variable),
+#
import sys
+import os
import re
import glob
import getopt
-class Category:
- def __init__(self, description):
- self.description = description
- self.params = []
+# Find the maximum width of a list of parameters (for plain text output)
- def add_param(self, param):
- self.params.append(param)
+def parameter_list_width(params):
+ w = 0
- # Find the maximum width of a parameter in this category
+ for p in params:
+ pw = len(p.name) + 5
- def paramtext_width(self):
- w = 0
+ if p.args:
+ pw += len(p.args)
- for p in self.params:
- pw = len(p.name) + 5
+ if pw > w:
+ w = pw
- if p.args:
- pw += len(p.args)
+ return w
- if pw > w:
- w = pw
+class ConfigFile:
+ def __init__(self, filename):
+ self.filename = filename
+ self.variables = []
- return w
+ def add_variable(self, variable):
+ self.variables.append(variable)
+ def manpage_output(self):
+ result = ".SH CONFIGURATION VARIABLES\n"
+
+ self.variables.sort()
+
+ for v in self.variables:
+ result += ".TP\n"
+ result += v.manpage_output()
+
+ return result
+
+ def plaintext_output(self):
+ result = ""
+
+ self.variables.sort()
+
+ w = parameter_list_width(self.variables)
+
+ for p in self.variables:
+ result += p.plaintext_output(w)
+
+ result = result.rstrip() + "\n"
+
+ return result
+
+class Category:
+ def __init__(self, description):
+ self.description = description
+ self.params = []
+
+ def add_param(self, param):
+ self.params.append(param)
+
# Plain text output
def plaintext_output(self):
@@ -52,7 +98,7 @@
self.params.sort()
- w = self.paramtext_width()
+ w = parameter_list_width(self.params)
for p in self.params:
if p.should_show():
@@ -101,6 +147,7 @@
}
wikipages = []
+config_files = {}# Show options that are in Vanilla Doom? Or only new options?
@@ -249,7 +296,29 @@
return text
+def add_parameter(param, line, config_file):
+
+ # Is this documenting a command line parameter?
+
+ match = re.search('M_CheckParm\s*\(\s*"(.*?)"\s*\)', line)+
+ if match:
+ param.name = match.group(1)
+ categories[param.category].add_param(param)
+ return
+
+ # Documenting a configuration file variable?
+
+ match = re.search('CONFIG_VARIABLE_\S+\s*\(\s*(\S+?),', line)+
+ if match:
+ param.name = match.group(1)
+ config_file.add_variable(param)
+
def process_file(file):
+
+ current_config_file = None
+
f = open(file)
try:
@@ -259,6 +328,11 @@
for line in f:
line = line.rstrip()
+ # Ignore empty lines
+
+ if re.match('\s*$', line):+ continue
+
# Currently reading a doc comment?
if param:
@@ -267,20 +341,12 @@
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?
+ # The first non-empty line after the documentation comment
+ # ends must contain the thing being documented.
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
-
+ add_parameter(param, line, current_config_file)
+ param = None
else:
# More documentation text
@@ -291,8 +357,17 @@
# Check for start of a doc comment
if re.search("//!", line):- param = Parameter()
- waiting_for_checkparm = False
+ match = re.search("@begin_config_file\s*(\S+)", line)+
+ if match:
+ # Beginning a configuration file
+ filename = match.group(1)
+ current_config_file = ConfigFile(filename)
+ config_files[filename] = current_config_file
+ else:
+ # Start of a normal comment
+ param = Parameter()
+ waiting_for_checkparm = False
finally:
f.close()
@@ -299,64 +374,55 @@
def process_files(dir):
# Process all C source files.
- files = glob.glob(dir + "/*.c")
+ if os.path.isdir(dir):
+ files = glob.glob(dir + "/*.c")
- for file in files:
- process_file(file)
+ for file in files:
+ process_file(file)
+ else:
+ # Special case to allow a single file to be specified as a target
-def print_file_contents(file):
- f = open(file)
+ process_file(dir)
+def print_template(template_file, content):
+ f = open(template_file)
+
try:
for line in f:
+ line = line.replace("@content", content)print line.rstrip()
finally:
f.close()
-def manpage_output(dir):
+def manpage_output(targets, template_file):
+
+ content = ""
- process_files(dir)
+ for t in targets:
+ content += t.manpage_output() + "\n"
- print_file_contents("header")+ print_template(template_file, content)
- print categories[None].manpage_output()
-
- for c in categories:
- if c != None:
- print categories[c].manpage_output()
-
- print_file_contents("environment")- print_file_contents("footer")-
-def wiki_output(dir):
+def wiki_output(targets, template):
read_wikipages()
- process_files(dir)
- print categories[None].wiki_output()
+ for t in targets:
+ print t.wiki_output()
- for c in categories:
- if c != None:
- print categories[c].wiki_output()
+def plaintext_output(targets, template_file):
-def plaintext_output(dir):
- process_files(dir)
+ content = ""
- print "== Command line parameters =="
- print "This is a list of the command line parameters supported by "
- print "Chocolate Doom. A number of additional parameters are supported "
- print "in addition to those present in Vanilla Doom. "
+ for t in targets:
+ content += t.plaintext_output() + "\n"
- print categories[None].plaintext_output()
+ print_template(template_file, content)
- for c in categories:
- if c != None:
- print categories[c].plaintext_output()
-
def usage():
- print "Usage: %s [-V] ( -m | -w | -p ) <directory>" % sys.argv[0]
+ print "Usage: %s [-V] [-c filename ]( -m | -w | -p ) <directory>" \
+ % sys.argv[0]
+ print " -c : Provide documentation for the specified configuration file"
print " -m : Manpage output"
print " -w : Wikitext output"
print " -p : Plaintext output"
@@ -365,22 +431,48 @@
# Parse command line
-opts, args = getopt.getopt(sys.argv[1:], "mwpV")
+opts, args = getopt.getopt(sys.argv[1:], "m:wp:c:V")
output_function = None
+template = None
+doc_config_file = None
for opt in opts:
if opt[0] == "-m":
output_function = manpage_output
+ template = opt[1]
elif opt[0] == "-w":
output_function = wiki_output
elif opt[0] == "-p":
output_function = plaintext_output
+ template = opt[1]
elif opt[0] == "-V":
show_vanilla_options = False
+ elif opt[0] == "-c":
+ doc_config_file = opt[1]
if output_function == None or len(args) != 1:
usage()
else:
- output_function(args[0])
+
+ # Process specified files
+
+ process_files(args[0])
+
+ # Build a list of things to document
+
+ documentation_targets = []
+
+ if doc_config_file:
+ documentation_targets.append(config_files[doc_config_file])
+ else:
+ documentation_targets.append(categories[None])
+
+ for c in categories:
+ if c != None:
+ documentation_targets.append(categories[c])
+
+ # Generate the output
+
+ output_function(documentation_targets, template)
--- a/man/environment
+++ /dev/null
@@ -1,17 +1,0 @@
-.SH ENVIRONMENT
-This section describes environment variables that control Chocolate Doom's
-behavior.
-.TP
-\fBDOOMWADDIR\fR, \fBDOOMWADPATH\fR
-These environment variables provide paths to search for Doom .WAD files when
-looking for a game IWAD file or a PWAD file specified with the '-file' option.
-\fBDOOMWADDIR\fR specifies a single path in which to look for WAD files,
-while \fBDOOMWWADDIR\fR specifies a colon-separated list of paths to search.
-.TP
-\fBPCSOUND_DRIVER\fR
-When running in PC speaker sound effect mode, this environment variable
-specifies a PC speaker driver to use for sound effect playback. Valid
-options are "Linux" for the Linux console mode driver, "BSD" for the
-NetBSD/OpenBSD PC speaker driver, and "SDL" for SDL-based emulated PC speaker
-playback (using the digital output).
-
--- /dev/null
+++ b/man/extra.cfg.template
@@ -1,0 +1,30 @@
+.TH chocolate-doom.cfg 5
+.SH NAME
+chocolate-doom.cfg \- Chocolate Doom configuration file
+.SH DESCRIPTION
+.PP
+\fIchocolate-doom.cfg\fR
+is a configuration file for \fBchocolate-doom\fR(6). This file acts
+as an auxiliary configuration file; the main configuration options
+are stored in \fBdefault.cfg\fR, which contains the same configuration
+options as Vanilla Doom (for compatibility). \fIchocolate-doom.cfg\fR
+contains configuration options that are specific to Chocolate Doom
+only.
+.PP
+\fIchocolate-doom.cfg\fR is normally stored in the user's home directory,
+as \fI~/.chocolate-doom/chocolate-doom.cfg\fR.
+.PP
+The \fBchocolate-setup\fR(6) tool provides a simple to use front-end
+for editing \fIchocolate-doom.cfg\fR.
+.SH FILE FORMAT
+.PP
+The file format is the same as that used for \fBdefault.cfg\fR(5).
+.br
+
+@content
+
+.SH SEE ALSO
+\fBchocolate-doom\fR(6),
+\fBdefault.cfg\fR(5),
+\fBchocolate-setup\fR(6)
+
--- a/man/footer
+++ /dev/null
@@ -1,8 +1,0 @@
-.\" this section from foot
-.SH AUTHOR
-Chocolate Doom is written and maintained by Simon Howard. It is based on
-the LinuxDoom source code, released by Id Software.
-.SH COPYRIGHT
-Copyright \(co id Software Inc.
-Copyright \(co 2005-8 Simon Howard.
-
--- a/man/header
+++ /dev/null
@@ -1,12 +1,0 @@
-.\" 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
--- /dev/null
+++ b/man/manpage.template
@@ -1,0 +1,38 @@
+.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
+
+@content
+
+.SH ENVIRONMENT
+This section describes environment variables that control Chocolate Doom's
+behavior.
+.TP
+\fBDOOMWADDIR\fR, \fBDOOMWADPATH\fR
+These environment variables provide paths to search for Doom .WAD files when
+looking for a game IWAD file or a PWAD file specified with the '-file' option.
+\fBDOOMWADDIR\fR specifies a single path in which to look for WAD files,
+while \fBDOOMWWADDIR\fR specifies a colon-separated list of paths to search.
+.TP
+\fBPCSOUND_DRIVER\fR
+When running in PC speaker sound effect mode, this environment variable
+specifies a PC speaker driver to use for sound effect playback. Valid
+options are "Linux" for the Linux console mode driver, "BSD" for the
+NetBSD/OpenBSD PC speaker driver, and "SDL" for SDL-based emulated PC speaker
+playback (using the digital output).
+
+.SH AUTHOR
+Chocolate Doom is written and maintained by Simon Howard. It is based on
+the LinuxDoom source code, released by Id Software.
+.SH COPYRIGHT
+Copyright \(co id Software Inc.
+Copyright \(co 2005-8 Simon Howard.
+
--- a/src/m_misc.c
+++ b/src/m_misc.c
@@ -359,6 +359,8 @@
#define CONFIG_VARIABLE_STRING(name, variable) \
{ #name, &variable, DEFAULT_STRING, 0, 0 }+//! @begin_config_file default.cfg
+
static default_t doom_defaults_list[] =
{//!
@@ -649,6 +651,8 @@
arrlen(doom_defaults_list),
NULL,
};
+
+//! @begin_config_file chocolate-doom.cfg
static default_t extra_defaults_list[] =
{