Merge branch 'release/3.3.0' into main

devtools/release.py

@@ -23,6 +23,8 @@
 exec(open(os.path.join(DOC_SRC_PATH, "conf.py")).read())
 RELEASE = release
 
+RELEASE_URL = "https://github.com/neogeographica/quakestarter/releases/tag/v" + RELEASE
+
 RELEASE_FOLDER = "release." + str(os.getpid())
 QUAKE_FOLDER = os.path.join(RELEASE_FOLDER, "Quake")
 ENGINE_STAGING_FOLDER = "engine-staging"
@@ -112,6 +114,14 @@ def gen_docs():
         stdout=subprocess.DEVNULL
     )
 
+def gen_version_url():
+    with open(os.path.join(QUAKE_FOLDER, "quakestarter_scripts", "_version_installed.cmd"), 'w', newline='\r\n') as f:
+        f.write("set version_installed=" + RELEASE_URL)
+
+def gen_version_number():
+    with open(os.path.join(QUAKE_FOLDER, "quakestarter_scripts", "_version_installed_number.cmd"), 'w', newline='\r\n') as f:
+        f.write("set version_installed_number=" + RELEASE)
+
 def patch_autoexec():
     autoexec_path = os.path.join(QUAKE_FOLDER, "id1", "autoexec.cfg.example")
     shutil.copy2(autoexec_path, "autoexec.cfg.example.bak")
@@ -139,6 +149,12 @@ def unpatch_autoexec():
     autoexec_path = os.path.join(QUAKE_FOLDER, "id1", "autoexec.cfg.example")
     shutil.move("autoexec.cfg.example.bak", autoexec_path)
 
+def gen_qs_manifest():
+    files = [f + "\r\n" for f in os.listdir(QUAKE_FOLDER) if f != "id1"]
+    files += ["id1\\" + f + "\r\n" for f in os.listdir(os.path.join(QUAKE_FOLDER, "id1"))]
+    with open(os.path.join(QUAKE_FOLDER, "quakestarter_scripts", "internal_qs_manifest.txt"), 'w') as f:
+        f.writelines(files)
+
 def merge_files(source_a_name, source_a_dir, source_b_name, source_b_dir):
     def extracted_files(source_dir):
         source_files = os.listdir(source_dir)
@@ -166,27 +182,43 @@ def extracted_files(source_dir):
         shutil.copy2(f, QUAKE_FOLDER)
     source_a_set = set([os.path.basename(f) for f in source_a_files])
     source_b_set = set([os.path.basename(f) for f in source_b_files])
+    return source_a_set, source_b_set
+
+def gen_user_engine_manifest(source_a_name, source_a_set, source_b_name, source_b_set):
     common_set = source_a_set & source_b_set
     source_a_unique_set = source_a_set - common_set
     source_b_unique_set = source_b_set - common_set
     manifest_lines = [
-        "files unique to {}:\r\n".format(source_a_name),
+        "* Files unique to {}:\r\n".format(source_a_name),
         "\r\n"
     ]
     manifest_lines += [f + "\r\n" for f in source_a_unique_set]
     manifest_lines += [
         "\r\n"
-        "files unique to {}:\r\n".format(source_b_name),
+        "* Files unique to {}:\r\n".format(source_b_name),
         "\r\n"
     ]
     manifest_lines += [f + "\r\n" for f in source_b_unique_set]
     manifest_lines += [
         "\r\n"
-        "files used in both {} and {}:\r\n".format(source_a_name, source_b_name),
+        "* Files used in both {} and {}:\r\n".format(source_a_name, source_b_name),
         "\r\n"
     ]
     manifest_lines += [f + "\r\n" for f in common_set]
-    return manifest_lines
+    with open(os.path.join(QUAKE_FOLDER, "engines_manifest.txt"), 'w') as f:
+        f.writelines(manifest_lines)
+
+def gen_internal_engines_manifest(source_a_set, source_b_set):
+    total_set = source_a_set.union(source_b_set)
+    files = ["engines_manifest.txt\r\n"]
+    files += [f + "\r\n" for f in total_set]
+    with open(os.path.join(QUAKE_FOLDER, "quakestarter_scripts", "internal_engines_manifest.txt"), 'w') as f:
+        f.writelines(files)
+
+def gen_engines_descriptor():
+    engines_descriptor = "vkQuake {} and Ironwail {}".format(VKQ_VERSION, IW_VERSION)
+    with open(os.path.join(QUAKE_FOLDER, "quakestarter_scripts", "engines_descriptor.txt"), 'w', newline='\r\n') as f:
+        f.write(engines_descriptor)
 
 def gen_release():
     try:
@@ -210,6 +242,8 @@ def exclusions_for_copy(dir, contents):
     shutil.copytree(SRC_PATH, QUAKE_FOLDER, ignore=exclusions_for_copy)
     gen_toplevel_readme()
     gen_docs()
+    gen_version_url()
+    gen_version_number()
     sql_timestamp = handle_zip(SQL_URL, SQL_LOCALFILE, QUAKE_FOLDER)
     print("SQL2 version: {}".format(SQL_VERSION))
     print("SQL2 timestamp: {}".format(sql_timestamp))
@@ -221,6 +255,11 @@ def exclusions_for_copy(dir, contents):
     gen_readme(readme_contents, "", "", sql_timestamp, timestamp)
     release_name = "quakestarter-noengine-" + RELEASE
     patch_autoexec()
+    gen_qs_manifest()
+    with open(os.path.join(QUAKE_FOLDER, "quakestarter_scripts", "internal_engines_manifest.txt"), 'w') as f:
+        f.writelines([])
+    with open(os.path.join(QUAKE_FOLDER, "quakestarter_scripts", "engines_descriptor.txt"), 'w') as f:
+        f.writelines([])
     shutil.make_archive(release_name, "zip", root_dir=RELEASE_FOLDER, base_dir=".")
     unpatch_autoexec()
     vkq_timestamp = handle_zip(VKQ_URL, VKQ_LOCALFILE, vkq_staging)
@@ -230,9 +269,10 @@ def exclusions_for_copy(dir, contents):
     print("IW version: {}".format(IW_VERSION))
     print("IW timestamp: {}".format(iw_timestamp))
     gen_readme(readme_contents, vkq_timestamp, iw_timestamp, sql_timestamp, timestamp)
-    manifest_lines = merge_files("vkQuake", vkq_staging, "ironwail", iw_staging)
-    with open(os.path.join(QUAKE_FOLDER, "engines_manifest.txt"), 'w') as f:
-        f.writelines(manifest_lines)
+    source_a_set, source_b_set = merge_files("vkQuake", vkq_staging, "ironwail", iw_staging)
+    gen_user_engine_manifest("vkQuake", source_a_set, "ironwail", source_b_set)
+    gen_internal_engines_manifest(source_a_set, source_b_set)
+    gen_engines_descriptor()
     release_name = "quakestarter-" + RELEASE
     shutil.make_archive(release_name, "zip", root_dir=RELEASE_FOLDER, base_dir=".")
     shutil.rmtree(RELEASE_FOLDER)

docsource/basic/installation.rst

@@ -8,9 +8,9 @@ The top-level "Quake" folder for this package is meant to be usable as the basis
 
 Another option however is to take the folders and files from inside this "Quake" folder and move them into some existing Quake installation that you have. If that's an installation of original Quake files such as you would get from Steam or GOG, this will work fine. (Note that this should be an installation of the original Quake, not the "enhanced" Quake rerelease.)
 
-If the existing Quake installation already contains an older version of Quakestarter, please see the the :doc:`Upgrading Quakestarter<../other_stuff/upgrading_quakestarter>` chapter (under Other Topics).
+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
@@ -70,7 +70,7 @@ Additional content
 
 The remaining choices in the Quakestarter menus can be used to download and play some of the many community-created singleplayer adventures. These choices, and ways to find all the rest of the available Quake singleplayer content, are discussed in the following chapters.
 
-If you're seeking something that was recently released, it might be under "The New Hotness" menu selections. On the other hand if you want to start with the classics then (unsurprisingly) the "Classic" selections would be the place to look. And there's a lot of stuff in between!
+If you're seeking something that was recently released, it might be under "The Latest Greatest" menu selections. On the other hand if you want to start with the classics then (unsurprisingly) the "Classic" selections would be the place to look. And there's a lot of stuff in between!
 
 
 .. _last 1.x release of Quakestarter: https://github.com/neogeographica/quakestarter/releases/tag/v1.10

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.
 
@@ -20,7 +24,7 @@ Once you get to a page that shows a list of addons, each item in the list will h
 
 After that sequence has finished (or if you select an already-installed addon from the menu), Quakestarter will give you options that allow you to launch or uninstall the addon, or return to the previous menu. These options should be pretty self-explanatory, but they're covered in more detail in the :doc:`Running With Quakestarter<../maps_and_mods/running_with_quakestarter>` chapter.
 
-**Note:** If you use Shift+Enter to submit your choice, rather than just Enter, then Quakestarter will open the Quaddicted review page for that choice rather than going into the usual install/manage/launch process. If you do this, keep Shift pressed down until the web page opens. (This will happen quickly, so don't sit around forever jamming on that Shift key if something goes wrong.) The web page will be opened with whatever web browser is registered with Windows as the default.
+**Note:** If you use Shift+Enter to submit your choice, rather than just Enter, then Quakestarter will open the Quaddicted review page for that choice rather than going into the usual install/manage/launch process -- or in the Latest Greatest menu, it may show some other webpage if the release is not on Quaddicted yet. If you do this, keep Shift pressed down until the web page opens. (This will happen quickly, so don't sit around forever jamming on that Shift key if something goes wrong.) The web page will be opened with whatever web browser is registered with Windows as the default.
 
 Using Quakestarter is the easiest way to correctly launch these addons, but it can only run the same addons that it knows how to install. Once you branch out into playing other stuff, you'll need to use Simple Quake Launcher 2 or other methods.
 

docsource/conf.py

@@ -59,7 +59,7 @@
 # built documents.
 #
 # The full version, including any pre-release tag.
-release = '3.2.0'
+release = '3.3.0'
 # And without that tag.
 version = release.split('-')[0]
 

docsource/maps_and_mods/explore_more.rst

@@ -4,21 +4,16 @@ Explore More
 Quake Injector
 --------------
 
-`Quake Injector`_ is worth a look when you're ready to really dig into Quake addons. It has a bit of a learning curve, but it runs on any OS (as a Java app) and it understands how to install and launch every bit of content from Quaddicted.
+`Quake Injector`_ is worth a look when you're ready to really dig into Quake addons. It runs on any OS and it understands how to install and launch almost every bit of content from Quaddicted.
 
 Quake Injector will *not* automatically apply the patches/fixes that Quakestarter does. The best way to find out what patches might be available for a release is to check out its individual page linked from `the Quaddicted reviews`_... see if the description in the upper right has an "additional files" section, and also maybe check the user comments as well. If there are available patches that you need (usually there won't be any), then you will have to manually download/extract/install those files into the mod folder.
 
 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.
 
-As a final note, a couple of projects exist that aim to provide Quake Injector (or a Quake-Injector-alike interface) as an executable that doesn't require Java. I haven't personally tried either of these yet but FYI...
-
-* `a standalone Quake Injector build`_
-* `a reimplementation of Quake Injector using Qt`_
-
 
 DIY
 ---
@@ -38,8 +33,6 @@ If you want more discussion about running Quake addons, see this relevant `Steam
 
 .. _Quake Injector: https://www.quaddicted.com/tools/quake_injector
 .. _the Quaddicted reviews: https://www.quaddicted.com/reviews/
-.. _a standalone Quake Injector build: https://github.com/hrehfeld/QuakeInjector/releases/tag/alpha04-gradle
-.. _a reimplementation of Quake Injector using Qt: https://sourceforge.net/projects/quake-injector-qt/
 .. _Quaddicted: https://www.quaddicted.com/reviews/
 .. _Slipgate Sightseer: https://www.slipseer.com/
 .. _the func_msgboard forum: http://www.celephais.net/board/forum.php