PKGBUILDs/aur/chocolate-doom/0013-man-Add-documentation-for-IWAD-search-paths.patch

From 5240ddc977d2f19e969a6683142e325595eec62c Mon Sep 17 00:00:00 2001
From: Simon Howard <fraggle@soulsphere.org>
Date: Sun, 23 Aug 2015 16:12:54 -0400
Subject: [PATCH 13/13] 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.
---
 man/Makefile.am      |  1 +
 man/doom.template    |  2 ++
 man/environ.man      |  5 +----
 man/heretic.template |  2 ++
 man/hexen.template   |  2 ++
 man/iwad_paths.man   | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 man/strife.template  |  2 ++
 7 files changed, 58 insertions(+), 4 deletions(-)
 create mode 100644 man/iwad_paths.man

diff --git a/man/Makefile.am b/man/Makefile.am
index 32f275e..f93e8ed 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 b587d15..d478815 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 171b25d..ef8de02 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 e9afa96..8fe2e73 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 4c0524a..f5619ad 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 0000000..9805815
--- /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 ddcc12f..3d5614c 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.
-- 
2.5.0