ref: b69888222b2a251bab3fa9c1d44668ac8f53c15a
parent: 3e0dc2d65cc5d31dc5ef1348af1681b032ab0a80
parent: 5d629db9beda83bc49730d22d584a4947bd1e5d6
author: Simon Howard <fraggle+github@gmail.com>
date: Sun Sep 16 16:29:52 EDT 2018
Merge pull request #1084 from chungy/win32_html_docs Use pandoc to generate HTML documentation files in win32 packages
--- a/man/.gitignore
+++ b/man/.gitignore
@@ -1,7 +1,11 @@
CMDLINE.doom
+CMDLINE.doom.md
CMDLINE.heretic
+CMDLINE.heretic.md
CMDLINE.hexen
+CMDLINE.hexen.md
CMDLINE.strife
+CMDLINE.strife.md
INSTALL.doom
INSTALL.heretic
INSTALL.hexen
--- /dev/null
+++ b/man/CMDLINE.template.md
@@ -1,0 +1,8 @@
+# Command line parameters
+
+This is a full list of the supported command line parameters. A number of
+additional parameters are supported in addition to those present in the DOS
+version.
+
+@content
+
--- a/man/INSTALL.template
+++ b/man/INSTALL.template
@@ -7,14 +7,13 @@
#elif STRIFE
#define DEFAULT_IWAD strife1.wad
#endif
+# LONG_GAME_NAME installation
-== LONG_GAME_NAME installation ==
-
These are instructions for how to install and set up LONG_GAME_NAME
for play.
#if !PRECOMPILED
-== Building LONG_GAME_NAME ==
+# Building LONG_GAME_NAME
Before you can play LONG_GAME_NAME, you need to compile a binary that
you can run. For compilation, LONG_GAME_NAME requires the following
@@ -30,9 +29,9 @@
Follow the standard instructions for installing an autotools-based
package:
- 1. Run './configure' to initialize the package.
- 2. Run 'make' to compile the package.
- 3. Run 'make install' to install the package.
+ 1. Run `./configure` to initialize the package.
+ 2. Run `make` to compile the package.
+ 3. Run `make install` to install the package.
An automated build script is available that installs the necessary
dependencies and builds the source code automatically. See the build
@@ -43,7 +42,7 @@
information.
#endif
-== Obtaining an IWAD file ==
+# Obtaining an IWAD file
To play, you need an IWAD file. This file contains the game data
(graphics, sounds, etc). The full versions of the games are
@@ -50,28 +49,30 @@
proprietary and need to be bought. The IWAD file has one of the
following names:
+| IWAD | Game |
+| -------------------------- | ------------------------------- |
#if DOOM
- doom1.wad (Shareware Doom)
- doom.wad (Registered / Ultimate Doom)
- doom2.wad (Doom 2)
- tnt.wad (Final Doom: TNT: Evilution)
- plutonia.wad (Final Doom: Plutonia Experiment)
- chex.wad (Chex Quest)
- freedm.wad (FreeDM)
+| doom1.wad | Shareware Doom |
+| doom.wad | Registered / Ultimate Doom |
+| doom2.wad | Doom 2 |
+| tnt.wad | Final Doom: TNT: Evilution |
+| plutonia.wad | Final Doom: Plutonia Experiment |
+| chex.wad | Chex Quest |
+| freedm.wad | FreeDM |
#endif
#if HERETIC
- heretic1.wad (Shareware Heretic)
- heretic.wad (Registered / Commercial Heretic)
+| heretic1.wad | Shareware Heretic |
+| heretic.wad | Registered / Commercial Heretic |
#endif
#if HEXEN
- hexen.wad (Hexen)
+| hexen.wad | Hexen |
#endif
#if STRIFE
- strife1.wad (+voices.wad) (Strife)
+| strife1.wad (+voices.wad) | Strife |
#endif
#if DOOM
-If you don't have a copy of a commercial version, you can download
+If you don’t have a copy of a commercial version, you can download
the shareware version of Doom (extract the file named doom1.wad):
* https://www.doomworld.com/idgames/idstuff/doom/win95/doom95
@@ -92,8 +93,8 @@
The Doom games, along with Heretic and Hexen, are available to buy
for download on Steam (http://www.steampowered.com/), but are only
available for Windows. To find the IWAD files on a Windows system,
-look in the Steam directory (usually within "Program Files"), under
-the "steamapps/common" path.
+look in the Steam directory (usually within “Program Files”), under
+the “steamapps/common” path.
#endif
#endif
@@ -100,10 +101,10 @@
#if DOOM || HERETIC
Older floppy disk versions are harder to deal with. The easiest way
to install from floppies is to run the original installer program
-inside an emulator such as DOSbox (http://www.dosbox.com/).
+inside an emulator such as DOSbox (https://www.dosbox.com/).
As an alternative to using an emulator, it is possible to extract the
files manually. On the install disk(s), you will find several files
-with numbered extensions (eg. "doom_se.1").
+with numbered extensions (eg. “doom_se.1”).
From the command line it is possible to combine these files into a
single large file, using a command similar to the following:
@@ -119,17 +120,17 @@
operating system).
#endif
-== Running the game ==
+# Running the game
#if __MACOSX__
Once you have an IWAD file, you can specify its location within the
-graphical launcher program. Click the "Configure..." button, and then
-click "Set..." for each IWAD to choose its location. From the main
+graphical launcher program. Click the “Configure...” button, and then
+click “Set...” for each IWAD to choose its location. From the main
launcher dialog you can then choose which game you want to play and
-click the "Launch" button to start the game.
+click the “Launch” button to start the game.
If you are an advanced user and like to run Doom from the command
-line, you can use the "Command Prompt..." menu item to open a Terminal
+line, you can use the “Command Prompt...” menu item to open a Terminal
window. The DOOMWADPATH environment variable is preconfigured
to point to the locations of the IWAD files set within the launcher.
You can launch the game with a specific IWAD file by typing, for
@@ -142,9 +143,9 @@
#if _WIN32
* Within Explorer, simply place the IWAD file in the same folder as
- the LONG_GAME_NAME files, and double-click LONG_EXE_NAME.exe.
+ the LONG_GAME_NAME files, and double-click `LONG_EXE_NAME.exe`.
- * Run LONG_GAME_NAME from the command prompt with the '-iwad' command
+ * Run LONG_GAME_NAME from the command prompt with the `-iwad` command
line parameter to specify the IWAD file to use, eg.
LONG_EXE_NAME -iwad c:\games\DEFAULT_IWAD
@@ -157,7 +158,7 @@
of directories to search (similar to the PATH environment
variable).
#else
- * Run LONG_GAME_NAME from the Unix console with the '-iwad' command
+ * Run LONG_GAME_NAME from the Unix console with the `-iwad` command
line parameter to specify the IWAD file to use, eg.
LONG_EXE_NAME -iwad /root/DEFAULT_IWAD
@@ -164,6 +165,7 @@
* Put the file into one of the following directories:
+ $HOME/.local/share/games/doom
/usr/share/games/doom
/usr/local/share/games/doom
@@ -178,7 +180,7 @@
#endif
#if DOOM
-== Playing with Freedoom ==
+# Playing with Freedoom
Freedoom is an open content project to create a Doom engine-based game
that is entirely free software. The website can be found here:
@@ -188,11 +190,12 @@
The main Freedoom IWAD files are not currently compatible with
LONG_GAME_NAME. However, you can play using FreeDM, the
deathmatch spinoff project. If you want to play single player games,
-you'll need to download additional fan-made WAD files to use in
-conjunction with it. Check out the Chocolate Doom wiki's page on
-Freedoom for some suggestions.
+you’ll need to download additional fan-made WAD files to use in
+conjunction with it. Check out the [Chocolate Doom wiki’s page on
+Freedoom](https://www.chocolate-doom.org/wiki/index.php/Freedoom)
+for some suggestions.
-== Playing with Chex Quest ==
+# Playing with Chex Quest
Chex Quest is a game based on Doom with some minor modifications that
was distributed with boxes of Chex cereal in 1997. It is possible to
@@ -199,19 +202,19 @@
play Chex Quest using LONG_GAME_NAME. To do this, the following files
are needed:
- * The IWAD file 'chex.wad', from the Chex Quest CD.
+ * The IWAD file “chex.wad”, from the Chex Quest CD.
- * The dehacked patch 'chex.deh', which can be found here:
+ * The dehacked patch “chex.deh”, which can be found here:
https://www.doomworld.com/idgames/utils/exe_edit/patches/chexdeh
(utils/exe_edit/patches/chexdeh.zip in your nearest /idgames mirror)
-Copy these files into a directory together and use the '-iwad' command
+Copy these files into a directory together and use the `-iwad` command
line parameter to specify the Chex Quest IWAD file:
LONG_EXE_NAME -iwad chex.wad
#endif
-== Installing upgrades ==
+# Installing upgrades
#if DOOM
LONG_GAME_NAME requires a version 1.9 IWAD file. Generally, if you
@@ -227,7 +230,7 @@
LONG_GAME_NAME requires a version 1.2 IWAD file. Generally, if you
install a recent version of Strife you should have a version 1.2 IWAD.
Please note that Strife version 1.3 does not update the IWAD, if your
-version.txt file says "STRIFE(TM) VERSION 1.3", you are still good.
+version.txt file says “STRIFE(TM) VERSION 1.3”, you are still good.
#endif
However, if you are installing from a very old CD version or from
floppy disks, you might find you have an older version.
@@ -234,7 +237,7 @@
The most obvious symptom of an out of date IWAD file is that the game
will exit at the title screen before the demo starts, with the message
-"Demo is from a different game version!". If this happens, your IWAD
+“Demo is from a different game version!”. If this happens, your IWAD
file is out of date and you need to upgrade.
Upgrade patches are available that will update your game to the latest
@@ -241,18 +244,20 @@
version, the following sites have the patches:
#if DOOM
- <http://www.doom2.net/doom2/utils.html>
- <http://www.gamers.org/pub/idgames/idstuff/doom>
- <http://www.gamers.org/pub/idgames/idstuff/doom2>
+ * http://www.doom2.net/doom2/utils.html
+ * http://www.gamers.org/pub/idgames/idstuff/doom
+ * http://www.gamers.org/pub/idgames/idstuff/doom2
#elif HERETIC
- <http://www.gamers.org/pub/idgames/idstuff/heretic>
+ * http://www.gamers.org/pub/idgames/idstuff/heretic
#elif HEXEN
- <http://www.gamers.org/pub/idgames/idstuff/hexen>
+ * http://www.gamers.org/pub/idgames/idstuff/hexen
#elif STRIFE
- <http://www.gamers.org/pub/idgames/roguestuff>
+ * http://www.gamers.org/pub/idgames/roguestuff
#endif
-Please see <http://doomwiki.org/wiki/Game_patch> for more information.
+Please see the
+[Doom Wiki’s page on game patches](https://doomwiki.org/wiki/Game_patch)
+for more information.
#if _WIN32
As the patches are binary patches that run as DOS executables, on
@@ -263,11 +268,11 @@
will need to use a DOS emulator (such as DOSBox) to run them.
#endif
-== Music support ==
+# Music support
LONG_GAME_NAME includes OPL emulation code that accurately reproduces
the way that the in-game music sounded under DOS when using an
-Adlib/Soundblaster card. This is, however, not to everyone's taste.
+Adlib/Soundblaster card. This is, however, not to everyone’s taste.
LONG_GAME_NAME includes a number of different options for better
quality MIDI playback; see the file README.Music for more details of
@@ -278,5 +283,3 @@
before installing SDL2_mixer.
#endif
-# vim: tw=70
-
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -17,12 +17,6 @@
if HAVE_PYTHON
-if HAVE_WINDRES
-
-WIN32=-D_WIN32
-
-endif
-
GENERATED_MAN_PAGES = \
@PROGRAM_PREFIX@doom.6 \
default.cfg.5 \
@@ -52,6 +46,17 @@
hexendocs_DATA = INSTALL.hexen CMDLINE.hexen
strifedocs_DATA = INSTALL.strife CMDLINE.strife
+if HAVE_WINDRES
+
+WIN32=-D_WIN32
+
+doomdocs_DATA += CMDLINE.doom.md
+hereticdocs_DATA += CMDLINE.heretic.md
+hexendocs_DATA += CMDLINE.hexen.md
+strifedocs_DATA += CMDLINE.strife.md
+
+endif
+
CLEANFILES = $(GENERATED_MAN_PAGES) $(SETUP_MAN_PAGES) \
$(doomdocs_DATA) $(hereticdocs_DATA) \
$(hexendocs_DATA) $(strifedocs_DATA)
@@ -78,6 +83,11 @@
-p $(srcdir)/CMDLINE.template \
$(top_srcdir)/src/ $(top_srcdir)/src/doom/ > $@
+CMDLINE.doom.md : CMDLINE.template.md $(top_srcdir)/src $(top_srcdir)/src/doom
+ $(DOCGEN) $(DOCGEN_COMMON_ARGS) \
+ -M $(srcdir)/CMDLINE.template.md \
+ $(top_srcdir)/src/ $(top_srcdir)/src/doom/ > $@
+
CMDLINE.doom.wikitext : $(top_srcdir)/src $(top_srcdir)/src/doom
$(DOCGEN) $(DOCGEN_COMMON_ARGS) \
-w $(top_srcdir)/src/ $(top_srcdir)/src/doom/ > $@
@@ -108,6 +118,11 @@
-p $(srcdir)/CMDLINE.template \
$(top_srcdir)/src/ $(top_srcdir)/src/heretic/ > $@
+CMDLINE.heretic.md : CMDLINE.template.md $(top_srcdir)/src $(top_srcdir)/src/heretic
+ $(DOCGEN) $(DOCGEN_COMMON_ARGS) \
+ -M $(srcdir)/CMDLINE.template.md \
+ $(top_srcdir)/src/ $(top_srcdir)/src/heretic/ > $@
+
INSTALL.heretic: INSTALL.template
$(srcdir)/simplecpp -DHERETIC $(WIN32) \
-DLONG_GAME_NAME="@PACKAGE_SHORTNAME@ Heretic" \
@@ -135,6 +150,11 @@
-p $(srcdir)/CMDLINE.template \
$(top_srcdir)/src/ $(top_srcdir)/src/hexen/ > $@
+CMDLINE.hexen.md : CMDLINE.template.md $(top_srcdir)/src $(top_srcdir)/src/hexen
+ $(DOCGEN) $(DOCGEN_COMMON_ARGS) \
+ -M $(srcdir)/CMDLINE.template.md \
+ $(top_srcdir)/src/ $(top_srcdir)/src/hexen/ > $@
+
INSTALL.hexen: INSTALL.template
$(srcdir)/simplecpp -DHEXEN $(WIN32) \
-DLONG_GAME_NAME="@PACKAGE_SHORTNAME@ Hexen" \
@@ -172,6 +192,11 @@
-p $(srcdir)/CMDLINE.template \
$(top_srcdir)/src/ $(top_srcdir)/src/strife/ > $@
+CMDLINE.strife.md : CMDLINE.template.md $(top_srcdir)/src $(top_srcdir)/src/strife
+ $(DOCGEN) $(DOCGEN_COMMON_ARGS) \
+ -M $(srcdir)/CMDLINE.template.md \
+ $(top_srcdir)/src/ $(top_srcdir)/src/strife/ > $@
+
INSTALL.strife: INSTALL.template
$(srcdir)/simplecpp -DSTRIFE $(WIN32) \
-DLONG_EXE_NAME="@PROGRAM_PREFIX@strife" \
@@ -190,6 +215,7 @@
EXTRA_DIST = $(man_MANS) $(MANPAGE_GEN_FILES) \
wikipages \
CMDLINE.template \
+ CMDLINE.template.md \
INSTALL.template \
simplecpp
--- a/man/docgen
+++ b/man/docgen
@@ -116,6 +116,19 @@
return result
+ def markdown_output(self):
+ result = "## %s\n\n| Parameter | Description |\n| - | - |\n" % self.description
+
+ self.params.sort()
+
+ for p in self.params:
+ if p.should_show():
+ result += p.markdown_output()
+
+ result = result.rstrip() + "\n"
+
+ return result
+
def completion_output(self):
result = ""
@@ -262,6 +275,28 @@
return result
+ def markdown_output(self):
+ if self.args:
+ name = "%s %s" % (self.name, self.args)
+ else:
+ name = "%s" % self.name
+
+ name = name.replace("|", "\\|")+
+ text = self.text
+ if self.platform:
+ text += " (%s only)" % self.platform
+
+ text = text.replace("|", "\\|")+
+ result = "| %s | %s |\n" % (name, text)
+
+ # html escape
+ result = result.replace("<", "<")+ result = result.replace(">", ">")+
+ return result
+
def plaintext_output(self, indent):
# Build the first line, with the argument on
start = " " + self.name
@@ -468,6 +503,14 @@
for t in targets:
stdout(t.wiki_output().encode('UTF-8') + b'\n')+def markdown_output(targets, substs, template_file):
+ content = ""
+
+ for t in targets:
+ content += t.markdown_output() + "\n"
+
+ print_template(template_file, substs, content)
+
def plaintext_output(targets, substs, template_file):
content = ""
@@ -487,7 +530,7 @@
print_template(template_file, substs, content)
def usage():
- print("Usage: %s [-V] [-c tag] [-g game] -n program_name -s package_name [ -z shortname ] ( -m | -w | -p ) <dir>..." \+ print("Usage: %s [-V] [-c tag] [-g game] -n program_name -s package_name [ -z shortname ] ( -M | -m | -w | -p ) <dir>..." \% sys.argv[0])
print(" -c : Provide documentation for the specified configuration file") print(" (matches the given tag name in the source file)")@@ -494,6 +537,7 @@
print(" -s : Package name, e.g. Chocolate Doom (for substitution)") print(" -z : Package short-name, e.g. Chocolate (for substitution)") print(" -n : Program name, e.g. chocolate (for substitution)")+ print(" -M : Markdown output") print(" -m : Manpage output") print(" -w : Wikitext output") print(" -p : Plaintext output")@@ -504,7 +548,7 @@
# Parse command line
-opts, args = getopt.getopt(sys.argv[1:], "n:s:z:m:wp:b:c:g:V")
+opts, args = getopt.getopt(sys.argv[1:], "n:s:z:M:m:wp:b:c:g:V")
output_function = None
template = None
@@ -521,6 +565,9 @@
substs["@PACKAGE_SHORTNAME@"] = opt[1]
if opt[0] == "-m":
output_function = manpage_output
+ template = opt[1]
+ elif opt[0] == "-M":
+ output_function = markdown_output
template = opt[1]
elif opt[0] == "-w":
output_function = wiki_output
--- a/pkg/win32/GNUmakefile
+++ b/pkg/win32/GNUmakefile
@@ -16,7 +16,6 @@
all: $(ZIPS)
$(ZIPS):
- unix2dos --add-bom $</*.txt
zip -j -r $@ $</*
$(DOOM_ZIP): staging-doom hook-doom
@@ -27,12 +26,12 @@
# Special hooks to custom modify files for particular games.
hook-doom: staging-doom
- cp $(TOPLEVEL)/NOT-BUGS.md $</NOT-BUGS.txt
+ -pandoc -f gfm -s -o $</NOT-BUGS.html $(TOPLEVEL)/NOT-BUGS.md
# Chocolate Strife has its own custom README file:
hook-strife: staging-strife
- cp $(TOPLEVEL)/README.Strife.md $</README.txt
+ -pandoc -f gfm -s -o $</README.html $(TOPLEVEL)/README.Strife.md
# Build up a staging dir for a particular game.
@@ -49,11 +48,12 @@
$(STRIP) $@/*.exe $@/*.dll
- for f in $(DOC_FILES); do \
- cp $(TOPLEVEL)/$$f $@/$$(basename $$f .md).txt; \
+ -for f in $(DOC_FILES); do \
+ pandoc -f gfm -o $@/$$(basename $$f .md).html \
+ -s $(TOPLEVEL)/$$f; \
done
- cp $(TOPLEVEL)/man/CMDLINE.$* $@/CMDLINE.txt
- cp $(TOPLEVEL)/man/INSTALL.$* $@/INSTALL.txt
+ -pandoc -f gfm -s -o $@/CMDLINE.html $(TOPLEVEL)/man/CMDLINE.$*.md
+ -pandoc -f gfm -s -o $@/INSTALL.html $(TOPLEVEL)/man/INSTALL.$*
clean:
rm -f $(ZIPS)