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

9 files changed, 292 insertions, 97 deletions

diff --git a/man/.gitignore b/man/.gitignore
index dd9b296c..b7b7be5f 100644
--- a/man/.gitignore
+++ b/man/.gitignore
@@ -1,3 +1,4 @@
 Makefile.in
 Makefile
 *.6
+*.5
diff --git a/man/CMDLINE.template b/man/CMDLINE.template
new file mode 100644
index 00000000..fee4a3f9
--- /dev/null
+++ b/man/CMDLINE.template
@@ -0,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
+
diff --git a/man/Makefile.am b/man/Makefile.am
index 9d38c92c..d3c90f7e 100644
--- 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
 
diff --git a/man/default.cfg.template b/man/default.cfg.template
new file mode 100644
index 00000000..663103ec
--- /dev/null
+++ b/man/default.cfg.template
@@ -0,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)
+
diff --git a/man/docgen b/man/docgen
index 8870c60c..d59ff71f 100755
--- a/man/docgen
+++ b/man/docgen
@@ -1,7 +1,11 @@
 #!/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>
@@ -13,37 +17,79 @@
 #
 #   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
+
+    return w
+
+class ConfigFile:
+    def __init__(self, filename):
+        self.filename = filename
+        self.variables = []
+
+    def add_variable(self, variable):
+        self.variables.append(variable)
 
-            if p.args:
-                pw += len(p.args)
+    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()
 
-            if pw > w:
-                w = pw
+        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 = []
 
-        return w
+    def add_param(self, param):
+        self.params.append(param)
 
     # Plain text output
 
@@ -52,7 +98,7 @@ class Category:
 
         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 @@ categories = {
 }
 
 wikipages = []
+config_files = {}
 
 # Show options that are in Vanilla Doom? Or only new options?
 
@@ -249,7 +296,29 @@ def add_wiki_links(text):
 
     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 @@ def process_file(file):
         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 @@ def process_file(file):
                 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,72 +357,72 @@ def process_file(file):
             # 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()
 
 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 c in categories:
-        if c != None:
-            print categories[c].wiki_output()
+    for t in targets:
+        print t.wiki_output()
 
-def plaintext_output(dir):
-    process_files(dir)
+def plaintext_output(targets, template_file):
 
-    print "== Command line parameters =="
-    print 
-    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. "
-    print
+    content = ""
 
-    print categories[None].plaintext_output()
+    for t in targets:
+        content += t.plaintext_output() + "\n"
 
-    for c in categories:
-        if c != None:
-            print categories[c].plaintext_output()
+    print_template(template_file, content)
 
 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 @@ def usage():
 
 # 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)
 
diff --git a/man/extra.cfg.template b/man/extra.cfg.template
new file mode 100644
index 00000000..2e0f9301
--- /dev/null
+++ b/man/extra.cfg.template
@@ -0,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)
+
diff --git a/man/footer b/man/footer
deleted file mode 100644
index 9bb3b8b4..00000000
--- a/man/footer
+++ /dev/null
@@ -1,8 +0,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.
-
diff --git a/man/header b/man/header
deleted file mode 100644
index 8917506b..00000000
--- a/man/header
+++ /dev/null
@@ -1,12 +0,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
diff --git a/man/environment b/man/manpage.template
index 47e3d8ed..e2df2b57 100644
--- a/man/environment
+++ b/man/manpage.template
@@ -1,3 +1,17 @@
+.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.
@@ -15,3 +29,10 @@ 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.
+