From 3951c995ebb761de6bfc2f852c5a81eb51ba42f5 Mon Sep 17 00:00:00 2001 From: Simon Howard Date: Mon, 25 Feb 2008 23:50:07 +0000 Subject: 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 --- man/.gitignore | 1 + man/CMDLINE.template | 8 ++ man/Makefile.am | 16 +++- man/default.cfg.template | 53 +++++++++++ man/docgen | 240 ++++++++++++++++++++++++++++++++--------------- man/environment | 17 ---- man/extra.cfg.template | 30 ++++++ man/footer | 8 -- man/header | 12 --- man/manpage.template | 38 ++++++++ 10 files changed, 309 insertions(+), 114 deletions(-) create mode 100644 man/CMDLINE.template create mode 100644 man/default.cfg.template delete mode 100644 man/environment create mode 100644 man/extra.cfg.template delete mode 100644 man/footer delete mode 100644 man/header create mode 100644 man/manpage.template (limited to 'man') 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 @@ -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 ) " % sys.argv[0] + print "Usage: %s [-V] [-c filename ]( -m | -w | -p ) " \ + % 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/environment b/man/environment deleted file mode 100644 index 47e3d8ed..00000000 --- a/man/environment +++ /dev/null @@ -1,17 +0,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). - 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/manpage.template b/man/manpage.template new file mode 100644 index 00000000..e2df2b57 --- /dev/null +++ b/man/manpage.template @@ -0,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. + -- cgit v1.2.3