docs work

docsource/basic/installation.rst

@@ -10,7 +10,7 @@ Another option however is to take the folders and files from inside this "Quake"
 
 If the existing Quake installation already contains an older version of Quakestarter, please see the the :doc:`Updating Quakestarter<../other_stuff/upgrading_quakestarter>` chapter (under Other Topics).
 
-If you are moving these items into some other already-customized Quake installation that contains a modern Quake engine, then you might want to consider using the "noengine" version of this bundle if you aren't already doing that. Otherwise the engine files bundled in this package can overwrite and perhaps conflict with existing files in your Quake directory. One thing to note is that the "engines_manifest.txt" file lists all of the vkQuake and Ironwail files in this package, which is helpful if you need to discard them. (If you don't have "engines_manifest.txt", then you are using the "noengine" bundle already.)
+If you are moving these items into some other already-customized Quake installation that contains a modern Quake engine, then you might want to consider using the "noengine" version of this bundle if you aren't already doing that. Otherwise the engine files bundled in this package can overwrite and perhaps conflict with existing files in your Quake directory. In this particular situation you definitely want to read the next section below about Quake engines!
 
 
 Quake engine

docsource/basic/running.rst

@@ -6,7 +6,11 @@ Launching with Quakestarter
 
 Quakestarter is meant to help you get your Quake installation set up and then to manage and play various addons.
 
-Other than the "Basic setup" section of the main menu (whose options were already described in :doc:`Installation<installation>` and :doc:`Configuration<configuration>`), the rest of the choices in the main Quakestarter menu will take you to pages where you can choose to install and play these addons. There are two other main sections:
+Other than the "Basic setup" section of the main menu (whose options were already described in :doc:`Installation<installation>` and :doc:`Configuration<configuration>`), the rest of the choices in the main Quakestarter menu will take you to pages where you can choose to install and play these addons. There are three other main sections:
+
+  * In "The Latest Greatest" list, you'll see a subjective selection of the buzz-iest releases of the past six months. (Depending on the rating that a release has accumulated so far, it may also appear in one of the other sections below.)
+
+|br|
 
   * Each choice in "Additional episodes/hubs" leads to a list of good-sized map collections that include a starting map, which either leads you into a linear sequence of other maps or else acts as a hub from which you can explore the other maps of the addon in any order.
 

docsource/maps_and_mods/explore_more.rst

@@ -10,7 +10,7 @@ Quake Injector will *not* automatically apply the patches/fixes that Quakestarte
 
 Note that Quake Injector likes to keep around the zipfiles that it downloads, even if you uninstall a mod, until you explicitly delete the zipfile. If you're going to be using both Quakestarter and Quake Injector then you may want to configure them to share the same downloads folder.
 
-The downloads location for Quake Injector is configured in the "Engine Configuration" dialog. The downloads location for Quakestarter is described in the :doc:`Advanced Configuration<../other_stuff/advanced_quakestarter_cfg>` chapter (under Other Topics). You can change one or the other of these locations so that they both point to the same folder. If you do this, you'll probably also want to configure Quakestarter to leave zipfiles in that folder and *not* delete them after they are installed, to match the behavior of Quake Injector.
+The downloads location for Quake Injector is configured in its "Engine Configuration" dialog. The downloads location for Quakestarter is described in the :doc:`Advanced Configuration<../other_stuff/advanced_quakestarter_cfg>` chapter (under Other Topics). You can change one or the other of these locations so that they both point to the same folder. If you do this, you'll probably also want to configure Quakestarter to leave zipfiles in that folder and *not* delete them after they are installed, to match the behavior of Quake Injector.
 
 One thing to look out for though is that Quakestarter doesn't work exactly the same as Quake Injector when it comes to choosing the name for a mod folder. Quakestarter will always use the name of the zipfile to determine the name of the folder, while Quake Injector may have other ideas. So to avoid confusion and wasted disk space on duplicate stuff, it's best to eventually settle on using only one of these install methods.
 

docsource/other_stuff/advanced_quakestarter_cfg.rst

@@ -18,41 +18,83 @@ Let's say you would rather not do that, so that you can quickly re-install previ
 
 You should always handle any preferences like this through your own "_quakestarter_cfg.cmd" file, *not* by modifying the "_quakestarter_cfg_defaults.cmd" file. That way, your preferences won't get overwritten when you take in the files for some future release of Quakestarter.
 
-The "_quakestarter_cfg_defaults.cmd" file describes these settings in detail, so most of them don't need extra description here. We'll cover a couple of them below though.
+The "_quakestarter_cfg_defaults.cmd" file describes these settings in detail, so most of them don't need extra description here.
 
 
-Engine choice
--------------
+Download behavior
+-----------------
 
-If you want Quakestarter to launch a particular Quake engine of your choice -- other than the options of vkQuake and Ironwail which are usually bundled with Quakestarter -- then the files for that Quake engine need to be placed in the Quake folder along with Quakestarter. It's easiest to do this if you're using a "noengine" installation of Quakestarter, to start from a blank slate without vkQuake/Ironwail getting in the way, but we'll discuss various options here.
+Quakestarter will use "curl.exe" to download zipfiles, if that utility is in a directory included in your Windows PATH environment variable. This will be the case in current versions of Windows 10 (or later).
 
-If you're intending to keep multiple Quake engine choices in this same folder, be careful about the files from one engine overwriting the files from another. For Quakespasm-family engines, they use the same library files which are often either identical among the various engine releases or differing only by minor version. In that case you can often get away with just keeping the latest version of each such library in the Quake folder, along with the various engine executables. But this is definitely a "power user" situation where you need to be careful about what you are doing (and be aware of what happens to Quake engine files when :doc:`Quakestarter is updated<upgrading_quakestarter>`). Engines that use notably different versions of the same library file cannot be kept in the same folder together.
+If Quakestarter can't find that curl utility, it will use a .Net assembly to do the download instead. This should work fine. One downside though is that this approach will not show a progress bar during the download.
 
-If you're *not* using the "noengine" bundle, and you need to get rid of the vkQuake and Ironwail files before installing some other engine, check "engines_manifest.txt" to see what to delete. If you're in this situation it's recommended to overwrite your current Quakestarter installation with the files from a "noengine" bundle so that Quakestarter knows that vkQuake and Ironwail are gone... that way it won't still try to delete vkQuake/Ironwail files on some future Quakestarter update.
+If you don't have "curl.exe" in one of your PATH directories and you really do want that progress bar -- or if for some reason the .Net assembly isn't working and you want to try using curl instead -- then you could install curl yourself. You can get a perfectly good "curl.exe" from `its website`_. Then you can either place that utility into some directory that is already in your PATH, or edit your PATH value to include the directory where you put curl.
 
-Once you have your desired Quake engine installed into this Quake folder, you can set a new quake_exe value in your "_quakestarter_cfg.cmd" file to indicate the Quake program that should be launched by Quakestarter.
+(How to edit system environment variables like PATH is outside the scope of this chapter, but is well-covered in Google results.)
 
-The easiest way to do this is by using the third item in the main Quakestarter menu. That will give you a selection of executables to choose from, and then Quakestarter will handle making the necessary changes to "_quakestarter_cfg.cmd".
 
-However you can also just manually edit "_quakestarter_cfg.cmd" to make the change yourself, if you want to. One reason you might want to do this is if you need to add some command-line arguments that should always be used whenever launching your Quake program. For example, if you are launching qbism Super8, its default "heapsize" value is quite low and on modern systems there's no downside to always cranking it up, so that more maps will work correctly. So you could choose to specify this in your "_quakestarter_cfg.cmd"::
+.. _its website: https://curl.se/windows/
 
-    set quake_exe=qbismS8.exe -heapsize 256000
 
-Note however that if you use the Quakestarter menu item to change your Quake engine executable, then any extra arguments like this will be discarded.
+Engine choice
+-------------
+
+If you want Quakestarter to launch a particular Quake engine of your choice -- other than the options of vkQuake and Ironwail which are usually bundled with Quakestarter -- you can certainly do that! Let's talk about what other Quake engines you might use, describe the easy/common way to install them, and then finally cover a few power-user things.
+
+Which engine
+~~~~~~~~~~~~
 
-In any case, if you do set your own quake_exe (through the menu or manually) then the following things are *not* always guaranteed:
+The :doc:`Quake Engines<quake_engines>` chapter talks a bit about the variety of Quake-playing programs out there. vkQuake and Ironwail are great general-purpose singleplayer Quake engines, but they might not work on your computer for some reason. Or some other engine may have that one special feature that makes it a must-have for you.
+
+You can use other Quake engines through Quakestarter, but keep in mind that for other Quake engines the following things are *not* always guaranteed:
 
 * that your choice of Quake engine will be able to properly run every selection from the Quakestarter menus
 * that your choice of Quake engine will be able to play soundtrack files
 * that all the settings in the example autoexec.cfg will work for your choice of Quake engine, or have the indicated defaults
 * that existing savegames will work for your choice of Quake engine
 
-vkQuake and Ironwail are safe engine choices, and Quakespasm-Spiked usually is too. The original Quakespasm engine is also widely compatible, although since the original Quakespasm lacks multigame support (see below) there will be a small number of Quakestarter items that it cannot launch.
+vkQuake and Ironwail are safe engine choices, and Quakespasm-Spiked usually is too. The original Quakespasm engine is also widely compatible, although since the original Quakespasm lacks multigame support (:ref:`see below<other_stuff/advanced_quakestarter_cfg:multigame support>`) there will be a small number of Quakestarter items that Quakespasm cannot launch.
 
 Beyond those choices, it's more on your shoulders to look into compatibility issues and be aware that something might go wrong. Even some Quake engine that is a perfectly fine piece of software engineering may have troubles running a particular map release if the map was never tested against that engine, and FWIW most releases are tested against a Quakespasm-family engine. A map may even malfunction in ways that are not immediately apparent if you haven't played it before (e.g. missing monsters, lighting errors).
 
 That said, there are many players who are perfectly happy with their preference for a specialty engine like FTE or DarkPlaces, willing to do a bit of troubleshooting if necessary in order to benefit from unique features that those engines provide. The only inarguable "bad choice" for a Quake engine, when it comes to the purpose of playing custom addons, would be a multiplayer-focused engine like ezQuake.
 
+Installing an engine - easy mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to use some other Quake engine, then the files that make up that engine need to be placed in the Quake folder along with Quakestarter.
+
+If you're interested in doing this, it's highly recommended to start with a "noengine" installation of Quakestarter. That way you won't have to worry about dealing with the vkQuake/Ironwail files from the normal Quakestarter bundle, and you also won't be in danger of a Quakestarter update doing anything unexpected to the files of your own Quake engine of choice.
+
+This "easy mode" section will assume that you are working with a "noengine" Quakestarter installation.
+
+If you're intending to manually place multiple Quake engine choices into this Quake folder, be careful about the files from one engine overwriting the files from another. For Quakespasm-family engines, they use the same library files which are often either identical among the various engine releases or differing only by minor version. In that case you can often get away with just keeping the latest version of each such library file in the Quake folder, along with the various engine executables. But this is definitely a situation where you need to be careful about what you are doing. Engines that use notably different versions of the same library file cannot be kept in the same folder together.
+
+Once you have your desired Quake engine(s) installed into this Quake folder, you can set a new quake_exe value in your "_quakestarter_cfg.cmd" file to indicate the Quake program that should be launched by Quakestarter.
+
+The easiest way to do this is by using the third item in the main Quakestarter menu. That will give you a selection of executables to choose from, and then Quakestarter will handle making the necessary changes to "_quakestarter_cfg.cmd" to honor your choice.
+
+However you can also just manually edit "_quakestarter_cfg.cmd" to make the change yourself, if you want to. One reason you might want to do this is if you need to add some command-line arguments that should always be used whenever launching your Quake program. For example, if you are launching qbism Super8, its default "heapsize" value is quite low and on modern systems there's no downside to always cranking it up, so that more maps will work correctly. So you could choose to specify this in your "_quakestarter_cfg.cmd"::
+
+    set quake_exe=qbismS8.exe -heapsize 256000
+
+**Note:** If you use the Quakestarter menu item to change your Quake engine executable, then any extra arguments like those will be discarded.
+
+Installing an engine - hard mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's say you *don't* have a "noengine" installation, but you still want to install some other Quake engines.
+
+If you are OK with transforming your current Quakestarter installation into a "noengine" form, there's a couple of ways to do that. One way to do this is to get the "noengine" bundle for the same version of Quakestarter and unzip it over top of your current Quakestarter files. Another way is to use Quakestarter's update process to install a "noengine" variant of a newer version of Quakestarter, choosing to "detach" or "erase" your current engine files as part of that process. These things are described in the chapter :doc:`Updating Quakestarter<upgrading_quakestarter>`. Once you've achieved a "noengine" setup, you can go back to the "easy mode" process described above.
+
+But OK, maybe you want to keep the vkQuake/Ironwail files and keep them "managed" by Quakestarter, but you also want to add some new engine...
+
+If this new engine is a single executable, that is still pretty easy. You can just drop its exe into the Quake folder and it will now be available as a Quakestarter engine choice.
+
+If this new engine is made up of multiple files, that is trickier. If those files overlap with any of the vkQuake/Ironwail files, they can be affected when Quakestarter updates. And even if they don't currently overlap, conceivably they still might be affected by some future Quakestarter update in which vkQuake/Ironwail use different library files. This is less of a "power user" situation and more of a "don't do this" situation, generally speaking. But... do what you like! Just be aware of what happens to the managed vkQuake/Ironwail files :doc:`when Quakestarter is updated<upgrading_quakestarter>`.
+
+FYI if you have vkQuake/Ironwail files that were installed by Quakestarter, those files will be listed in "engines_manifest.txt".
+
 
 Multigame support
 -----------------
@@ -88,20 +130,3 @@ Finally, you can choose to use the multigame_support value to explicitly define
 That last example would result in the following command line for running the "udob_v1_1" release based on Copper::
 
     my_quake_program.exe -game2 copper_v1_17 -game udob_v1_1 +map start
-
-
-Download behavior
------------------
-
-And finally, a consideration that is outside of that configuration file:
-
-Quakestarter will use "curl.exe" to download zipfiles, if that utility is in a directory included in your Windows PATH environment variable. This will be the case in current versions of Windows 10 (or later).
-
-If Quakestarter can't find that curl utility, it will use a .Net assembly to do the download instead. This should work fine. One downside though is that this approach will not show a progress bar during the download.
-
-If you don't have "curl.exe" in one of your PATH directories and you really do want that progress bar -- or if for some reason the .Net assembly isn't working and you want to try using curl instead -- then you could install curl yourself. You can get a perfectly good "curl.exe" from `its website`_. Then you can either place that utility into some directory that is already in your PATH, or edit your PATH value to include the directory where you put curl.
-
-(How to edit system environment variables like PATH is outside the scope of this chapter, but is well-covered in Google results.)
-
-
-.. _its website: https://curl.se/windows/

docsource/other_stuff/auto_setup_logic.rst

@@ -9,7 +9,7 @@ If you already have an installation of the original Quake game somewhere on the
 Stores cheat-sheet
 ------------------
 
-If you just want to know how Quake installations from various stores can help the Quakestarter auto-setup, here's the bottom line about the files that those store installations provide (as of the last time this doc was updated, April 2022).
+If you just want to know how Quake installations from various stores can help the Quakestarter auto-setup, here's the bottom line about the files that those store installations provide (as of the last time this doc was updated, August 2022).
 
 * The original Quake pak files (game data) are provided by Steam and GOG.