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.

7 files changed, 58 insertions, 4 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index 32f275ea..f93e8ede 100644
--- 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        \
diff --git a/man/doom.template b/man/doom.template
index b587d153..d478815d 100644
--- a/man/doom.template
+++ b/man/doom.template
@@ -10,6 +10,8 @@ Chocolate Doom is a port of Id Software's 1993 game "Doom" that is designed
 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.
diff --git a/man/environ.man b/man/environ.man
index 171b25dc..ef8de02a 100644
--- 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
diff --git a/man/heretic.template b/man/heretic.template
index e9afa96d..8fe2e73d 100644
--- a/man/heretic.template
+++ b/man/heretic.template
@@ -11,6 +11,8 @@ aims to behave as similar to the original DOS version of Heretic as
 possible.
 .br
 @content
+.SH IWAD SEARCH PATHS
+@include iwad_paths.man
 .SH ENVIRONMENT
 This section describes environment variables that control Chocolate Heretic's
 behavior.
diff --git a/man/hexen.template b/man/hexen.template
index 4c0524a4..f5619ad8 100644
--- a/man/hexen.template
+++ b/man/hexen.template
@@ -11,6 +11,8 @@ aims to behave as similar to the original DOS version of Hexen as
 possible.
 .br
 @content
+.SH IWAD SEARCH PATHS
+@include iwad_paths.man
 .SH ENVIRONMENT
 This section describes environment variables that control Chocolate Hexen's
 behavior.
diff --git a/man/iwad_paths.man b/man/iwad_paths.man
new file mode 100644
index 00000000..98058154
--- /dev/null
+++ b/man/iwad_paths.man
@@ -0,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.
diff --git a/man/strife.template b/man/strife.template
index ddcc12f9..3d5614cf 100644
--- a/man/strife.template
+++ b/man/strife.template
@@ -13,6 +13,8 @@ of the original programmers of the game (see the section HISTORY below).
 
 @content
 
+.SH IWAD SEARCH PATHS
+@include iwad_paths.man
 .SH ENVIRONMENT
 This section describes environment variables that control Chocolate Strife's
 behavior.