Cleanup Docs

docs/Coding/index.rst

@@ -0,0 +1,17 @@
+Coding
+******
+
+The Coding category is a set of technical documentation of varying aspects of the Freeciv21 code base. The
+audience of this documentation is software developers seeking information on how the code is setup and
+architected.
+
+
+.. toctree::
+  hacking.rst
+  agents.rst
+  ai.rst
+  attributes.rst
+  delta.rst
+  fcdb.rst
+  scorelog.rst
+  :maxdepth: 1

docs/Developing/bugs.rst → docs/Contributing/bugs.rst

@@ -13,7 +13,6 @@ help you fill in the details.
     :alt: GitHub Issue Templates
 
 
-
 Reporting an Issue
 ==================
 

docs/Contributing/index.rst

@@ -0,0 +1,11 @@
+Contributing
+************
+
+The Contributing category is where documentation editors provide instructions on how to contribute to the
+Freeciv21 project.
+
+.. toctree::
+  bugs.rst
+  msys2.rst
+  style-guide.rst
+  :maxdepth: 1

docs/Developing/msys2.rst → docs/Contributing/msys2.rst

@@ -10,25 +10,25 @@ Setup
 
 This chapter is about creating new msys2 build environment.
 
-1. Install MSYS2 following the documentation on their homepage
+1. Install MSYS2 following the documentation on their homepage.
 
-2. Download: https://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-x86_64-20210228.exe for win64 host
+2. Download: https://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-x86_64-20210228.exe for win64 host.
 
-3. Run it to install MSYS2 on build system
+3. Run it to install MSYS2 on build system.
 
-4. Launch :file:`msys2_shell` to update packages
+4. Launch :file:`msys2_shell` to update packages.
 
 .. code-block:: rst
 
     > pacman -Syu
 
 
-5. Install following packages with :code:`pacman -Su`
+5. Install following packages with :code:`pacman -Su`.
 
 6. Packages needed for building freeciv21. These packages are needed even if you don't plan to make the
 installer, but only build Freeciv21 for local use.
 
-7. Arch independent packages needed for building Freeciv21
+7. Arch independent packages needed for building Freeciv21.
 
 8. Arch independent packages always needed for building Freeciv21. With these packages it's possible to build
 Freeciv21 source tree that has already such generated files present that are created for the release tarball.
@@ -69,23 +69,16 @@ addition to the ones always needed for building Freeciv21.
 * mingw-w64-i686-tolua / mingw-w64-x86_64-tolua
 
 
-13. Arch-specific packages for buildind Qt-client and/or Ruledit (i686 or x86_64, not both)
+13. Arch-specific packages for building the client and/or Ruledit (i686 or x86_64, not both)
 
 * mingw-w64-i686-qt5 / mingw-w64-x86_64-qt5
 * mingq-w64-i686-karchive-qt5 / mingw-w64-x86_64-karchive-qt5
 
 
-14. Arch-specific packages for building sdl2-client (i686 or x86_64, not both)
-
-* mingw-w64-i686-SDL2_image / mingw-w64-x86_64-SDL2_image
-* mingw-w64-i686-SDL2_ttf / mingw-w64-x86_64-SDL2_ttf
-* mingw-w64-i686-SDL2_gfx / mingw-w64-x86_64-SDL2_gfx
-
-
-15. Packages needed for building installer package. These are needed in addition to above ones used in the
+14. Packages needed for building installer package. These are needed in addition to above ones used in the
 building step already.
 
-16. Arch-specific packages needed for building installer package (i686 or x86_64, not both)
+15. Arch-specific packages needed for building Windows installer package (i686 or x86_64, not both)
 
 * mingw-w64-i686-nsis / mingw-w64-x86_64-nsis
 
@@ -100,4 +93,4 @@ environment. The scripts create an x86_64 environment.
 Build
 =====
 
-Now that you have the environment setup. You can follow the steps in :doc:`../General/install`
+Now that you have the environment setup. You can follow the steps in :doc:`../../General/install`

docs/General/index.rst

@@ -1,9 +1,8 @@
 General
 *******
 
-General
-  The General category is a catch-all for content that does not neatly fit into the other three. Things like
-  the FAQ and installation instructions go here.
+The General category is a catch-all for content that does not neatly fit into the other three. Things like
+the FAQ and installation instructions go here.
 
 
 .. toctree::

docs/General/install.rst

@@ -1,5 +1,5 @@
-Linux Compiling and Installing
-******************************
+Compiling and Installing
+************************
 
 General Prerequisites
 =====================
@@ -234,7 +234,7 @@ Windows Notes
 Msys2 is an available environment for compiling Freeciv21. Microsoft Windows Visual C is under development.
 
 Freeciv21 currently supports building and installing using the Msys2 environment. Build instructions for
-Msys2 versions are documented in :doc:`../Developing/msys2`. Alternately you can visit
+Msys2 versions are documented in :doc:`../Contributing/msys2`. Alternately you can visit
 https://github.com/jwrober/freeciv-msys2 for ready made scripts.
 
 Follow the steps starting in configuring_ above.
@@ -245,6 +245,7 @@ Instead of installing, use this command to create the Windows Installer package:
 
   $ cmake --build build --target package
 
+
 When the Ninja command is finished running, you will find an installer in :file:`build/Windows-${arch}`
 
 Documentation Build Notes

docs/General/modpack-installer.rst

@@ -1,11 +1,8 @@
 Using the Modpack Installer Utility
 ***********************************
 
-Installing Modpacks
-===================
-
-The modpack installer is a simple tool to download custom Freeciv21 content called :strong:`modpacks` from 
-the Internet, and automatically install them into the correct location to be used by the Freeciv21 client and 
+The modpack installer is a simple tool to download custom Freeciv21 content called :strong:`modpacks` from
+the Internet, and automatically install them into the correct location to be used by the Freeciv21 client and
 server.
 
 A :strong:`modpack` can consist of one or more of:
@@ -15,30 +12,32 @@ A :strong:`modpack` can consist of one or more of:
 * :strong:`tilesets` for game graphics
 * :strong:`soundsets` or :strong:`musicsets` for sound effects and in-game music
 
-They can be installed using the modpack installer tool :file:`freeciv21-modpack-qt` that comes with the 
-standard installation. There is also a command-line-only tool called :file:`freeciv21-modpack`, which is 
+They can be installed using the modpack installer tool :file:`freeciv21-modpack-qt` that comes with the
+standard installation. There is also a command-line-only tool called :file:`freeciv21-modpack`, which is
 mainly useful for headless game servers.
 
-In standard Freeciv21 builds, when you start the graphical modpack installer, it will show a list of 
-modpacks curated by the Freeciv21 developers and longturn.net community. You can select one and click 
-:guilabel:`Install modpack`; the tool will download the files for the selected modpack, and any other 
+In standard Freeciv21 builds, when you start the graphical modpack installer, it will show a list of
+modpacks curated by the Freeciv21 developers and longturn.net community. You can select one and click
+:guilabel:`Install modpack`; the tool will download the files for the selected modpack, and any other
 modpacks it depends on, and install them ready for the main Freeciv21 programs to use.
 
 .. image:: ../_static/images/gui-elements/modpack-installer.png
     :align: center
     :alt: Freeciv21 Modpack Installer Qt GUI application
 
+
 You can also point the installer at modpacks or lists on other servers:
 
-* If someone has given you an individual modpack URL (ending in :literal:`.json`), you can paste it into the 
-  :guilabel:`Modpack URL` box, and when you click :guilabel:`Install modpack`, the modpack will immediately  
-  downloaded and install. 
+* If someone has given you an individual modpack URL (ending in :literal:`.json`), you can paste it into the
+  :guilabel:`Modpack URL` box, and when you click :guilabel:`Install modpack`, the modpack will immediately
+  downloaded and install.
 
-.. note:: If you have been given a URL ending up :literal:`.modpack` or :literal:`.mpdl`, 
-    that is probably for legacy Freeciv and not Freeciv21.
+.. note:: If you have been given a URL ending up :literal:`.modpack` or :literal:`.mpdl`,
+    that is probably for legacy Freeciv and not Freeciv21. These modpack files are not compatible with
+    Freeciv21.
 
-* If someone has given you a URL for a list of modpacks (also ending in :literal:`.json`) and you want to 
-  browse them with the standard Freeciv21 modpack installer build, you need to start the tool with that URL  
+* If someone has given you a URL for a list of modpacks (also ending in :literal:`.json`) and you want to
+  browse them with the standard Freeciv21 modpack installer build, you need to start the tool with that URL
   on its command line, for instance:
 
 .. code-block:: rst
@@ -48,59 +47,59 @@ You can also point the installer at modpacks or lists on other servers:
 
 .. note:: The capital letter in :literal:`--List`
 
-    The tool has some other command-line options, but most users will not need to use them. Use 
+    The tool has some other command-line options, but most users will not need to use them. Use
     :literal:`--help` for a list of them.
 
 Once you have installed a modpack, how you use it depends on the modpack type:
 
-* Scenarios (maps) should be listed under :guilabel:`Start scenario game` from the client start page, or 
+* Scenarios (maps) should be listed under :guilabel:`Start scenario game` from the client start page, or
   from the game server prompt via :literal:`/list scenarios`.
 
 .. tip:: For network play, scenarios need only be installed on the game server.
 
-* Rulesets should appear on the :guilabel:`Ruleset` drop-down from the client's :guilabel:`Start new game` 
-  page. On the game server, you can load a ruleset with :literal:`/read <name>` or failing that perhaps 
+* Rulesets should appear on the :guilabel:`Ruleset` drop-down from the client's :guilabel:`Start new game`
+  page. On the game server, you can load a ruleset with :literal:`/read <name>` or failing that perhaps
   :literal:`/rulesetdir <name>`.
 
-* Tilesets should appear for selection in the local client options, in the appropriate topology-specific 
+* Tilesets should appear for selection in the local client options, in the appropriate topology-specific
   :guilabel:`Tileset` drop-down under :guilabel:`Graphics`.
 
 .. note:: Tilesets should be installed on the client machine.
 
-* Soundsets and musicsets should appear in the dropdowns on the :guilabel:`Sound` page of the local 
+* Soundsets and musicsets should appear in the dropdowns on the :guilabel:`Sound` page of the local
   client options.
 
-With standard Freeciv21 builds, modpacks get installed into a per-user area, not into the main Freeciv21 
-installation. So you shouldn't need any special permissions to download them, and if you uninstall the 
-Freeciv21 game, any modpacks you downloaded are likely to remain on your system. Conversely, if you delete 
+With standard Freeciv21 builds, modpacks get installed into a per-user area, not into the main Freeciv21
+installation. So you shouldn't need any special permissions to download them, and if you uninstall the
+Freeciv21 game, any modpacks you downloaded are likely to remain on your system. Conversely, if you delete
 downloaded modpacks by hand, the standard rulesets, tilesets, etc. supplied with Freeciv21 won't be touched.
 
-The precise location where files are downloaded to depends on your build and platform. For Unix systems, it 
-is likely to be under the hidden :file:`~/.local/share/freeciv21` directory in your home directory. For 
-Windows based sytems it will be in your user profile directory in a hidden :literal:`AppData` folder, 
-typically, :file:`C:\\Users\\[MyUserName]\\AppData\\Roaming\\Freeciv21` It is likely to be near where the 
+The precise location where files are downloaded to depends on your build and platform. For Unix systems, it
+is likely to be under the hidden :file:`~/.local/share/freeciv21` directory in your home directory. For
+Windows based sytems it will be in your user profile directory in a hidden :literal:`AppData` folder,
+typically, :file:`C:\\Users\\[MyUserName]\\AppData\\Roaming\\Freeciv21` It is likely to be near where the
 Freeciv21 client stores its saved games.
 
-Most modpacks are specific to a particular major version of Freeciv21; for instance, while a 3.0 ruleset or 
-tileset can be used with all Freeciv21 3.0.x releases, it cannot be used as-is with any 3.1.x release. So, 
-most modpacks are installed in a specific directory for the major version, such as 
-:file:`~/.local/share/freeciv21/3.1/` on Unix. 
+Most modpacks are specific to a particular major version of Freeciv21; for instance, while a 3.0 ruleset or
+tileset can be used with all Freeciv21 3.0.x releases, it cannot be used as-is with any 3.1.x release. So,
+most modpacks are installed in a specific directory for the major version, such as
+:file:`~/.local/share/freeciv21/3.1/` on Unix.
 
 .. note:: The modpack installer displays which version it will install for at the top of its window.
 
-An exception to this is scenario maps; scenarios created for one version of Freeciv21 can usually be loaded 
-in later versions, so they are installed in a version-independent location (typically 
+An exception to this is scenario maps; scenarios created for one version of Freeciv21 can usually be loaded
+in later versions, so they are installed in a version-independent location (typically
 :file:`~/.local/share/freeciv21/scenarios/` on Unix).
 
-Once a modpack is installed, there is no uninstall action, and if you remove the files by hand, the 
-installer will still consider the modpack to be installed; the installer maintains its own database 
-(:file:`.control/modpacks.db`) listing which modpack versions are installed, but does not keep track of 
-which files were installed by which modpack. If the database gets out of sync with reality (or is deleted), 
-it's harmless for already installed modpacks and the main Freeciv21 programs (which do not consult the 
+Once a modpack is installed, there is no uninstall action, and if you remove the files by hand, the
+installer will still consider the modpack to be installed; the installer maintains its own database
+(:file:`.control/modpacks.db`) listing which modpack versions are installed, but does not keep track of
+which files were installed by which modpack. If the database gets out of sync with reality (or is deleted),
+it's harmless for already installed modpacks and the main Freeciv21 programs (which do not consult the
 database), but can confuse the modpack installer's dependency tracking later.
 
-Modpacks consist mostly of data files read by the Freeciv21 engine; they do not contain compiled binary code 
-(and are thus platform-independent). Rulesets can contain code in the form of Lua scripts, but this is 
-executed in a sandbox to prevent obvious security exploits. Modpacks are installed to a specific area and 
-cannot overwrite arbitrary files on your system. Nevertheless, you should only install modpacks from sources 
+Modpacks consist mostly of data files read by the Freeciv21 engine; they do not contain compiled binary code
+(and are thus platform-independent). Rulesets can contain code in the form of Lua scripts, but this is
+executed in a sandbox to prevent obvious security exploits. Modpacks are installed to a specific area and
+cannot overwrite arbitrary files on your system. Nevertheless, you should only install modpacks from sources
 you trust.

docs/Modding/Rulesets/actions.rst

@@ -32,7 +32,7 @@ unable to perform the action. The actor unit may also lose a ruleset configurabl
 
 Example:
 
-.. code-block:: rst
+.. code-block:: ini
 
     [actionenabler_veil_the_threat_of_terror]
     action = "Incite City"
@@ -45,7 +45,7 @@ Example:
 
 Another Example:
 
-.. code-block:: rst
+.. code-block:: ini
 
     [actionenabler_go_bind_your_sons_to_exile]
     action = "Incite City"

docs/Modding/Rulesets/nations.rst

@@ -329,7 +329,7 @@ mountains, and deserts. Although this degree of detail is probably unnecessary t
 the system is designed to degrade smoothly so it should work just fine.
 
 .. note::
-  A note on scale: it might be tempting to label London as "code:`!ocean`, i.e. not adjacent to an ocean.
+  A note on scale: it might be tempting to label London as :code:`!ocean`, i.e. not adjacent to an ocean.
   However, on a reasonably-sized Freeciv21 world map, London will be adjacent to the ocean; labeling it
   :code:`!ocean` will tend to give bad results. This is a limitation of the system, and should be taken into
   account when labelling cities.

docs/Modding/Tilesets/graphics.rst

@@ -2,9 +2,9 @@ Tile Specification Files
 ************************
 
 Creating a Freeciv21 Tileset requires a mix of editing plain text :file:`spec` files as well as creating
-graphics files saved in the :file:`.png` image format. When complete, a Tileset editor will have created
-the canvas that Freeciv21 players play upon. Next to :doc:`../Rulesets/index`, creating Tilesets is one of the
-most important aspects of a Freeciv21 game.
+graphics files saved in the :file:`.png` image format. When complete, a Tileset editor will have created the
+canvas that Freeciv21 players play upon. Next to Rulesets, creating Tilesets is one of the most important
+aspects of a Freeciv21 game.
 
 Using Graphics
 ---------------

docs/Modding/index.rst

@@ -1,11 +1,10 @@
 Modding
 *******
 
-Modding
-  The Modding category is an area for documentation editors to provide tips and other details on modifying
-  aspects of Freeciv21 such as Rulesets, Musicsets, Soundsets and Tilesets. All of these areas allow for a
-  large amount of varyability in game play that is not hardcoded in the software. This is one of the
-  strengths of Freeciv21.
+The Modding category is an area for documentation editors to provide tips and other details on modifying
+aspects of Freeciv21 such as Rulesets, Musicsets, Soundsets and Tilesets. All of these areas allow for a
+large amount of varyability in game play that is not hardcoded in the software. This is one of the
+strengths of Freeciv21.
 
 There are five major areas of Modding that are often called "Modpacks" and are written by "Modders". The
 sections below describe these major Modding areas.
@@ -50,7 +49,7 @@ Tilesets
 ========
 
 Tilesets are a collection of :literal:`spec` files that fully define the look and feel of the game map, units,
-buildings, etc. This is effectively the graphics layer of Freeciv21. A tileset a Modder can create a whole new
+buildings, etc. This is effectively the graphics layer of Freeciv21. A tileset Modder can create a whole new
 custom graphics look and feel. The file layout for a tileset can vary depending on how the author wants to
 break out the varying layers. It will always start with a top-level :literal:`.tilespec` file and with a
 directory of the same name will have :literal:`.png` graphics files and associated :literal:`.spec` files to

docs/Modding/scenarios.rst

@@ -1,5 +1,5 @@
-Scenarios
-*********
+Scenarios Overview
+******************
 
 Overview
 ========