ref: 7d51bb2262cec4b754d714e5f54c9a16ddf87117
parent: d1d65f2567d4943e2103414e793b0e445e6365d5
author: Simon Howard <fraggle@soulsphere.org>
date: Sun Aug 23 12:12:54 EDT 2015
man: Add documentation for IWAD search paths. We now search in a bunch of different directories in order to find IWAD files to use to play with, and the logic is a bit complicated. Add some hopefully friendly documentation to explain where people can put their IWAD files to play with. Part of #597.
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,4 +1,5 @@
MANPAGE_GEN_FILES = environ.man \
+ iwad_paths.man \
doom.template \
heretic.template \
hexen.template \
--- a/man/doom.template
+++ b/man/doom.template
@@ -10,6 +10,8 @@
to behave as similar to the original DOS version of Doom as is possible.
.br
@content
+.SH IWAD SEARCH PATHS
+@include iwad_paths.man
.SH ENVIRONMENT
This section describes environment variables that control Chocolate Doom's
behavior.
--- a/man/environ.man
+++ b/man/environ.man
@@ -1,9 +1,6 @@
.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 \fBDOOMWWADPATH\fR specifies a colon-separated list of paths to search.
+See the section, \fBIWAD SEARCH PATHS\fR above.
.TP
\fBPCSOUND_DRIVER\fR
When running in PC speaker sound effect mode, this environment variable
--- a/man/heretic.template
+++ b/man/heretic.template
@@ -11,6 +11,8 @@
possible.
.br
@content
+.SH IWAD SEARCH PATHS
+@include iwad_paths.man
.SH ENVIRONMENT
This section describes environment variables that control Chocolate Heretic's
behavior.
--- a/man/hexen.template
+++ b/man/hexen.template
@@ -11,6 +11,8 @@
possible.
.br
@content
+.SH IWAD SEARCH PATHS
+@include iwad_paths.man
.SH ENVIRONMENT
This section describes environment variables that control Chocolate Hexen's
behavior.
--- /dev/null
+++ b/man/iwad_paths.man
@@ -1,0 +1,48 @@
+To play, an IWAD file is needed. This is a large file containing all of the
+levels, graphics, sound effects, music and other material that make up the
+game. IWAD files are named according to the game; the standard names are:
+.TP
+\fBdoom.wad, doom1.wad, doom2.wad, tnt.wad, plutonia.wad\fR
+Doom, Doom II, Final Doom
+.TP
+\fBheretic.wad, heretic1.wad, hexen.wad, strife1.wad\fR
+Heretic, Hexen and Strife (commercial Doom engine games).
+.TP
+\fBhacx.wad, chex.wad\fR
+Hacx and Chex Quest - more obscure games based on the Doom engine.
+.TP
+\fBfreedm.wad, freedoom1.wad, freedoom2.wad\fR
+The Freedoom open content IWAD files.
+.LP
+The following directory paths are searched in order to find an IWAD:
+.TP
+\fBCurrent working directory\fR
+Any IWAD files found in the current working directory will be used in
+preference to IWADs found in any other directories.
+.TP
+\fBDOOMWADDIR\fR
+This environment variable can be set to contain a path to a single directory
+in which to look for IWAD files. This environment variable is supported by
+most Doom source ports.
+.TP
+\fBDOOMWADPATH\fR
+This environment variable, if set, can contain a colon-separated list of
+directories in which to look for IWAD files, or alternatively full paths to
+specific IWAD files.
+.TP
+\fB$HOME/.local/share/games/doom\fR
+Writeable directory in the user's home directory. The path can be overridden
+using the \fBXDG_DATA_HOME\fR environment variable (see the XDG Base Directory
+Specification).
+.TP
+\fB/usr/local/share/games/doom, /usr/share/games/doom\fR
+System-wide locations that can be accessed by all users. The path
+\fB/usr/share/games/doom\fR is a standard path that is supported by most
+Doom source ports. These paths can be overridden using the \fBXDG_DATA_DIRS\fR
+environment variable (see the XDG Base Directory Specification).
+.LP
+The above can be overridden on a one-time basis by using the \fB\-iwad\fR
+command line parameter to provide the path to an IWAD file to use. This
+parameter can also be used to specify the name of a particular IWAD to use
+from one of the above paths. For example, '\fB-iwad doom.wad\fR' will search
+the above paths for the file \fBdoom.wad\fR to use.
--- a/man/strife.template
+++ b/man/strife.template
@@ -13,6 +13,8 @@
@content
+.SH IWAD SEARCH PATHS
+@include iwad_paths.man
.SH ENVIRONMENT
This section describes environment variables that control Chocolate Strife's
behavior.