Break "Manifests and Game Folders" into two articles.

Also, substantially re-work each of them.

docs/concepts/game-folders.md

@@ -1,81 +1,93 @@
 What is a game folder?
 ----------------------
 
-TODO
+A game folder
+is higan's way of grouping all
+the information and resources required
+to properly emulate a particular game.
+Other emulators group resources related to a game
+by requiring that every file has the base name
+but different file extensions.
+
+For example,
+if another emulator loaded the game `dkc3.sfc`
+it might store the save data in `dkc3.srm`:
+
+```text
++- Super Famicom
+   |
+   +- dkc3.sfc
+   |
+   +- dkc3.srm
+```
+
+higan would create a game folder named `dkc3.sfc`,
+and inside it store the game data as `program.rom`
+and the save data as `save.ram`:
+
+```text
++- Super Famicom
+   |
+   +- dkc3.sfc
+      |
+      +- program.rom
+      |
+      +- save.ram
+```
 
 Why game folders?
 -----------------
 
-A game is more than just
+The traditional files-with-different-extensions system
-the raw data originally encased in a game's ROM chip.
+works well enough when a game only requires
-If a game allows you to save your progress,
+a small number of files,
-that information needs to be stored somewhere.
+because a file extension doesn't offer
-If you use an emulator's [save states](#save-states),
+much room for description.
-those save states need to be stored somewhere.
+Also,
-If you use Game Genie or Pro Action Replay codes,
+since file extensions traditionally describe
-information about what codes exist,
+the format of the file in question,
-what codes are enabled,
+it also means a game can't use
-and what they do
+two or more files in the same format.
-needs to be stored somewhere.
 
-On the technical side,
+Compared to other emulators,
-a physical game cartridge contains a circuit board
+higan tends to use a larger number of files per game.
-that makes the game data available to the console,
+For example,
-and different games used circuit boards that work differently.
+higan's low-level emulation of Super Famicom co-processors
-That circuit-layout information needs to be stored somewhere.
+often requires [separate firmware files][firmware].
-Some games included custom processors
+higan's [MSU-1 support][msu1]
-to do calculations the base console could not do quickly enough
+requires up to 99 audio tracks per game,
-(like the SuperFX chip used in _StarFox_ for the Super Famicom)
+and higan supports up to 133 save-states per game.
-and information about extra chips needs to be stored somewhere.
+Therefore,
-Some of those custom processors require extra data to work
+higan suffers from the limitations of name-based-grouping
-that's not part of the main game data
+more than most.
-(like the DSP chip used in Super Mario Kart for the Super Famicom)
-and that data needs to be stored somewhere too.
 
-higan keeps all this game-related information together
+higan's game folders allow all a game's resources
-in a single place:
+to be given unique, descriptive filenames,
-a game folder in the higan library.
+and to use the file-extension
+that's most appropriate for that file.
+They also allow emulator-specific data
+like save-states and the cheat database
+to be kept separate from the game's actual data,
+by putting it in a sub-folder.
+
+[msu1]: ../guides/import.md#msu-1-games
+[firmware]: ../guides/import.md#games-with-co-processor-firmware
 
 For a more detailed motivation for game folders,
-see [Game Paks on the higan website][gp]
+see [Game Paks on the higan website][gp].
 
 [gp]: https://byuu.org/emulation/higan/game-paks
 
-What is a manifest?
--------------------
-
-TODO
-
-The most important file in a game folder is `manifest.bml`,
-which describes how all the other files should be wired together
-to create a runnable game cartridge.
-However,
-the manifest format has occasionally changed
-as new emulation details were uncovered
-that could not be represented in the old format.
-Therefore,
-icarus [defaults](#the-icarus-settings-dialog)
-to not writing out manifests when it imports games,
-and higan [defaults](#the-configuration-dialog)
-to ignoring manifests that are present.
-Instead,
-when higan loads a game,
-it will ask icarus to generate a temporary manifest in the latest format,
-based on the files present in the game folder
-and how they are likely to go together.
-You can view this temporary manifest
-in [the Manifest Viewer](#the-manifest-viewer).
-
 What's in a game folder?
 ------------------------
 
-As mentioned [above](#why-game-folders),
+As mentioned [above](#what-is-a-game-folder),
 a game folder collects all the information relevant
 to emulating a particular game.
 Not all of the following files
 are relevant to every emulated console,
 or to every game on a given console,
-but they may be relevantunder particular circumstances.
+but they may be present under particular circumstances.
 
 All the files directly in the game folder
 are expected to be useful
@@ -97,7 +109,7 @@ to all emulators that support them:
     from the cartridge's ROM chips.
   - `ines.rom`:
     While other consoles typically include enough hints
-    in `program.rom` for icarus to generate a manifest,
+    in `program.rom` for icarus to guess a working manifest,
     the Famicom does not.
     Famicom games not stored in game folders
     typically include an "iNES header" to store that information,
@@ -117,25 +129,20 @@ to all emulators that support them:
     Games that include a calendar or real-time clock
     will create this file.
   - `*.data.rom`, `*.program.rom`:
-    Files named like this are usually
+    Files named like this are usually [co-processor firmware][firmware].
-    [co-processor firmware](#importing-and-playing-games-with-co-processor-firmware).
   - `msu1.rom`:
-    Holds streamable data for
+    Holds streamable data for [the MSU-1][msu1].
-    [the MSU-1](#importing-and-playing-MSU-1-games).
   - `track-*.pcm`:
-    Holds streamable audio for
+    Holds streamable audio for [the MSU-1][msu1].
-    [the MSU-1](#importing-and-playing-MSU-1-games).
 
 Files that are only useful to higan specifically
 are placed in a `higan` subdirectory:
 
   - `cheats.bml`:
     All information present in
-    [the Cheat Editor](#the-cheat-editor)
+    [the Cheat Editor](../interface/higan-tools.md#the-cheat-editor)
     is stored here.
   - `states/quick/slot-*.bst`:
-    All the save states made to
+    All [Quick States](save-states.md#quick-states) are stored here.
-    [Quick state slots](#quick-states).
   - `states/managed/slot-*.bst`:
-    All the save states made with
+    All [Manager States](save-states.md#manager-states) are stored here.
-    [the State Manager](#the-state-manager).

docs/concepts/manifests.md

@@ -0,0 +1,128 @@
+What is a manifest?
+-------------------
+
+If a [game folder](game-folders.md) is
+the emulation equivalent of
+a physical game cartridge,
+a manifest is like
+the circuit board inside the cartridge:
+it controls how all the other parts of the cartridge
+talk to one another and to the console itself.
+
+If you load a game into higan,
+you can look at the game's manifest
+by opening [the Tools menu](../interface/higan.md#the-tools-menu)
+and choosing [Manifest Viewer](../interface/higan-tools.md#the-manifest-viewer).
+
+Why manifests?
+--------------
+
+Any given console might support
+hundreds or thousands of different games,
+but the vast majority of those games
+use one of a few different circuit boards.
+For most consoles,
+the raw game data provides enough clues
+to guess a circuit board configuration
+that will get the game running,
+but relying on heuristics often leads to problems:
+
+  - Inventing heuristics
+    that correctly guess the configuration
+    for a particular game is very difficult.
+      - If you change the rules,
+        you really need to re-test
+        the console's entire game library
+        to check you haven't broken anything.
+  - Some games accidentally do the wrong thing.
+      - The Mega Drive game *Warrior of Rome II*
+        follows the rule for a European game running at 50fps,
+        when it's really an American game designed for 60fps.
+  - Some games deliberately do the wrong thing.
+      - The Game Boy Advance game *Top Gun - Combat Zones*
+        follows the rule for
+        (several kinds of)
+        save-game storage.
+        If it detects any save-game storage,
+        it assumes it's running in an emulator
+        and disables all the main menu options.
+  - Heuristics are difficult to reason about.
+      - If a homebrew developer
+        takes a game that almost does what they want
+        and changes it slightly,
+        it can result in the emulator
+        doing something completely different
+        because it now matches
+        some completely different game.
+  - Heuristics can make sensible configurations impossible.
+      - If a homebrew developer wants
+        a particular hardware configuration
+        that no official games happened to use,
+        it may not be possible
+        to trigger it heuristically.
+  - It's not hardware accurate.
+      - The original console did not use heuristics
+        to guess a hardware configuration,
+        it just used the actual configuration
+        of the actual hardware.
+
+Manifests provide a way to *tell* the emulator
+what hardware configuration to use,
+avoiding all these problems entirely.
+
+Where do manifests come from?
+-----------------------------
+
+Ideally,
+everybody who extracts the data from a game cartridge would
+(at the same time)
+record the board configuration in a manifest file.
+Unfortunately,
+manifests were invented long after cartridge extracting,
+so there are a lot of previously extracted games
+with no manifest attached.
+
+If a game doesn't come with a manifest,
+it may be possible to look up the correct manifest.
+The
+[SNES Preservation Project](https://preservation.byuu.org/)
+intends to re-dump every Super Famicom game
+and record its board configuration at the same time.
+Given a game's data,
+you can take the SHA256 fingerprint
+and look it up in the Project's database
+to find the correct manifest to use.
+
+Unfortunately,
+this doesn't help for any other console.
+Even for the Super Famicom,
+there will always be games
+too rare to acquire for re-dumping,
+and homebrew that was never on a cartridge to begin with.
+For these games,
+heuristics will always be needed as a fallback,
+but at least if the heuristics are wrong
+the can be overridden.
+
+Manifests can be found inside
+[game folders](game-folders.md),
+but usually aren't.
+Occasionally,
+a newly-dumped game will turn out to have
+a configuration that can't be expressed
+in the existing manifest file format,
+and a new format must be designed.
+If manifests were always written inside game folders,
+games with old-format manifests
+would break when played in emulators that supported the new format.
+
+Therefore,
+icarus [defaults](#the-icarus-settings-dialog)
+to not writing out manifests when it imports games,
+and higan [defaults](#the-configuration-dialog)
+to ignoring manifests that are present.
+Instead,
+when higan loads a game,
+it will ask icarus to generate a temporary manifest in the latest format,
+based on the files present in the game folder
+and how they are likely to go together.

mkdocs.yml

@@ -25,7 +25,8 @@ pages:
         - Using video shaders: guides/shaders.md
         - Choosing drivers: guides/drivers.md
     - Concepts:
-        - Manifests and Game Folders: concepts/game-folders.md
+        - Game Folders: concepts/game-folders.md
+        - Game Manifests: concepts/manifests.md
         - The Game Library: concepts/game-library.md
         - Save States: concepts/save-states.md
     - Frequently Asked Questions: faq.md