Move installation docs to a separate document and expand

docs/Installing.rst

@@ -0,0 +1,132 @@
+.. _installing:
+
+=================
+Installing DFHack
+=================
+
+.. contents::
+    :local:
+
+
+Requirements
+============
+
+DFHack supports Windows, Linux, and macOS, and both 64-bit and 32-bit builds
+of Dwarf Fortress.
+
+.. _installing-df-version:
+
+DFHack releases generally only support the version of Dwarf Fortress that they
+are named after. For example, DFHack 0.40.24-r5 only supported DF 0.40.24.
+DFHack releases *never* support newer versions of DF, because DFHack requires
+data about DF that is only possible to obtain after DF has been released.
+Occasionally, DFHack releases will be able to maintain support for older
+versions of DF - for example, DFHack 0.34.11-r5 supported both DF 0.34.11 and
+0.34.10. For maximum stability, you should usually use the latest versions of
+both DF and DFHack.
+
+Windows
+-------
+
+* DFHack only supports the SDL version of Dwarf Fortress. The "legacy" version
+  will *not* work with DFHack (the "small" SDL version is acceptable, however).
+* Windows XP and older are *not* supported, due in part to a
+  `Visual C++ 2015 bug <https://stackoverflow.com/questions/32452777/visual-c-2015-express-stat-not-working-on-windows-xp>`_
+
+The Windows build of DFHack should work under Wine on other operating systems,
+although this is not tested very often. It is recommended to use the native
+build for your operating system instead.
+
+.. _installing-reqs-linux:
+
+Linux
+-----
+
+Generally, DFHack should work on any modern Linux distribution. There are
+multiple release binaries provided - as of DFHack 0.47.04-r1, there are built
+with GCC 7 and GCC 4.8 (as indicated by the ``gcc`` component of their
+filenames). Using the newest build that works on your system is recommended.
+The GCC 4.8 build is built on Ubuntu 14.04 and targets an older glibc, so it
+should work on older distributions.
+
+In the event that none of the provided binaries work on your distribution,
+you may need to `compile DFHack from source <compile>`.
+
+macOS
+-----
+
+OS X 10.6.8 or later is required.
+
+
+.. _downloading:
+
+Downloading DFHack
+==================
+
+Stable builds of DFHack are available on `GitHub <https://github.com/dfhack/dfhack/releases>`_.
+GitHub has been known to change their layout periodically, but as of July 2020,
+downloads are available at the bottom of the release notes for each release, under a section
+named "Assets" (which you may have to expand). The name of the file indicates
+which DF version, platform, and architecture the build supports - the platform
+and architecture (64-bit or 32-bit) **must** match your build of DF. The DF
+version should also match your DF version - see `above <installing-df-version>`
+for details. For example:
+
+* ``dfhack-0.47.04-r1-Windows-64bit.zip`` supports 64-bit DF on Windows
+* ``dfhack-0.47.04-r1-Linux-32bit-gcc-7.tar.bz2`` supports 32-bit DF on Linux
+  (see `installing-reqs-linux` for details on the GCC version indicator)
+
+The `DFHack website <https://dfhack.org/builds>`_ also provides links to
+unstable builds. These files have a different naming scheme, but the same
+restrictions apply (e.g. a file named ``Windows64`` is for 64-bit Windows DF).
+
+.. warning::
+
+    Do *not* download the source code from GitHub, either from the releases page
+    or by clicking "Download ZIP" on the repo homepage. This will give you an
+    incomplete copy of the DFHack source code, which will not work as-is. (If
+    you want to compile DFHack instead of using a pre-built release, see
+    `compile` for instructions.)
+
+Installing DFHack
+=================
+
+When you `download DFHack <downloading>`, you will end up with a release archive
+(a ``.zip`` file on Windows, or a ``.tar.bz2`` file on other platforms). Your
+operating system should have built-in utilities capable of extracting files from
+these archives.
+
+The release archives contain several files and folders, including a ``hack``
+folder, a ``dfhack-config`` folder, and a ``dfhack.init-example`` file. All
+files from the DFHack archive need to be copied into the root DF folder, which
+should already include a ``data`` folder and a ``raw`` folder, among other
+things. Some packs and other redistributions of Dwarf Fortress may place DF in
+another folder, so ensure that the ``hack`` folder ends up next to the ``data``
+folder.
+
+.. note::
+
+    On Windows, installing DFHack will overwrite ``SDL.dll``. This is
+    intentional and necessary for DFHack to work, so be sure to choose to
+    overwrite ``SDL.dll`` if prompted. (If you are not prompted, you may be
+    installing DFHack in the wrong place.)
+
+
+Uninstalling DFHack
+===================
+
+Uninstalling DFHack essentially involves reversing what you did to install
+DFHack. On Windows, replace ``SDL.dll`` with ``SDLreal.dll`` first. Then, you
+can remove any files that were part of the DFHack archive. DFHack does not
+currently maintain a list of these files, so if you want to completely remove
+them, you should consult the DFHack archive that you installed for a full list.
+Generally, any files left behind should not negatively affect DF.
+
+Pre-packaged DFHack installations
+=================================
+
+There are :wiki:`several packs available <Utility:Lazy_Newb_Pack>` that include
+DF, DFHack, and other utilities. If you are new to Dwarf Fortress and DFHack,
+these may be easier to set up. Note that these packs are not maintained by the
+DFHack team and vary in their release schedules and contents. Some may make
+significant configuration changes, and some may not include DFHack at all.

docs/Introduction.rst

@@ -35,47 +35,19 @@ allows easier development of new tools.  As an open-source project under
   :local:
 
 
-.. _installing:
-
-Installing DFHack
-=================
-DFHack is available for the SDL version of Dwarf Fortress on Windows,
-any modern Linux distribution, and Mac OS X (10.6.8 and later).
-It is possible to use Windows DF+DFHack under Wine on Linux or OS X.
-
-Most releases only support the version of DF mentioned in their title - for
-example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases
-support earlier DF versions as well.  Wherever possible, use the latest version
-of DFHack built for the target version of DF.
-
-Installing DFhack involves copying files from a release archive
-into your DF folder, so that:
-
-* On Windows, ``SDL.dll`` is replaced
-* On Linux or OS X, the ``dfhack`` script is placed in the same folder as the ``df`` script
-
-Uninstalling is basically the same, in reverse:
-
-* On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files.
-* On Linux or OS X, remove the DFHack files.
-
-New players may wish to :wiki:`get a pack <Utility:Lazy_Newb_Pack>`
-with DFHack preinstalled.
-
-
 Getting started
 ===============
-DFHack basically extends DF with something similar to the
+See `installing` for details on installing DFHack.
-console found in many PC games.
 
-If DFHack is installed correctly, it will automatically pop up a console
+Once DFHack is installed, it extends DF with a console that can be used to run
-window once DF is started as usual on Windows. Linux and Mac OS X require
+commands. On Windows, this console will open automatically when DF is started.
-running the dfhack script from the terminal, and will use that terminal for
+On Linux and macOS, you will need to run the ``dfhack`` script from a terminal
-the console.
+(instead of the ``df`` script included with DF), and that terminal will be
+used by the DFHack console.
 
-* Basic interaction with dfhack involves entering commands into the console.
+* Basic interaction with DFHack involves entering commands into the console. To
-  To learn what commands are available, you can keep reading this documentation
+  learn what commands are available, you can keep reading this documentation or
-  or skip ahead and use the `ls` and `help` commands.
+  skip ahead and use the `ls` and `help` commands.
 
 * Another way to interact with DFHack is to set in-game `keybindings <keybinding>`
   for certain commands.  Many of the newer and user-friendly tools are designed

index.rst

@@ -27,6 +27,7 @@ User Manual
    :maxdepth: 2
 
    /docs/Introduction
+   /docs/Installing
    /docs/Core
    /docs/Plugins
    /docs/Scripts