Finally finished reviewing and polishing all the text!

docs/concepts/game-folders.md

@@ -2,22 +2,8 @@ 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`
+to represent a Super Famicom game named `dkc3`,
-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`:
@@ -32,14 +18,30 @@ and the save data as `save.ram`:
       +- save.ram
 ```
 
+In contrast,
+other emulators typically
+group resources related to a game
+by requiring that every file has the same 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
+```
+
 Why game folders?
 -----------------
 
-The traditional files-with-different-extensions system
+A file extension doesn't offer
-works well enough when a game only requires
+much room for description,
-a small number of files,
+so the traditional name-based-grouping system
-because a file extension doesn't offer
+only really works when games use a small number of files,
-much room for description.
 Also,
 since file extensions traditionally describe
 the format of the file in question,
@@ -47,22 +49,23 @@ it also means a game can't use
 two or more files in the same format.
 
 Compared to other emulators,
-higan tends to use a larger number of files per game.
+higan can use a larger number of files per game.
 For example,
 higan's low-level emulation of Super Famicom co-processors
 often requires [separate firmware files][firmware].
 higan's [MSU-1 support][msu1]
-requires up to 99 audio tracks per game,
+supports up to 99 audio tracks per game,
 and higan supports up to 133 save-states per game.
-Therefore,
+Thus,
 higan suffers from the limitations of name-based-grouping
 more than most.
 
-higan's game folders allow all a game's resources
+higan's game folders allow a game
-to be given unique, descriptive filenames,
+to have unique, descriptive filenames
-and to use the file-extension
+for all its resources,
-that's most appropriate for that file.
+and for each file to use the extension
-They also allow emulator-specific data
+that's most appropriate.
+They also allow emulator-specific extras
 like save-states and the cheat database
 to be kept separate from the game's actual data,
 by putting it in a sub-folder.
@@ -78,12 +81,11 @@ see [Game Paks on the higan website][gp].
 What's in a game folder?
 ------------------------
 
-As mentioned above,
+A game folder collects all the information relevant
-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,
+are relevant for every console,
-or to every game on a given console,
+or even for every game on a console,
 but they may be present under particular circumstances.
 
 All the files directly in the game folder
@@ -114,12 +116,12 @@ to all emulators that support them:
     Games that include a save feature
     will create this file.
     Note that it is only written to disk
-    when higan exits gracefully,
+    when higan exits gracefully;
     if higan crashes or is forced to quit,
     in-game saves may be lost.
     Other emulators sometimes call this an "SRAM file",
     even though the same filename is used
-    for cartridges that use EEPROM or Flash storage,
+    with games that included EEPROM or Flash storage,
     not just battery-backed Static RAM.
   - `rtc.ram`:
     Games that include a calendar or real-time clock

docs/concepts/game-library.md

@@ -4,10 +4,10 @@ is the folder where all the
 When [icarus](../interface/icarus.md) imports a game,
 it creates or updates
 the corresponding game folder in the game library.
-When you use the console menu items
+When you use the console submenu items
 in [higan's Library menu](../interface/higan.md#the-library-menu),
 it higan shows you the games for that console
-already in the library.
+that are already in the library.
 
 Inside the game library folder
 there is a subfolder for each system.
@@ -75,7 +75,7 @@ and telling higan where to find them.
     where imported games will be stored.
  1. Launch higan,
     then from [the Settings menu][settingsmenu],
-    choose "Advanced..."
+    choose "Advanced ..."
     to open [higan's Advanced settings][advsettings].
  1. Click the "Change ..." button on the right.
     A [filesystem browser][fsbrowser] will appear,

docs/concepts/manifests.md

@@ -3,8 +3,8 @@ 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
+it connects all the other parts together
-talk to one another and to the console itself.
+and to the console itself.
 
 If you load a game into higan,
 you can look at the game's manifest
@@ -14,15 +14,14 @@ 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,
+a manifest isn't strictly necessary:
 the raw game data provides enough clues
-to guess a circuit board configuration
+for emulators to guess the circuit board configuration,
-that will get the game running,
+or at least
-but relying on heuristics often leads to problems:
+to guess a *reasonable* configuration.
+However,
+relying on such heuristics often leads to problems:
 
   - Inventing heuristics
     that correctly guess the configuration
@@ -47,10 +46,10 @@ but relying on heuristics often leads to problems:
       - If a homebrew developer
         takes a game that almost does what they want
         and changes it slightly,
-        it can result in the emulator
+        it may cause the emulator
-        doing something completely different
+        to do something completely different
-        because it now matches
+        because the modified game
-        some completely different game.
+        is now a closer match to some other game.
   - Heuristics can make sensible configurations impossible.
       - If a homebrew developer wants
         a particular hardware configuration
@@ -63,8 +62,9 @@ but relying on heuristics often leads to problems:
         it just used the actual configuration
         of the actual hardware.
 
-Manifests provide a way to *tell* the emulator
+Manifests provide a way to describe
-what hardware configuration to use,
+*exactly* what hardware configuration to use,
+no guessing required,
 avoiding all these problems entirely.
 
 Where do manifests come from?
@@ -72,8 +72,7 @@ Where do manifests come from?
 
 Ideally,
 everybody who extracts the data from a game cartridge would
-(at the same time)
+also record the board configuration in a manifest file.
-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
@@ -95,7 +94,7 @@ 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.
+and homebrew that was never on a physical cartridge to begin with.
 For these games,
 heuristics will always be needed as a fallback,
 but at least if the heuristics are wrong
@@ -128,12 +127,16 @@ If the manifest that icarus generates
 for some particular game
 is broken or buggy,
 you'll need to switch the manifest machinery back on
-so you can fix the problem:
+so you can fix it:
 
-  - Turn "Create manifests" back on in icarus' settings
+  - Turn on "Create manifests" in icarus' settings
-  - Re-import the game in question,
+  - Re-import the game in question
     to store the broken manifest
     as `manifest.bml` in the game folder.
-  - Edit `manifest.bml`
+  - Edit `manifest.bml` as you see fit
-  - Turn "Ignore manifests" off in higan's settings
+  - Turn off "Ignore manifests" in higan's settings
-  - Load the game in higan to check that your edit fixed the problem
+  - Load the game in higan to check that your changes fixed the problem
+
+If the manifest format changes in the future,
+you'll have to repeat this process
+to create a fixed manifest in the new format.

docs/concepts/save-states.md

@@ -109,8 +109,8 @@ or with the appropriate
 
 Quick states are useful
 as extra checkpoints
-in games that don't have them,
+in games whose checkpoints are too far apart,
-or where they aren't close enough together.
+or in games that don't have checkpoints at all.
 Map the "Save Quick State" and "Load Quick State" hotkeys
 to your controller,
 and you can cheese your way through just about anything.

docs/faq.md

@@ -6,10 +6,9 @@ to the display's vertical-synchronization (or "vsync") signal,
 but the option is hidden
 because it often causes more problems than it solves
 (see the next question).
-
 To enable video synchronization:
 
-  - Open the higan's configuration file, `settings.bml`
+  - Open higan's configuration file, `settings.bml`
       - On Windows, look in `%LOCALAPPDATA%\higan`
         or beside `higan.exe`
       - On Linux, look in `~/.local/share/higan`
@@ -50,8 +49,8 @@ the emulated console's refresh rate:
   - The Super Famicom usually runs a little faster than 60Hz
   - the PAL variants of most consoles run at 50Hz
   - the WonderSwan runs at 75Hz
-  - While the Game Boy does run its LCD at 60Hz
+  - While the Game Boy does run its LCD at 60Hz,
-    it can turn it off and on at any time,
+    games can turn the LCD off and on at any time,
     requiring emulation to pause
     until it can get back in sync
     with the computer display.
@@ -120,7 +119,7 @@ requires an Intel Ivy Bridge (or equivalent),
 full-speed for the wireframe animations in Mega Man X2
 requires an even faster computer.
 Low-power CPUs like ARM chips,
-or Intel Atom and Celeron CPUS
+or Intel Atom and Celeron CPUs
 generally aren't fast enough to emulate the Super Famicom with higan,
 although other emulated consoles may work.
 
@@ -168,11 +167,11 @@ Games can and do depend on timing details like
 it will interrupt the CPU at exactly the right time
 for the CPU to fiddle with the video chip".
 higan is therefore very cautious about timing:
-while it's emulating the audio chip (for example),
+while it's emulating the CPU (for example),
-at every point the emulated CPU *might* interrupt
+at every point the emulated audio chip *might* interrupt
-the emulated audio chip,
+the emulated CPU,
-higan switches to emulating the CPU up to the same point
+higan switches to emulating the audio chip up to the same point
-to find out whether the CPU *will* interrupt it.
+to find out whether it *will* interrupt the CPU.
 
 In this way,
 higan is a little bit like
@@ -180,8 +179,8 @@ an office-worker trying to do the jobs of three other people
 by running from desk to desk,
 sending the same emails
 that those three people would send to each other,
-leaving themselves a note at each desk to remind themselves
+leaving itself a note at each desk to remind it
-where they were up to when they come back.
+where it was up to when it comes back.
 Although this constant switching
 is slow and inefficient,
 higan does it
@@ -224,8 +223,8 @@ Why can't higan use multiple CPU cores?
 
 These days,
 most computers contain multiple CPU cores,
-allowing them to run different programs,
+allowing them to run different programs
-or different parts of the same program
+(or different parts of the same program)
 at the same time.
 Since higan requires high CPU performance,
 sometimes people suggest that it should split its work
@@ -257,26 +256,28 @@ do their work in exactly the same amount of time
 as their hardware counterparts.
 The problem is forty years of technology
 designed to make programs run as fast as possible:
-optimizing compilers and superscalar, out-of-order CPU architectures
+optimizing compilers
+and superscalar, out-of-order CPU architectures
 change programs to make them faster,
 speeding up some programs more than others
 in ways that are very difficult to understand and predict.
 Even if higan's emulated devices
 ran at the exact, correct speed
 on one particular computer,
-they'd still run differently on any other computer,
+they'd still run differently on
-or with a smarter compiler,
+a computer with a smarter CPU,
-or with a smarter CPU.
+or when compiled with a smarter compiler.
 
 Since higan needs its emulated components
 to run at particular speeds,
-and they won't run at those speeds naturally,
+and it's not practical
+to make them run at those speeds naturally,
 it must force them manually.
 An emulated device runs for a little while,
 then all the others are run until they catch up.
 It's this careful management,
 regular stopping and starting,
 that makes higan slow,
-not the actual emulation of each device,
+not the actual emulation of each device.
-and so it doesn't make sense
+Having multiple CPU cores waiting on each other
-for higan to be multi-threaded.
+would not help them wait any faster.

docs/guides/drivers.md

@@ -1,9 +1,8 @@
 Unfortunately,
-there's no standard for
+there's no cross-platform standard for
 displaying video,
 playing audio,
-and accepting input from game controllers
+and accepting input from game controllers.
-that works on every operating system.
 Or rather,
 there's many standards,
 and different ones work best
@@ -20,7 +19,7 @@ of the Settings window.
 
 Here are the most notable drivers
 for each platform
-for each category.
+in each category.
 If your copy of higan
 includes a driver not listed here,
 it's probably a reasonable choice,
@@ -44,11 +43,11 @@ Video
 
 On Windows:
 
-  - **OpenGL** is usually the best choice,
+  - **OpenGL** is the best choice,
-    since it supports [custom shaders](shaders.md),
+    since it's fast
-    however it does require support for OpenGL 3.2
+    and it supports [custom shaders](shaders.md),
-    which excludes some integrated graphics chipsets
+    but requires support for OpenGL 3.2.
-    and old graphics cards.
+    This excludes some older and weaker hardware.
   - **Direct3D** is a good choice
     if OpenGL is unavailable.
     It also allows
@@ -62,7 +61,7 @@ On Linux:
   - **OpenGL** is the best choice,
     since it's fast
     and it supports [custom shaders](shaders.md),
-    but requires OpenGL 3.2.
+    but requires support for OpenGL 3.2.
     You can check what version of OpenGL
     your system supports by running
     `glxinfo | grep 'core profile version'`
@@ -82,7 +81,7 @@ On Windows:
   - **ASIO** offers the lowest possible latency,
     but is the least likely to work on any given computer.
   - **WASAPI** offers low latency,
-    but is only slightly more likely to work.
+    but is only slightly more likely to work than ASIO.
     It also offers
     [Exclusive Mode](../interface/higan-settings.md#audio),
     which can improve audio quality and lower latency,

docs/guides/import.md

@@ -219,8 +219,8 @@ and one that uses the DSP1B,
 so if it cannot find your game in its manifest database,
 it will assume it uses DSP1B.
 Many games work just as well with either variant,
-but Pilotwings requires the DSP1 firmware,
+but *Pilotwings* requires the DSP1 firmware,
-while Ballz 3D requires the DSP1B.
+while *Ballz 3D* requires the DSP1B.
 
 If you try to import a game
 using the "Import ROM Files ..." option

docs/notes.md

@@ -1,24 +1,21 @@
 The consoles that higan emulates
 are similar in many ways,
-but some of them do have particular quirks
+but some of them do have particular quirks of their own.
-that you should be aware of.
 
 Music and Sound Effect Volume on the Mega Drive
 -----------------------------------------------
 
 The Mega Drive has two different audio-generating chips:
 
-  - the SN76489 or "PSG" chip,
+  - the SN76489 or "PSG" chip
     inherited from the Master System,
     mostly used for sound-effects
-    like Sonic picking up rings
   - the YM2612 or "FM" chip,
     mostly used for music
 
 With two different sound sources,
-it's important that they have similar volumes,
+it's important that they have similar volumes
-or the sound-effects will drown out the music,
+or one kind of sound will drown out the other.
-or vice-versa.
 Sega did *not* do this,
 and different hardware revisions
 used different relative volumes.
@@ -26,8 +23,8 @@ used different relative volumes.
 higan currently
 sets the PSG volume to [125% of the FM volume][vol],
 based on [a Sega Genesis model 1 VA6][va6] that byuu owns.
-If you feel sound-effects in higan's Mega Drive core
+If you feel sound-effects in higan's Mega Drive emulation
-are too loud or too quiet,
+are too loud or too quiet compared to the music,
 you may be comparing it
 to a Mega Drive calibrated to a different scale
 (or to an emulator tweaked to match such a Mega Drive).
@@ -50,7 +47,7 @@ Games that required
 the extra hardware in the Game Boy Color
 came in transparent cartridges,
 and had a slightly different shape
-to prevent them from being used in original Game Boys..
+to prevent them from being used in original Game Boys.
 ROM files for these games
 typically have filenames ending in `.gbc`.
 
@@ -117,17 +114,9 @@ higan must guess which storage type to use
 and sometimes it guesses incorrectly.
 
 If higan guesses incorrectly for a game you want to play,
-you will need to turn on
+you will need to override the automatically-generated manifest.
-"Create manifests" in
+See [Ignoring manifests](concepts/manifests.md#ignoring-manifests)
-[the Icarus settings dialog](interface/icarus.md#the-icarus-settings-dialog),
+for details.
-turn off
-"Ignore manifests" in
-[higan's Advanced settings](interface/higan-settings.md#advanced),
-re-import the game,
-and edit `manifest.bml` in
-[the game folder](concepts/game-folders.md)
-to describe the correct storage type.
-Try importing other GBA games to see what save types they use.
 
 For more discussion of the GBA save type mess,
 see [What's the deal with... GBA save files?][gbasaves]
@@ -145,7 +134,7 @@ included a rumble motor within the cartridge itself.
 Because higan does not currently support
 game-specific controller features,
 to experience the rumble effect in higan
-you'll need to configure the console itself:
+you'll need to configure the console:
 
   - Open
     [higan's Input settings](interface/higan-settings.md#input)